Skip to content

Keycloak as Identity Provider

This guide will help you set up Keycloak as an identity provider for the Capella Collaboration Manager (CCM). It focuses on setting up the connection between Keycloak and CCM. The setup of the connection between Keycloak and your identity provider is not covered.

Install Keycloak

If you don't already have a running Keycloak server, please follow the installation instructions in Keycloak - Getting Started.

After this step, you should have access to the Keycloak admin console, which is required for the following steps.

Register the CCM Client in Keycloak

  1. Below Manage click on Clients and then Create client:
    Create client

  2. In General settings set the values as follows:

    Key Value
    Client type OpenID Connect
    Client ID capella-collaboration-manager
    Name Capella Collaboration Manager
    Description Client used to authenticate users in the Capella Collaboration Manager
    Allow display in UI Personal preference

    Create client - Step 1

  3. In Capability config modify the default values as follows:

    1. Enable Client Authentication
    2. Disable Direct access grants

    Create client - Step 2

  4. In Login settings set the values as follows:

    Key Value Example value
    (development environment)
    Root URL +
    Home URL +
    Web origins    		 {scheme}://{host}:{port}
    (URL of the CCM frontend)    		 http://localhost:4200
    Valid redirect URIs {scheme}://{host}:{port}/oauth2/callback http://localhost:4200/oauth2/callback
    Valid post logout redirect URIs None -

    Create client - Step 3

  5. Click Save, which should create the client in Keycloak.

  6. Make the email claim optional. It is not required for the CCM.

    1. In the Clients tab, open the client details of the newly created client
    2. Click on Client scopes
    3. For the email scope, change the Assigned Type from Default to Optional

    Create client - Step 4)

Configure the CCM to use the Keycloak Client

Update the values.yaml and set the following values for the backend.authentication section:

backend:
  authentication:
    endpoints:
      wellKnown: [...]/.well-known/openid-configuration # (1)!

    claimMapping: # (2)!
      idpIdentifier: sub
      username: preferred_username
      email: email

    scopes:
      - openid
      - profile
      - offline_access

    client:
      id: capella-collaboration-manager # (3)!
      secret: ... # (4)!

    redirectURI: [...]/oauth2/callback # (5)!
  1. To find out the well-known endpoint, click Realm Settings in Keycloak, scroll down and click OpenID Endpoint Configuration, which should open the configuration in a new tab. The well-known endpoint is the URL of the opened page.
  2. Make sure that the mentioned claims are available in the identity token. You can evaluate the claims available in the token via Keycloak: Open the client details, click on the Client scopes tab and navigate to "Evaluate".
  3. Set the client.id to the value used when the client was created. If not changed it should be capella-collaboration-manager.
  4. To find out the client secret, open the client details in the Keycloak admin console. Open the Credentials tab and copy the Client Secret. Keep this value confidential and generate a new client secret in case it gets leaked.
  5. Set the redirectURI to the CCM base url + /oauth2/callback

Then redeploy the application using Helm.