Configure Realm Roles and the Role Claim

Configure Keycloak to include an end user’s realm roles in a top-level array claim that the database can map to data roles.

1. Create realm roles, such as EMPLOYEE and MANAGER, and assign them to the required end users.

2. Select the Keycloak client used for the browser application’s end-user sign-in. Add a User Realm Role protocol mapper to that client’s dedicated client scope.

3. Set the mapper’s token claim name to roles, enable multivalued output, and include the claim in the end-user token. If you use another claim name, specify that name in roles_claim in the database configuration. The database requires a top-level array for role values; it does not read them from nested claims such as realm_access.roles or resource_access.<client>.roles.

4. Verify that the client’s role scope mappings allow the required realm roles assigned to the user to appear in the end-user access token.

5. Sign in as an end user and obtain an end-user access token. Verify that the configured role claim contains the expected realm roles in a top-level array. For example:

   "roles": ["EMPLOYEE"]

See Realm roles, Role mappings in the token and Protocol mappers in the Keycloak Server Administration Guide.

Note:

• When configuring the database, map these realm roles to data roles using ROLE=<realm_role_name>. Currently, only realm roles are supported; the mapping does not include an application identifier. See Create Data Role.

• Avoid realm role names that differ only by letter case, such as EMPLOYEE and employee. The database compares role names with external data-role mappings without regard to case.