Connecting Keycloak

Using the OAuth 2.0 protocol, the Identity Service can delegate the authentication of users to Keycloak . This means that a user can log in with an account managed by Keycloak.

Connecting to Keycloak is done in three steps:

First, you register the Identity Service as a client in Keycloak.
Then, you adjust the configuration of the Identity Service, so that the Login can be delegated to Keycloak.
Finally, you configure other con terra products to use the Identity Service.

The following description is based on version 21.1.1 of Keycloak.

Step 1: Register Identity Service

The Identity Service must be registered as a client in a Keycloak installation to allow login with an account managed by Keycloak.

The client is created within a so called realm. The following description assumes that a realm has already been created.

Extensive configuration options are available for a client. We assume that properties not mentioned in the following descriptions have an appropriate default value.

Proceed as follows to register Identity Service as a client:

Create a client

Log in to the admin console of Keycloak with your administrator account.
Select the desired realm.
Select Clients.
Click Create Client to create a new client.
Use the following settings in the General Settings tab:
- Client type: OpenID Connect
- Client ID: identity-service
Click Next
Use the following settings in the Capability config tab:
- Client authentication: On
- Standard flow: On
Click Next.
- Root URL: URL of your Identity Service installation, for example https://www.example.com/identity
- Valid redirect URIs: Specify the account path of Identity Service, for example https://www.example.com/identity/account/*
Click Save. The Settings tab of the newly created client is shown.
Apply the following settings to further configure the client:
- Front channel logout: Off
- Backchannel logout URL: (Optional) Specify the logout endpoint of Identity Service, for example https://www.example.com/identity/account/logout
Click Save
Switch to the Credentials tab.
- Note the displayed client Client secret at any position. It is later required for the configuration.

Step 2: Configure Identity Service

The following parameters must be added or changed in the global Configuration.

Configuration example

# .identity-service/application.properties
security.oauth.provider=keycloak
security.oauth.provider.keycloak.url=http://keycloak.example.com
security.oauth.provider.keycloak.realm=yourrealm
security.oauth.clientId=identity-service
security.oauth.clientSecret=NJrrsZXVm8CvnhF7owT6m50CXhbnN55w

security.oauth.provider: The value keycloak specifies that Keycloak is the identity provider.
security.oauth.provider.keycloak.url: URL of your Keycloak deployment, for example http://keycloak.example.com.
security.oauth.provider.keycloak.realm: Name of the realm.
security.oauth.clientId: ID of the Keycloak client defined in step one.
security.oauth.clientSecret: Secret of the Keycloak client defined in step one.

The secret is displayed in the Credentials tab of the client in Keycloak.

Step 3: Set up roles

They may need to provide additional roles in keycloak as products are connected. For example, map.apps expects the role maAdmin for an administrative user. This role must be made known in Keycloak.

Add roles

Create roles in Keycloak as follows:

Switch to the Roles tab of the client.
Add the role maAdmin by clicking on Create role.

Create a Mapper

The Identity Service uses Keycloak’s User Information endpoint to query roles of users. By creating a mapper, you ensure that the roles created in the previous step are returned from this endpoint. Proceed as follows to create a mapper:

Click Client scopes in the navigation menu.
Click on the roles entry of the OpenID Connect protocol.
In the following roles view switch to the Mappers tab.
Click Add mapper and then By configuration to create a new mapper.
Click on the User Client Role mapping from the list.
The configuration of the mapping is shown.
Use the following settings for the mapper:
- Mapper Type: User Client Role
- Name: identity-service client role mapper
- Client ID: Select the entry identity-service from the list of clients
- Client Role prefix: Leave this field empty.
- Multivalued: ON
- Token Claim Name: roles
- Claim JSON Type: String
- Add to userinfo: ON
Click Save

Assign roles to Keycloak users

If you want to assign roles to a single Keycloak user, proceed as follows:

Click Users in the navigation menu
Select the desired user. The Details page of that user is shown.
Switch to the Role mapping tab.
Click on Assign role.
Set the filter to Filter by clients.
Select the roles you want to assign to the user.
Click Assign.
A message should appear, that the user has been saved successfully.
The role should be visible in the list of roles of that user.

Step 4: Test configuration

You can test the configuration of Keycloak as identity provider by performing a login initiated by the Identity Service. Follow these steps:

Make sure you have a Keycloak user account
If you are logged in to Keycloak, log out.
Open the Identity Service base URL, http://www.example.com/identity or http://www.example.com:8080/identity, for example. Make sure to use the exact same URL that you specified as Root URL when registering the Identity Service at Keycloak in step 1 of this document.

The browser displays a page with a list of available service endpoints:
Click the link titled Login. The browser will redirect you to the Keycloak login page.
Enter username and password of your Keycloak account to login.

After successful login you are redirected to the Identity Service "Self" endpoint (/identity/account/self). If your Keycloak account data is displayed as JSON, you successfully connected Keycloak with the Identity Service.

Next steps

After you have connected Keycloak with the Identity Service, you need to configure services, which require an access token, as trusted services in the Identity Service. This allows users of applications, which make use of the Identity Service, to access these trusted services without further login.