Keycloak OIDC Group Membership Mapping
Learn how to sync Keycloak group members to matching groups in Hanzo KMS.
You can have Hanzo KMS automatically sync group memberships between Keycloak and Hanzo KMS by configuring a group membership mapper in Keycloak. When a user logs in via OIDC, they will be added to Hanzo KMS groups that match their Keycloak groups names, and removed from any Hanzo KMS groups not present in their groups claim.
When enabled, manual management of Hanzo KMS group memberships will be disabled.
Group membership changes in the Keycloak only sync with Hanzo KMS when a user logs in via OIDC. For example, if you remove a user from a group in Keycloak, this change will not be reflected in Hanzo KMS until their next OIDC login. To ensure this behavior, Hanzo KMS recommends enabling Enforce OIDC SSO in the OIDC settings.
1.1. In your realm, navigate to the Clients tab and select your Hanzo KMS client.
1.2. Select the Client Scopes tab.
1.3. Next, select the dedicated scope for your Hanzo KMS client.
1.4. Click on the Add mapper button, and select the By configuration option.
1.5. Select the Group Membership option.
1.6. Give your mapper a name and ensure the following properties are set to the following before saving:
- Token Claim Name is set to
groups - Full group path is disabled
2.1. In Hanzo KMS, create any groups you would like to sync users to. Make sure the name of the Hanzo KMS group is an exact match of the Keycloak group name.
2.2. Next, enable OIDC Group Membership Mapping on the Single Sign-On (SSO) page under the General tab.
2.3. The next time a user logs in they will be synced to their matching Keycloak groups.
How is this guide?
Last updated on