Keycloak: How-to

Create a custom scope

1. Open the Keycloak administration console

2. Open the “Client scopes” tab

3. Click “Create client scope”

4. Enter the following information:

   1. Name: modelop_client

   2. Description: A ModelOp custom scope used to distinguish between an OAuth2 client and an end-user

   3. Type: Optional

   4. Protocol: OpenID Connect

   5. Display on consent screen: Off

   6. Include in token scope: On

   7. Display Order: <Leave blank>

5. Click “Save”

Once the scope is created, add it as a scope to the internal-client by following these steps:

1. Open the “Clients” tab

2. Select “internal-client”

3. Open the “Client scopes” tab

4. Click “Add client scope”

5. Select “modelop_client”

6. Click “Add” and select “Optional”

Create a user attribute mapper

To create a user attribute mapper which specifies which LDAP attribute maps to the attribute of the Keycloak user, please follow these steps:

1. Open the Keycloak administration console

2. Open the “User Federation” tab

3. Select the LDAP provider

4. Open the “Mappers” tab

5. Click “Add mapper”

6. Enter the following information:

   1. Name: modelOpGroups

   2. Mapper Type: user-attribute-ldap-mapper

   3. LDAP Groups DN

   4. User Model Attribute: memberOf

   5. LDAP Attribute: <Enter the name of the mapped attribute on LDAP object containing the user’s groups>

   6. Read Only: On

   7. Always Read Value From LDAP: On

   8. Is Mandatory in LDAP: Off

   9. Attribute default value: <Leave blank>

   10. Force a Default Value: Off

   11. Is Binary Attribute: Off

7. Click “Save”

Once the group mapper is defined, it needs to be applied to all users by following these steps, starting with “Step 4. Open the ‘Mappers’ tab” listed above:

1. In the upper right corner, select “Sync all users” from the dropdown menu for “Action”.

Create a hardcoded attribute mapper

To create a hardcoded attribute mapper which adds a hardcoded group value to each Keycloak user linked with LDAP, please follow these steps:

1. Open the Keycloak administration console

2. Open the “User Federation” tab

3. Select the LDAP provider

4. Open the “Mappers” tab

5. Click “Add mapper”

6. Enter the following information:

   1. Name: modelOpGroups

   2. Mapper Type: hardcoded-attribute-mapper

   3. User Model Attribute Name: memberOf

   4. Attribute Value: modelop

7. Click “Save”

Once the group mapper is defined, it needs to be applied to all users by following these steps, starting with “Step 4. Open the ‘Mappers’ tab” listed above:

1. In the upper right corner, select “Sync all users” from the dropdown menu for “Action”.

Create a group mapper

To create a group mapper which maps LDAP groups from a branch of an LDAP tree into groups within Keycloak, please follow these steps:

1. Open the Keycloak administration console

2. Open the “User Federation” tab

3. Select the LDAP provider

4. Open the “Mappers” tab

5. Click “Add mapper”

6. Enter the following information:

   1. Name: modelOpGroups

   2. Mapper type: group-ldap-mapper

   3. LDAP Groups DN: <Enter the LDAP DN where are groups of this tree saved. For example, ‘ou=groups,dc=example,dc=org’>

   4. Group Name LDAP Attribute: <Name of LDAP attribute, which is used in group objects for name and RDN of group. Usually it will be 'cn'>

   5. Group Object Classes: <Object class (or classes) of the group object. It's divided by comma if more classes needed. In typical LDAP deployment it could be 'groupOfNames' . In Active Directory it's usually 'group'>

   6. Preserve Group Inheritance: Off

   7. Ignore Missing Groups: Off

   8. Membership LDAP Attribute: <Name of LDAP attribute on group, which is used for membership mappings. Usually it will be 'member' .However when 'Membership Attribute Type' is 'UID' then 'Membership LDAP Attribute' could be typically 'memberUid'>

   9. Membership Attribute Type: <DN means that LDAP group has its members declared in form of their full DN. For example 'member: uid=john,ou=users,dc=example,dc=com' . UID means that LDAP group has its members declared in form of pure user uids. For example 'memberUid: john'>

   10. Membership User LDAP Attribute

   11. LDAP Filter: <Leave blank>

   12. Mode: READ_ONLY

   13. User Groups Retrieve Strategy: GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE

   14. Member-Of LDAP Attribute: < It specifies the name of the LDAP attribute on the LDAP user, which contains the groups, which the user is member of. Usually it will be 'memberOf' and that's also the default value>

   15. Mapped Group Attributes: <Leave blank>

   16. Drop non-existing groups during sync: Off

   17. Groups Path: <Keycloak group path the LDAP groups are added to>

When configuring this mapper, Keycloak will populate most of the fields and normally those default values are correct.

Once the group mapper is created, an additional mapper has to be created for each of the ModelOp clients by following these steps:

1. Open the “Clients” tab

2. For each ModelOp client, follow these steps:

   1. Select the client

   2. Open the “Client scopes” tab

   3. Open the “<client-name>-dedicated“ scope

   4. Click “Add mapper” by configuration

   5. Select “Group Membership”

   6. Enter the following information:

      1. Mapper type: Group Membership

      2. Name: modelopGroups2

      3. Token Claim Name: <Name of the claim to insert into the token>

      4. Full group path: Off

      5. Add to ID token: On

      6. Add to access token: On

      7. Add to userinfo: On

   7. Click “Save”

Official Keycloak Resources

The following links from the official Keycloak documentation are excellent resources that cover the topics and settings required for ModelOp Center:

• Core concepts and terms

• Creating a realm

• LDAP provider

• LDAP mappers

• Client scopes

• Creating an OpenID Connect client