IAM Group Configuration

This guide shows you how to carry the group claim your identity provider sends through Keycloak, so it arrives on the Keycloak token as a groups claim that Self-Service can read, and how local Keycloak users are handled alongside it.

Type

How-to guide

Goal

Have Self-Service resolve IAM group membership from the group claim your identity provider already sends.

Audience

Platform Operator with admin access to Keycloak, working with whoever administers the identity provider.

When to use

Use this guide when a tenant authenticates through an SSO realm rather than local users.

Self-Service reads the groups claim from the Keycloak token to resolve Identity and Access Management (IAM) group membership. Keycloak acts as an authentication proxy, so the claim has to reach the Keycloak token rather than stopping at the token the Identity Provider (IdP) issues. The steps below are provider-agnostic: the same Keycloak mapper approach applies whichever IdP you use (Azure AD, Okta, Google, and others).

For Tenant Admin instructions on enabling IAM Group Management in Self-Service, see IAM Group Management.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Admin access to the Keycloak Administration Console for the tenant’s SSO realm.

  • Access to the identity provider’s configuration, or an administrator who can add the groups claim to the token it issues.

  • Tenant Admin rights in Self-Service, to enable IAM Group Management and to read the IAM Reference values.

Tools and versions required

You need the following tools:

  • A browser that reaches the Keycloak Administration Console at <keycloak.host>/auth.

Replace every <…​> placeholder with your own value before opening a URL.

Resources that must exist before starting

The following must already exist:

The group claim your identity provider must send

Configure your identity provider to include a groups claim in the access token. The claim is a JSON array of group identifiers, usually Universally Unique Identifiers (UUIDs) or similar opaque identifiers:

{
  "groups": [
    "46abfd96-69ad-4596-af8e-f19c29b956d3",
    "db884ce8-cba4-4c2c-bb87-1a09f4f44973"
  ]
}

The values in this array are the IAM Reference values you use when creating or converting groups in Self-Service. Your IdP documentation states how to include group memberships as a claim in the token.

Mapping IdP claims to the Keycloak token

Self-Service reads the Keycloak token, so the groups claim from the IdP token has to carry through to it. Two mappers do that: one on the identity provider captures the incoming claim as a user attribute, and one on the client scope puts that attribute in the outgoing Keycloak token.

Step 1: Identity provider mapper

Store the incoming groups claim as a Keycloak user attribute, so it lands on the Keycloak account the identity provider authenticated:

  1. Open the Menu and press the Identity providers menu, then open the provider configured for this realm.

  2. Press the Mappers tab and add a mapper.

  3. Configure the mapper to read the groups claim from the IdP token and store it as a user attribute named groups.

Step 2: Client scope mapper

Emit that user attribute as a groups claim on the Keycloak token, using the same mapper type and the same client scope that already carries the tenant claims:

  1. Open the Menu and press the Clients menu, then open the self-service client.

  2. Press on the Client scopes tab.

  3. Press on the self-service-dedicated client scope.

  4. Press on the Add Mapper and select By Configuration.

  5. Select User Attribute.

    1. Fill the Name with a name that identifies the mapper, for example Groups Mapper

    2. Fill the User Attribute as groups

    3. Fill the Token Claim Name as groups

  6. Press Save button

self-service-dedicated is the client scope that How to Create the Local Realm in Keycloak adds the tenant mappers to, so this mapper sits beside them and reaches the same token.

With both mappers in place, the Keycloak token carries the groups claim populated from the IdP.

Handling local Keycloak users for automation

Some deployments define users directly in the Keycloak realm, usually service accounts for automation such as Terraform provisioning or Continuous Integration and Continuous Delivery (CI/CD) pipelines. These users authenticate locally and receive no groups claim from an IdP.

To give these users the correct IAM group memberships, the Tenant Admin and the Platform Operator do two things:

  1. Identify every local Keycloak user that needs IAM group access.

  2. Set the groups attribute directly on each user in Keycloak, using the correct group identifiers, which are the IAM Reference values configured in Self-Service.

Keycloak then puts the groups user attribute in the token, as long as the client scope mapper in Mapping IdP claims to the Keycloak token is configured.

No external IdP authenticates a local Keycloak user, so each one needs the attribute set explicitly before it takes part in IAM group-based authorisation.

Verify the groups claim reaches Self-Service

Self-Service does not list the members of an IAM group, so confirm the claim by what a signed-in user can reach rather than by a membership screen. Pick one IAM group that grants a permission role no other group grants, then:

  1. Sign in to Self-Service through the SSO realm as a user who belongs to that group in the identity provider.

  2. Open a resource that only the group’s permission role gives access to.

Expected result: the resource opens, which happens only when the Keycloak token carried a groups claim holding that group’s IAM Reference. A sign-in that succeeds and is then refused on the resource means the claim did not survive the hop through Keycloak. Check the client scope mapper in Mapping IdP claims to the Keycloak token first. For how IAM groups resolve permissions, see Groups.