Skip to content

Keycloak¤

Introduction¤

This page describes important steps in order to configure Keycloak as an authentication backend for Corporate Memory. The screenshots displayed in this documentation were taken from Keycloak v20 using the keycloak.v2 theme.

Info

You do not need these instruction in case you followed the documentation on Scenario: Local Installation or Scenario: Single Node Cloud Installation (in this case, everything was done automatically). However, in case you need to integrate Corporate Memory with an existing Keycloak, this page may help you. Please also have the Keycloak - Server Administration Guide ready 😄

Realm configuration¤

Warning

A realm can be im-/exported. However, exported realms will not contain user credentials.

To create a realm, use the drop down menu for choosing a realm on the left side.

  • Create a realm cmem
    • Select Realm settings
    • General tab:
    • Change HTML Display name to <span class="ecc-logo"></span>Corporate Memory
    • Themes tab
    • Switch realm’s login theme to eccenca
    • Switch realm’s account theme to eccenca

Client configuration¤

Clients are used to link users and groups managed in Keycloak to Corporate Memory. There are two different clients used by Corporate Memory:

  • The first client is used to authenticate a user for using the web interface (usually named cmem).
  • The other client is used as a technical user with the command line interface (typically named cmem-service-account). Depending on the environment, there might be other use cases, when running background schedules, then a third client, also as technical user, might be useful.

Access conditions, roles and groups¤

Corporate Memory uses access conditions which are related to users or groups. This is described at Access Conditions. To use groups from Keycloak in Corporate Memory access conditions, all Keycloak client configurations need to have attached mappers:

  • For the web interface client (cmem), the user groups need to get attached to the client. This is done by a Group Membership mapper (described below). With this mapper each group of a user is assigned for the authentication process, so Corporate Memory is aware of the user and group IDs for setting up access conditions.

  • For the technical account clients (such as cmem-service-account), Keycloak does not allow to add groups directly to a client. To work around this limitation, we are using ROLES instead. By creating a mapper to re-define roles from groups, we allow Corporate Memory to read roles as groups attached to the client token.

In the default setup in helm or docker compose deployments, we often refer to the elds-admins group, acting as a super-admin / root group. Every user in this group has all possible rights in Corporate Memory, no matter which access conditions are available. This is configured in the DataPlatform configuration or as an environment variable AUTHORIZATION_ABOX_ADMINGROUP=elds-admins (see also Dataplatform configuration authorization).

Option 1: Import the needed clients from a JSON export¤

To import a pre-configured cmem client for using the web interface, follow these steps:

Dialog import cmem client

  • Login to Keycloak and select the Corporate Memory realm (cmem).
  • Download the client configuration for using the web interface (cmem.json).
  • Select Clients, then Import client.
  • Browse for the downloaded cmem.json and select it.
  • Save new client.

To import a pre-configured cmem-service-account client, repeat the process with the client configuration with credentials for the technical account (cmem-service-account) (cmem-service-account.json).

Option 2: Create client configurations manually¤

Add the cmem client for using the web interface¤

This client is intended for the usage with DataManager, DataPlatform and DataIntegration (user login):

Dialog create cmem client

  • Client type: OpenID Connect
  • Client ID: i.e. cmem, you need to remember this and use this later
  • Name and Description: fill as you like
  • Select Next
  • Client authentication: Off
  • Authorization: Off
  • Enable Standard Flow Enabled (enables OAuth 2.0 Authorization Code Flow)
  • Before v23.1:
    • Additionally enable Implicit Flow Enabled
  • Save

Dialog create cmem client

