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.

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 to create a new client. Use the following settings:

    • Client ID: mapapps

    • Client Protocol: openid-connect

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

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

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

    • Access Type: confidential

    • Standard Flow Enabled: ON

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

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

  7. Click Save

  8. Switch to the Credentials tab.

    • Note the displayed 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.

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. Switch to the Mappers tab of the client.

  2. Click Create to create a new mapper.

  3. Use the following settings for the mapper:

    • Name: mapapps client role mapper

    • Mapper Type: User Client Role

    • Client ID: Select the entry mapapps from the list of Client Roles.

    • Client Role prefix: Leave this field empty.

    • Token Claim Name: roles

    • Claim JSON Type: String

    • Multivalued: ON

    • Add to userinfo: ON

  4. 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 Mappings tab.

  4. Select the mapapps client from the Client Roles list.

  5. Select the role you want to assign in the Available roles area

  6. Click Add selected.

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

  8. The role should be visible in the Assigned 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.