Configure Keycloak for the Desk API

Learn how to set up Keycloak for the Desk API.

The Desk API accepts user mangagement integration from Keycloak. This guide describes how to configure Keycloak to work with the Desk API.

Prerequisites

• You have a Keycloak account and admin privileges.

1

Configure the realms

1. Create a new realm, for example desk.

2. Select the master realm and create a new client with the following settings:

   • Client type: OpenID Connect
   • Client ID: CLIENT_ID
   • Name: CLIENT_NAME
   • Client authentication: On
   • Authentication flow: Select the Standard flow and Direct access grants checkboxes

   All other fields can be left empty or with default value. Replace CLIENT_ID and CLIENT_NAME with the name you want for your Desk API client.

3. Select the newly created client, open the Credentials tab and click Regenerate client secret.

4. Select the desk realm and create a new client with the following settings:

   • Client type: OpenID Connect
   • Client ID: CLIENT_ID
   • Name: CLIENT_NAME
   • Client authentication: On
   • Authorization: On
   • Authentication flow: Select the Standard flow and Direct access grants checkboxes

   All other fields can be left empty or with default values. Replace CLIENT_ID and CLIENT_NAME with the same values used in step (2).

5. Select the newly created client, open the Credentials tab and click Regenerate client secret.

2

Add new client scope to client

1. Select the desk realm, click Client scopes and create a new client scope with the following configurations:

• Name: group
• Type: default
• Protocol: OpenID Connect
• Include in token scope: On
• Display on consent screen: On

2. Select the group client scope, open the Mappers tab and click Configure a new mapper. Create three new mappers with the following settings:

• group_role

  • Mapper type: User Attribute

  • Name: group_role

  • User attribute: group_role

  • Token Claim Name: group_role

  • Claim JSON Type: String

  • Select the following checkboxes:

    • Add to ID token
    • Add to access token
    • Add to userinfo
    • Multivalued
    • Aggregate attribute values

  All other fields can be left empty or with default values.

• Group

  • Mapper type: Group membership

  • Name: Group

  • Token Claim Name: groups

  • Select the following checkboxes:

    • Full group path
    • Add to ID token
    • Add to access token
    • Add to userinfo

  All other fields can be left empty or with default values.

• group_membership

  • Mapper type: Group membership

  • Name: group_membership

  • Token Claim Name: group_membership

  • Select the following checkboxes:

    • Full group path
    • Add to ID token
    • Add to access token
    • Add to userinfo

  All other fields can be left empty or with default values.

3. Add the new client scope to client.

• Still in the desk realm, select the client created in the previous section.
• Open the Client scopes tab.
• Click Add client scope.
• Select the group client scope and click Add.

3

Create groups

For each organization in the Desk API, create a Group and create Roles for that group.

1. Select the desk realm, select Groups and click Create group.

2. Enter a GROUP_NAME and click Create.

3. Select the created group and select the Attributes tab.

4. Add the following attributes:

   • display_name: Choose a display name for the organization
   • core_id: Provide a random UUID for the organization

5. In the realm admin panel, select Realm roles.

6. Create two roles:

   • GROUP_NAME_READER: Users with this role assigned can read data in this organization but not write or create entities
   • GROUP_NAME_EDITOR: Users with this role assigned can write data and create entities in this organization

   For example, for a group named HR, create an HR_READER role and an HR_EDITOR role.

4

Define user attributes

For each user of the Desk API, a username and credentials must be specified, three attributes must be defined, and roles must be mapped.

1. Use an email address as the Username and click Create.

2. With the newly created user selected, select the Credentials tab and click Set password. Input a password for the user.

3. Select the Attributes tab and add three attributes:

   • organisation: Provide the UUID of the default organization upon login
   • language: Provide the two-letter language code for the default language upon login
   • homepage: Provide the path for the default homepage upon login

warning

The Desk API uses the UK-English spelling of 'organisation'.

4. Select the Role mapping tab and click Assign role.

5. Select all of the roles to be mapped to this user.

6. Save your changes.