Fine-grained permissions are often needed if you are integrating an application with Keycloak for SSO purposes.

By default, Keycloak does not expose group membership information in the access- or ID-tokens or in the data from the UserInfo endpoint. Since it is not totally obvious how to achieve delivering the groups, this article shows how to do it.

Add a customized mapper to your OIDC client

  1. Choose your OIDC client and click on the Client scopes tab. In the example below, testGroupClient-dedicated is the custom entry you should select.
Client scopes configuration
  1. Click Configure a new mapper.
Add a new mapper
  1. Choose Group membership from the list.
List with mappers
  1. Add descriptive information and decide where to put group information.
Group membership mapper configuration
  • I just want the group name, not the full path.
  • I don’t choose ID token or access token because I don’t need the information there. If you need to parse the tokens for groups, pick the right settings.
  • Add to userinfo is enabled because that is the place where I will parse group information from.

You can adjust the settings to suit your needs.

  1. If you finish, your client’s custom mapping is set up.
Custom group mapping for the OIDC client

If the configuration was correct, the group information has been added to the designated location(s). In my case, I would query the UserInfo endpoint.

{
  "sub": "ce7ca1f2-218e-4e87-bff8-3dc0adfe206c",
  "email_verified": true,
  "name": "Siegurd Schnätterchen",
  "groups": [
    "admins"
  ],
  "preferred_username": "siegurd",
  "given_name": "Siegurd",
  "family_name": "Schnätterchen",
  "email": "[email protected]"
}

Please refer to Postman and the Keycloak UserInfo endpoint for further information on testing the configuration.