The dialog above closes and you land on the configuration page of this client:

  • Valid redirect URIs: Add the correct URL pattern (e.g., wildcard https://cmem.example.net/* works) to Valid Redirect URIs (* for testing purposes can be used as well) and Save
  • Switch the Tabs to Client scopes and click on the first scope (i.e.: cmem-dedicated)

Dialog select cmem-service-account-dedicated Dialog create mapper Dialog create mapper

  • Click Configure a new mapper
    • Select Mapper Type Group Membership
    • Name groups
    • Token Claim Name groups
    • Disable Full group path
    • Disable Add to ID token
    • Enable Add to access token
    • Enable Add to user info
  • Save

Dialog create mapper

  • In Corporate Memory configuration until v22.2:
    • Configure this client ID under js.config.workspaces.default.authorization.oauth2.clientId in DataManager’s configuration file (Datamanager needs implicit flow)
    • Configure this client ID under oauth.clientId = "cmem" in DataManager’s configuration file (Dataintegration needs standard flow)
  • In Corporate Memory configuration from v23.1:
    • Configure this client ID in the environments with the name OAUTH_CLIENT_ID in /environments/config.env (defaults to cmem if not set)

Add the cmem-service-account client¤

This client is intended for internal use by DataIntegration (scheduler super-user) and data import purposes (cmemc).

This descriptions can also be used to create clients with different permissions than admins. For this, just create a different role name later, and create an access condition with this groups name in Corporate Memory as it is described in Access Conditions.

Dialog create role Dialog create role Dialog create role

  • Client type: OpenID Connect
  • Client ID: i.e. cmem-service-account, you need to remember this and use this later
  • Name and Description: fill as you like
  • click Next
  • Client authentication: On
  • Authorization: Off
  • Authentication flow: only enable Service accounts roles, the rest can be disabled
  • Save

  • Go to Credentials and configure Client Id and Secret, copy the client secret for later usage

Dialog create role

  • Go to Roles and click Create role to create the elds-admins role

Dialog create role Dialog create role

  • Click Action and select Add associated roles

Dialog create role

  • Select Filter by client from the filter pull-down-menu

Dialog create role

  • In this dialog select the client by name which you are currently configuring (here cmem-service-account) and then Assign

Dialog create role

  • Go back to Client details e.g., by using the top navigation
  • In the Roles tab you now see your created role here

Dialog create role

  • Switch the Tabs to Client scopes and click on the first scope (i.e.: cmem-service-account-dedicated)

Dialog create mapper

  • select Add mapper -> By configuration

Dialog create mapper

  • select Mapper Type User Client Role
    • Name roles
    • Client ID select the client you are currently configuring from the pull-down-menu (here cmem-service-account)
    • Enable Multivalued
    • Token Claim Name groups
    • Enable Add to ID token
    • Enable Add to access token
    • Enable Add to user info
  • Save

Dialog create mapper

Dialog create mapper

  • After Save go back to Client details
  • Go to tab Service account roles tab
  • Select the link in the center To manage detail and group mappings, click on the username service-account-YOUR_CLIENT_ID

Dialog add role to client

  • Go to tab Role mapping and select Assign role

Dialog add role to client

  • Change the filter to Filter by clients and select the new Client ID, i.e cmem-service-account
  • Click Assign

Dialog add role to client Dialog add role to client Dialog add role to client

Corporate Memory configuration after setting up clients¤

  • If DataIntegration schedulers are required, configure this client id and secret under the properties workbench.superuser.client and workbench.superuser.clientSecret in DataIntegration’s configuration file or
  • in docker compose-orchestration you can edit this in the environment as:
      CMEM_SERVICE_ACCOUNT_CLIENT_ID=cmem-service-account
      CMEM_SERVICE_ACCOUNT_CLIENT_SECRET=YourSecret
      DATAINTEGRATION_CMEM_SERVICE_CLIENT=cmem-service-account
      DATAINTEGRATION_CMEM_SERVICE_CLIENT_SECRET=YourSecret
    
  • in helm this value is defined by:
      DATAINTEGRATION_CMEM_SERVICE_CLIENT_SECRET: {{ .Values.global.cmemClientSecret }}
      DATAINTEGRATION_CMEM_SERVICE_CLIENT: {{ .Values.global.cmemClientId }}
    
  • For cmemc you can configure this with OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET.

Groups configuration¤

  • Go to Groups and add the following groups:
  • These groups are used only to assign them to user accounts (clients have roles-to-group mappers).
  • elds-admins
  • Any groups provided by your user management system (e.g. LDAP) that must be recognized/mapped by Keycloak
  • In Corporate Memory docker orchestration, local-userslocal-admins

Users configuration¤

  • This applies to the Docker Orchestration, for other setups consult the Keycloak manual.
  • Go to Users
  • Add the following users and assign their groups respectively (for each user go to credentials, add password and disable Temporary)
  • user:user
    • groups: local-users
  • admin:admin
    • groups: local-admin

Comments