Keycloak

It is possible to use Keycloak as an external identity provider and delegate the authentication of user from map.apps to Keycloak using the OAuth 2.0 protocol. This means that a user can log in to map.apps with an account managed by Keycloak.

Using Keycloak creates the following possibilities:

  • Assignment of roles for the use of map.apps Manager

  • Protection of apps

  • Protection of tools

Using Keycloak has the following limitations:

  • Apps exported with the app export for native apps do not support the authentication. Apps with anonymous access are still supported.

Configuration of the connection

To be able to use Keycloak as an external identity provider three steps are required:

  1. First, you register map.apps as a client in Keycloak.

  2. Then, you adjust the configuration of map.apps, so that it can delegate the authentication to Keycloak.

  3. Finally, you configure your apps to use the authentication information.

The following description is based on version 20.0.1 of Keycloak.

Step 1: Register map.apps in Keycloak

map.apps must be registered as a client in a Keycloak installation to allow logging in to map.apps 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 map.apps as a client:

Create a client

  1. Log in to the admin console of Keycloak with your administrator account.

  2. Select the desired realm.

  3. Select Clients.

  4. Click Create Client to create a new client.

  5. Use the following settings in the General Settings tab:

    • Client type: OpenID Connect

    • Client ID: mapapps

  6. Click Next

  7. Use the following settings in the Capability config tab:

    • Client authentication: On

    • Standard flow: On

  8. Click Save. The Settings tab of the newly created client is shown.

  9. Apply the following settings to further configure the client:

    • Root URL: URL of your map.apps installation, for example https://example.com/mapapps

    • Valid redirect URIs: Specify the account path of map.apps, for example https://example.com/mapapps/account/*

    • Front channel logout: Off

    • Backchannel logout URL: Specify the logout endpoint of map.apps, for example https://example.com/mapapps/account/logout

  10. Click Save

  11. Switch to the Credentials tab.

    • Note the displayed client Client secret at any position. It is later required for the configuration of map.apps.

Add roles

map.apps uses the following roles to authorize users:

  • maAdmin: Users with this role assigned are allowed to administer map.apps

  • maEditor: Users with this role assigned are allowed to use map.apps as editors.

Create these roles in Keycloak as follows:

  1. Switch to the Roles tab of the client.

  2. Add the roles maAdmin and maEditor by clicking on Create role.

Create a Mapper

map.apps 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:

  1. Click Client scopes in the navigation menu.

  2. Click on the roles entry of the OpenID Connect protocol.

  3. In the following roles view switch to the Mappers tab.

  4. Click Add mapper and then By configuration to create a new mapper.

  5. Click on the User Client Role mapping from the list.

  6. The configuration of the mapping is shown.

  7. Use the following settings for the mapper:

    • Mapper Type: User Client Role

    • Name: mapapps client role mapper

    • Client ID: Select the entry mapapps 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

  8. Click Save

The configuration of the client is now complete.

Assign roles to Keycloak users

Assign the previously created roles to Keycloak users or groups who will edit or administer map.apps.

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

  1. Click Users in the navigation menu

  2. Select the desired user. The Details page of that user is shown.

  3. Switch to the Role mapping tab.

  4. Click on Assign role.

  5. Set the filter to Filter by clients.

  6. Select the roles you want to assign to the user.

  7. Click Assign.

  8. A message should appear, that the user has been saved successfully.

  9. The role should be visible in the list of roles of that user.

After you have assigned the roles, you can proceed to the next step, configuring map.apps.

Step 2: Configuration of map.apps

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

Configuration example
security.mode=OAUTH
security.oauth.provider=keycloak
# The Keycloak url depends on the Keycloak version, see description below
security.oauth.provider.keycloak.url=http://keycloak.example.com
security.oauth.provider.keycloak.realm=yourrealm
security.oauth.clientId=mapapps
security.oauth.clientSecret=NJrrsZXVm8CvnhF7owT6m50CXhbnN55w
# Replace "0123456789" with an arbitrary string of at least 32 characters
security.sharedSecret=0123456789
security.mode

The value OAUTH specifies that the the OAuth 2.0 protocol is used for authentication.

security.oauth.provider

The value keycloak specifies that Keycloak should be used as identity provider.

security.oauth.provider.keycloak.url

URL of your Keycloak deployment, for example http://keycloak.example.com.

If you are using Keycloak version 16 or earlier, you have to append /auth to this path, for example http://keycloak.example.com/auth.

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.

security.sharedSecret

The text you enter here will be used by map.apps as a key for encrypting data that needs to be exchanged between different parts of the application. To prevent unauthorized access or manipulation of data you should keep this secret private, like a password. You must create this key yourself. It must have a length of at least 32 characters for security reasons.

You can create a secure key with these commands, for example:

Windows PowerShell
> [Convert]::ToBase64String((1..32|%{[byte](Get-Random -Minimum ([byte]::MinValue) -Maximum ([byte]::MaxValue))}))
Linux
$ openssl rand -base64 32

In a scenario where, for example, multiple application instances are used for load balancing, all instances must use the same value.

Step 3: Configure your apps

Finally, add the authentication bundle to each app where a login should be performed via Keycloak.