Configure Keycloak for use with the API Server

Steps to configure a keycloak realm to issue suitable tokens for the API Server.

Create a new realm

Configure Organizations - Add groups

Currently organizations are not propagated to the IdP. You need to add organizations manually. In Keycloak we use the groups concept to represent an organization.

The example below adds a my-org organization:

Add a user

First add a user, then on the newly created user set the password -

Add client configuration for the API Server

Add a new client and set the callback url and web-origin (for CORS). Use the correct host name and port according to your deployment.

Add roles to the client

Now we need to add the roles (org-admin, platform-admin) to the client

Add roles to user

Navigate to the user you created and switch to the role mappings tab - then in the “client roles” field select the name of the client you created (in the example platform-api-server). This will load the roles and you can assign both of the roles created previously to the user

Add groups to user

Navigate to the user you created and switch to the groups tab. Add the my-org group to the user:

Add mappers to the client

The issued JWT token must include the roles and groups as well as the audience (aud) claim. We need to set up mappers for these attributes.

Add groups (organizations) mapper

Click “Create” to add a new mapper. Set the new mapper up as follows:

Add audience (aud) mapper

Click “Create” to add a new mapper. Set the new mapper up as follows:

Modify the Client Scope settings

Disable “Full Scope Allowed”:

Setup the Client Scopes

Go to the “Client Scopes” tab of your client and the sub-tab “Setup”. Set the default and optional client scopes as shown below:

Preview the JWT token

Go to the “Client Scopes” tab of your client and the sub-tab “Evaluate”. Select the user you created previously:

Then you can preview the token, check that it contains the right aud, resource_access / roles and organizations attributes:

Here is an example:

{
  "exp": 1619689009,
  "iat": 1619688709,
  "jti": "dd8c2095-e96f-4ee8-96c6-f3262b1508f9",
  "iss": "http://localhost:8180/auth/realms/apim-connector",
  "aud": "platform-api-server",
  "sub": "bfd13823-9987-446c-b4f8-5f9793be50bf",
  "typ": "Bearer",
  "azp": "platform-api-server",
  "session_state": "297121ef-77d0-4d3d-85ef-64ab2c9ef208",
  "acr": "1",
  "resource_access": {
    "platform-api-server": {
      "roles": [
        "org-admin",
        "platform-admin"
      ]
    }
  },
  "scope": "openid profile",
  "organizations": [
    "my-org"
  ],
  "name": "Harry H",
  "preferred_username": "harry",
  "given_name": "Harry",
  "family_name": "H"
}

Configure the API Server

Properties for claim and username extraction:

AUTH_EXTRACTION_USER_PRINCIPAL=$.preferred_username

Will evaluate to “harry” given the JWT example above.

AUTH_EXTRACTION_ORGS=$.organizations

Will evaluate to

[
    "my-org"
  ]

AUTH_EXTRACTION_ROLES=$.resource_access['platform-api-server'].roles

Will evaluate to

[
        "org-admin",
        "platform-admin"
      ]

Properties for JWT verification

AUTH_VERIFICATION_AUD=platform-api-server

Must match the aud property in the JWT token - see example above

AUTH_VERIFICATION_ISSUER=http://localhost:8180/auth/realms/apim-connector

The URL of your keycloak realm, apim-connector is the realm name. Replace if you use another realm.

AUTH_VERIFICATION_KEY=/Users/swenhelge/platform-api-tmp/keycloak_local_key.pem

The location of public key used by keycloak - you need to download it from the “Realm Settings” in keycloak:

Set the OpenId Connect Discovery URL

Will be in the format below. Replace host, port and realm (apim-connector in the example below) with the correct values for your deployment:

AUTH_DISCOVERY_OIDC_URL=http://localhost:8180/auth/realms/apim-connector/.well-known/openid-configuration