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>

website/docs/how-to/how-to-set-up-group-sso-sync.md

@@ -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.
+
+![The Unleash Admin UI with the steps highlighted to navigate to the Single sign-on configuration.](/img/setup-sso-group-sync-1.png)
+
+## 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.
+
+![The Single sign-on configuration page with enable group syncing, group field JSON path and save inputs highlighted.](/img/setup-sso-group-sync-2.png)
+
+## Step 3: Navigate to a group {#step-3}
+
+Navigate to the group you want to sync users for.
+
+![The Unleash Admin UI with the steps highlighted to navigate to groups and a highlighted group card.](/img/setup-sso-group-sync-3.png)
+
+## Step 4: Edit the group configuration {#step-4}
+
+Navigate to edit group.
+
+![The group configuration screen with edit group highlighted.](/img/setup-sso-group-sync-4.png)
+
+## 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.
+
+![The edit group screen with SSO Group input and save highlighted.](/img/setup-sso-group-sync-5.png)

website/docs/how-to/how-to-setup-sso-keycloak-group-sync.md

@@ -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".
+
+![The Keycloak Admin UI with the steps highlighted to navigate to client configuration.](/img/setup-keycloak-sync-1.png)
+
+
+### 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.
+
+![The Keycloak Admin UI with the client configuration open.](/img/setup-keycloak-sync-2.png)
+
+### 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.
+
+![The Keycloak client configuration with redirect URIs highlighted.](/img/setup-keycloak-sync-3.png)
+
+### 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.
+
+![The Keycloak credentials configuration with copy client secret highlighted.](/img/setup-keycloak-sync-4.png)
+
+### 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.
+
+![The Keycloak realm settings the OpenID endpoint configuration link highlighted.](/img/setup-keycloak-sync-5.png)
+
+### Step 6: Create a new Client Scope and Map Groups {#keycloak-step-6}
+
+Navigate to the "Client Scopes" page and select "Create Client Scope".
+
+![The Keycloak Client Scopes page with the Create Client Scope button highlighted.](/img/setup-keycloak-sync-6.png)
+
+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.
+
+![The Keycloak Add Client Scope page with the Name, Type, Protocol and Include in Token Response fields highlighted.](/img/setup-keycloak-sync-7.png)
+
+Navigate the the Mappers tab and select "Configure new Mapper".
+
+![The Keycloak Client Scope details page with the Mappers tab and Configure new Mapper element highlighted.](/img/setup-keycloak-sync-8.png)
+
+Select the Group Membership mapper.
+
+![The Keycloak mapper popup with the Group Membership mapper highlighted.](/img/setup-keycloak-sync-9.png)
+
+Give your mapper a claim name, this must match the "Group Field JSON Path" in Unleash, and turn off the "Full group path" option.
+
+![The Keycloak mapper options screen with the Token Claim Name and Full Group Path elements highlighted.](/img/setup-keycloak-sync-10.png)
+
+
+## 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).
+
+![The Unleash SSO configuration screen with Client ID, Client Secret and Discover URL highlighted.](/img/setup-keycloak-sync-11.png)
+
+### 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.
+
+![The Unleash SSO configuration screen with the Enable Group Syncing and Group Field JSON Path highlighted.](/img/setup-keycloak-sync-12.png)
+
+### Step 3: Enable Group Syncing for your Group {#unleash-step-3}
+
+Navigate to Groups and select the group that you want to sync.
+
+![The Groups page with a group element highlighted.](/img/setup-keycloak-sync-13.png)
+
+Edit the group.
+
+![The Group page with the Edit group element highlighted.](/img/setup-keycloak-sync-14.png)
+
+Add as many SSO groups as you like. These need to match the Keycloak groups exactly.
+
+![The edit group page with the add SSO group element highlighted.](/img/setup-keycloak-sync-15.png)
+
+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.

website/docs/user_guide/rbac.md

@@ -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.

website/sidebars.js

@@ -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: {