Skip to content

How to configure Keycloak for the SCL#

This document describes how to adjust an existing Keycloak service to enable the SCL use-case. Setting up and securing Keycloak from scratch is not covered here. See the official Keycloak documentation to learn more about best (security) practices.

Info

This guide is known to work with Keycloak version 22.0.1.

General settings#

Settings independent of particular Separation Contexts.

Remove or disable rsa-enc-generated Realm key provider#

In the Realm settings, remove or disable the key provider rsa-enc-generated. This will also remove or disable the RSA-OAEP key.

Info

The RSA-OAEP key causes problems with the OAP.

Create a Client for the Infrastructure Management API#

Create an OpenID Connect Client for the Infrastructure Management API.

Complete the creation dialog#

The form to create clients consists of three pages. Adjust the settings on the first page (called General Settings) as follows:

Field Value
Client type OpenID Connect
Client ID infrastructure-management-api

Proceed with the default settings on the remaining pages.

Remove unused scopes in the Client scopes tab#

Remove the following claims from default scopes:

  • email
  • roles
  • profile
  • web-origins

Remove the following claims from optional scopes:

  • address
  • phone

Create a Mapper via the Client scopes tab#

We need a Mapper that encodes separation-context-id User attribute values into JWT claims.

In the Client scopes tab of infrastructure-management-api, click on the automatically created scope infrastructure-management-api-dedicated in order to open the Dedicated scopes page.

Click on Configure a new mapper and select the User Attribute entry.

Enter the following values into the formular and save the changes.

Field Value
Mapper type User Attribute
Name separation-context-id-attribute
User attribute separation-context-id
Token claim name scid
JSON type String
Add to ID token no
Add to access token yes
Add to userinfo no
Multivalued no
Aggregate attribute values no

Separation Context Management#

Create a Group for each Separation Context#

Access permissions for Separation Contexts are represented via Group memberships.

For each Separation Context:

  1. Create a Group using the name of the Separation Context prefixed by sc_ as the name of the Group.
  2. Open the newly created Group, switch to the Attributes tab and Add an attribute:
Key name Value
separation-context-id <name of the Separation Context>

Associate Users with Groups#

Users need to be associated with Groups representing Separation Context access permissions. This can be done during User creation via the Join Groups button or afterward via the Groups tab of the User details page.

Test the setup#

The following test can be used to check that the scid claim gets properly included by the Mapper of the infrastructure-management-api Client.

It assumes a User with username / password being test / test that is member of a Group representing a Separation Context a.

# Start a nix-shell with a tool to work with JWTs
nix-shell -p jwt-cli

# Acquire JWT
TOKEN=$(curl 'https://<keycloak-instance>/realms/<realm>/protocol/openid-connect/token' \
  --data-urlencode grant_type=password \
  --data-urlencode username=test \
  --data-urlencode password=test \
  --data-urlencode client_id=infrastructure-management-api | jq -r '.access_token')

# View content of the token using https://github.com/mike-engel/jwt-cli
jwt decode $TOKEN

The output should show the scid property with the expected Separation Context:

Example output (some fields were omitted for brevity)
Token claims
------------
{
  "azp": "infrastructure-management-api",
  "scid": "a",
  "scope": "",
  "typ": "Bearer"
  ...
}