mirror of
https://github.com/Unleash/unleash.git
synced 2025-10-27 11:02:16 +01:00
109 lines
4.7 KiB
Markdown
109 lines
4.7 KiB
Markdown
---
|
|
title: 'How to set up Keycloak and Unleash to sync user groups'
|
|
---
|
|
|
|
:::info availability
|
|
|
|
User group syncing was released in Unleash 4.18 and is available to enterprise customers.
|
|
|
|
:::
|
|
|
|
In this guide, we will setup OIDC Single Sign-On (SSO) in Keycloak and configure Unleash to automatically sync user group membership from Keycloak.
|
|
|
|
## Prerequisites
|
|
The steps in this guide assume you have admin access to a running Unleash instance and to a running Keycloak instance.
|
|
|
|
## Keycloak Configuration
|
|
|
|
### Step 1: Navigate to Create Client {#keycloak-step-1}
|
|
|
|
Open the Keycloak admin dashboard, navigate to clients and select "Create Client".
|
|
|
|
|
|
|
|
|
|
### Step 2: Create an Unleash Client {#keycloak-step-2}
|
|
|
|
Select "OpenID Connect" as the client type and give your client a name, then save your configuration.
|
|
|
|
|
|
|
|
### Step 3: Set a redirect URI {#keycloak-step-3}
|
|
|
|
Set the redirect URI to:
|
|
|
|
`<base-url>/auth/oidc/callback`
|
|
|
|
For a hosted Unleash instance this becomes:
|
|
|
|
`https://<region>.app.unleash-hosted.com/<instance-name>/auth/oidc/callback`
|
|
|
|
Save your configuration.
|
|
|
|
|
|
|
|
### Step 4: Copy your client secret {#keycloak-step-4}
|
|
|
|
Navigate to "Credentials" and copy your client secret. You'll need to add this to the Unleash configuration later, so put it somewhere you'll be able to find it.
|
|
|
|
|
|
|
|
### Step 5: Copy your OpenID endpoint configuration {#keycloak-step-5}
|
|
|
|
Navigate to your realm settings and copy the link to OpenID endpoint configuration. You'll need to add this to the Unleash configuration later.
|
|
|
|
|
|
|
|
### Step 6: Create a new Client Scope and Map Groups {#keycloak-step-6}
|
|
|
|
Navigate to the "Client Scopes" page and select "Create Client Scope".
|
|
|
|
|
|
|
|
Give your new scope a name. Set the type to "Optional". Make sure the protocol is set to "OpenID Connect" and the "Include in Token Response" option is enabled. Save your new scope.
|
|
|
|
|
|
|
|
Navigate to the Mappers tab and select "Configure new Mapper".
|
|
|
|
|
|
|
|
Select the Group Membership mapper.
|
|
|
|
|
|
|
|
Give your mapper a claim name, this must match the "Group Field JSON Path" in Unleash, and turn off the "Full group path" option.
|
|
|
|
|
|
|
|
|
|
## Unleash Configuration
|
|
|
|
### Step 1: Navigate to the Unleash SSO Configuration {#unleash-step-1}
|
|
|
|
Log in to Unleash as an admin user and navigate to the SSO configuration. Input your Client Secret (copied in step 3 of the Keycloak configuration), your Discover URL (copied in step 4 of the Keycloak configuration), and the Client ID (from step 2 of the Keycloak configuration).
|
|
|
|
|
|
|
|
### Step 2: Enable Group Syncing {#unleash-step-2}
|
|
|
|
Turn on Group Syncing and set a value for "Group Field JSON Path". This must match the value in claim name in Keycloak exactly. Save your configuration.
|
|
|
|
|
|
|
|
### Step 3: Enable Group Syncing for your Group {#unleash-step-3}
|
|
|
|
Navigate to Groups and select the group that you want to sync.
|
|
|
|
|
|
|
|
Edit the group.
|
|
|
|
|
|
|
|
Add as many SSO groups as you like. These need to match the Keycloak groups exactly.
|
|
|
|
|
|
|
|
Save your configuration. Once a user belonging to one of these Keycloak groups logs in through SSO, they'll be automatically added to this Unleash group.
|