IAM Group Configuration

This page describes how to configure Keycloak so that group membership information from an external Identity Provider (IdP) is included in the JWT tokens presented to Axual Self-Service.

Self-Service reads the groups claim from the Keycloak token to resolve IAM group membership. Because Keycloak acts as an authentication proxy, the claim must be present in the Keycloak token — not only in the IdP token. The steps below are provider-agnostic; the same Keycloak mapper approach applies regardless of which IdP you use (Azure AD, Okta, Google, etc.).

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

Identity Provider Prerequisites

Your Identity Provider must be configured to include a groups claim in the access token. The claim must be a JSON array of group identifiers (typically 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 will use when creating or converting groups in Self-Service. Consult your IdP documentation for how to include group memberships as a claim in the token.

Mapping IdP Claims to the Keycloak Token

Because Self-Service reads the Keycloak token, the groups claim from the IdP token must be mapped through to the Keycloak token. This requires two mappers: one on the Identity Provider to capture the incoming claim as a user attribute, and one on the client scope to include that attribute in the outgoing Keycloak token.

Step 1: Identity Provider Mapper

  1. In Keycloak, open your Identity Provider configuration and navigate to the Mappers tab.

  2. Create a new mapper that reads the incoming groups claim from the IdP token and stores it as a user attribute named groups.

Step 2: Client Scope Mapper

  1. Open the client used by Self-Service and navigate to Client Scopes.

  2. Create a mapper of type User Attribute that reads the groups user attribute and includes it as a groups claim in the Keycloak token.

Once both mappers are in place, the Keycloak token will include the groups claim populated from the IdP.

Handling Local Keycloak Users (Automation)

Some deployments have users defined directly in the Keycloak realm — typically service accounts used for automation such as Terraform provisioning or CI/CD pipelines. These users authenticate locally and do not receive a groups claim from an IdP.

To grant these users the correct IAM group memberships, the Tenant Admin and the Operator must:

  1. Identify all local Keycloak users that require IAM group access.

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

Keycloak will include the groups user attribute in the token when the client scope mapper described in Mapping IdP Claims to the Keycloak Token is configured.

Local Keycloak users (those in the local realm) are not authenticated via an external IdP and require explicit attribute configuration to participate in IAM group-based authorization.