docs: add documentation for user group syncing (#2314)
* docs: add documentation for user group syncing and a end to end example for keycloak Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
43
website/docs/how-to/how-to-set-up-group-sso-sync.md
Normal file
@ -0,0 +1,43 @@
|
||||
---
|
||||
title: How set up user group SSO syncing
|
||||
---
|
||||
|
||||
:::info availability
|
||||
|
||||
User group syncing is planned to be released in Unleash 4.18 and will be available for enterprise customers.
|
||||
|
||||
:::
|
||||
|
||||
This guide takes you through how to configure your [user groups](../user_guide/rbac#user-groups) to automatically populate users through Single Sign On (SSO). Refer to [setting up Keycloak for user group sync](../../how-to/how-to-setup-sso-keycloak-group-sync) for an end to end example. Note that the steps below require you to be logged in as an admin user.
|
||||
|
||||
## Step 1: Navigate to SSO configuration {#step-1}
|
||||
|
||||
Navigate to the "Single sign-on" configuration page.
|
||||
|
||||

|
||||
|
||||
## Step 2: Enable Group Syncing {#step-2}
|
||||
|
||||
Turn on "Enable Group Syncing" and enter a value a for "Group Field JSON Path". Refer to the [User group SSO integration documentation](../user_guide/rbac.md#user-group-sso-integration) for more information or to the [how-to guide for integrating with Keycloak](how-to-setup-sso-keycloak-group-sync.md) for a practical example.
|
||||
|
||||
The value is the JSON path in the token response where your group properties are located, this is up to your SSO provider, a full example for Keycloak can be [found here](../../how-to/how-to-setup-sso-keycloak-group-sync). Once you're happy, save your configuration.
|
||||
|
||||

|
||||
|
||||
## Step 3: Navigate to a group {#step-3}
|
||||
|
||||
Navigate to the group you want to sync users for.
|
||||
|
||||

|
||||
|
||||
## Step 4: Edit the group configuration {#step-4}
|
||||
|
||||
Navigate to edit group.
|
||||
|
||||

|
||||
|
||||
## Step 5: Link SSO groups to your group {#step-5}
|
||||
|
||||
Link as many SSO groups as you like to your group, these names should match the group name or ID sent by your SSO provider exactly. Save your group configuration, the next time a user belonging to one of these groups logs in, they'll be automatically added to this group.
|
||||
|
||||

|
108
website/docs/how-to/how-to-setup-sso-keycloak-group-sync.md
Normal file
@ -0,0 +1,108 @@
|
||||
---
|
||||
title: 'How to set up Keycloak and Unleash to sync user groups'
|
||||
---
|
||||
|
||||
:::info availability
|
||||
|
||||
User group syncing is an upcoming Unleash feature that will be available for 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 the 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.
|
@ -119,7 +119,51 @@ A user group consists of the following:
|
||||
- a **name** (required)
|
||||
- a **description** (optional)
|
||||
- a list of users (optional)
|
||||
- a list of SSO groups to sync from (optional)
|
||||
|
||||
Groups do nothing on their own. They must be given a role on a project to assign permissions. You can assign both standard roles and custom project roles to groups.
|
||||
|
||||
While a user can only have one role in a given project, a user may belong to multiple groups, and each of those groups may be given a role on a project. In the case where a given user is given permissions to a project through more than one group, the user will inherit most permissive permissions of all their groups in that project.
|
||||
|
||||
## User Group SSO Integration
|
||||
|
||||
:::info availability
|
||||
|
||||
User group syncing is planned to be released in Unleash 4.18 and will be available for enterprise customers.
|
||||
|
||||
:::
|
||||
|
||||
User groups also support integration with your Single Sign-On (SSO) provider. This allows you to automatically assign users to groups when they log in through SSO. Check out [_how to set up group SSO sync_](../how-to/how-to-set-up-group-sso-sync.md) for a step-by-step walkthrough.
|
||||
|
||||
Users that have been added to a group through your SSO provider will be automatically removed next time they log in if they've been removed from the SSO group. Users that have been manually added to the group will not be affected.
|
||||
|
||||
To enable group sync, you'll need to set two fields in your SSO provider configuration options:
|
||||
|
||||
- **enable group syncing**:
|
||||
|
||||
Turns on group syncing. This is disabled by default.
|
||||
|
||||
- **group field JSON path**
|
||||
|
||||
A JSON path that should point to the groups field in your token response. This should match the exact field returned by the provider. For example, if your token looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
"iss": "https://some-url.com",
|
||||
"azp": "1234987819200.apps.some-url.com",
|
||||
"aud": "1234987819200.apps.some-url.com",
|
||||
"sub": "10769150350006150715113082367",
|
||||
"at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
|
||||
"hd": "example.com",
|
||||
"email": "jsmith@example.com",
|
||||
"email_verified": "true",
|
||||
"groups": ["test-group", "test-group-2"], //the field where groups are specified
|
||||
"iat": 1353601026,
|
||||
"exp": 1353604926,
|
||||
"nonce": "0394852-3190485-2490358"
|
||||
}
|
||||
```
|
||||
You need to set the "Group Field JSON path" to "groups".
|
||||
|
||||
Once you've enabled group syncing and set an appropriate path, you'll need to add the SSO group names to the Unleash group. This can be done by navigating to the Unleash group you want to enable sync for and adding the SSO group names to the "SSO group ID/name" property.
|
||||
|
@ -119,6 +119,7 @@ module.exports = {
|
||||
'user_guide/user-management',
|
||||
'how-to/how-to-create-and-assign-custom-project-roles',
|
||||
'how-to/how-to-create-and-manage-user-groups',
|
||||
'how-to/how-to-set-up-group-sso-sync',
|
||||
],
|
||||
type: 'category',
|
||||
link: {
|
||||
@ -135,6 +136,7 @@ module.exports = {
|
||||
'advanced/sso-saml',
|
||||
'advanced/sso-saml-keycloak',
|
||||
'advanced/sso-google',
|
||||
'how-to/how-to-setup-sso-keycloak-group-sync',
|
||||
],
|
||||
type: 'category',
|
||||
link: {
|
||||
|
BIN
website/static/img/setup-keycloak-sync-1.png
Normal file
After Width: | Height: | Size: 58 KiB |
BIN
website/static/img/setup-keycloak-sync-10.png
Normal file
After Width: | Height: | Size: 45 KiB |
BIN
website/static/img/setup-keycloak-sync-11.png
Normal file
After Width: | Height: | Size: 104 KiB |
BIN
website/static/img/setup-keycloak-sync-12.png
Normal file
After Width: | Height: | Size: 112 KiB |
BIN
website/static/img/setup-keycloak-sync-13.png
Normal file
After Width: | Height: | Size: 55 KiB |
BIN
website/static/img/setup-keycloak-sync-14.png
Normal file
After Width: | Height: | Size: 40 KiB |
BIN
website/static/img/setup-keycloak-sync-15.png
Normal file
After Width: | Height: | Size: 88 KiB |
BIN
website/static/img/setup-keycloak-sync-2.png
Normal file
After Width: | Height: | Size: 30 KiB |
BIN
website/static/img/setup-keycloak-sync-3.png
Normal file
After Width: | Height: | Size: 60 KiB |
BIN
website/static/img/setup-keycloak-sync-4.png
Normal file
After Width: | Height: | Size: 41 KiB |
BIN
website/static/img/setup-keycloak-sync-5.png
Normal file
After Width: | Height: | Size: 79 KiB |
BIN
website/static/img/setup-keycloak-sync-6.png
Normal file
After Width: | Height: | Size: 81 KiB |
BIN
website/static/img/setup-keycloak-sync-7.png
Normal file
After Width: | Height: | Size: 45 KiB |
BIN
website/static/img/setup-keycloak-sync-8.png
Normal file
After Width: | Height: | Size: 36 KiB |
BIN
website/static/img/setup-keycloak-sync-9.png
Normal file
After Width: | Height: | Size: 91 KiB |
BIN
website/static/img/setup-sso-group-sync-1.png
Normal file
After Width: | Height: | Size: 108 KiB |
BIN
website/static/img/setup-sso-group-sync-2.png
Normal file
After Width: | Height: | Size: 114 KiB |
BIN
website/static/img/setup-sso-group-sync-3.png
Normal file
After Width: | Height: | Size: 54 KiB |
BIN
website/static/img/setup-sso-group-sync-4.png
Normal file
After Width: | Height: | Size: 40 KiB |
BIN
website/static/img/setup-sso-group-sync-5.png
Normal file
After Width: | Height: | Size: 103 KiB |