diff --git a/website/docs/how-to/how-to-setup-provisioning-with-okta.md b/website/docs/how-to/how-to-setup-provisioning-with-okta.md new file mode 100644 index 0000000000..95260e487e --- /dev/null +++ b/website/docs/how-to/how-to-setup-provisioning-with-okta.md @@ -0,0 +1,106 @@ +--- +title: How to Setup Okta Provisioning +--- + +:::info availability + +The **Provisioning capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details. + +::: + +## Unleash Configuration {#unleash-setup} + +### Step 1: Navigate to Provisioning configuration {#unleash-setup-step-1} + +First you'll need to log in to Unleash as an admin user. Navigate to the Single Sign-On section and select the "SCIM" tab. The SCIM API URL will be shown in this section, you'll need this to configure Okta later. + +![Navigate to the SCIM Config](/img/scim-config-1.png) + +### Step 2: Enable Provisioning {#unleash-setup-step-2} + +Enable SCIM by turning on the toggle and keep the token Unleash provides you for the Okta setup below. + +![Enable the SCIM toggle](/img/scim-config-2.png) + +## Okta Configuration {#okta-setup} + +### Step 1: Create an Application in Okta {#okta-setup-step-1} + +:::info Note + +If you already have SAML SSO configured for Unleash in Okta you can skip to the [next step](how-to-setup-provisioning-with-okta#okta-setup-step-2). If you're planning on using [SAML for Unleash](../how-to/how-to-add-sso-saml), do that first and skip to the next step. Note that if you're using OIDC SSO in Okta you still need to do this step. + +This step will create an empty Sign-On Application that will only be used for SCIM. + +::: + +**1) Navigate to "Admin -> Applications" and click the "Create App Integration" button.** + +![Navigate to Create Application](/img/scim-okta-config-1.png) + +**2) Select SWA - Secure Web Authentication** + +![Select Secure Web Application](/img/scim-okta-config-2.png) + +**3) Fill in your App Name and App's login page URL** + +![Setup Application Properties](/img/scim-okta-config-3.png) + +### Step 2: Enable Provisioning in your Okta Application {#okta-setup-step-2} + +:::info Note + +If you already have a SAML application setup for Unleash you'll be modifying that application in this step. + +::: + +**Enable SCIM provisioning and save.** + +![Enable SCIM](/img/scim-okta-config-5.png) + +### Step 3: Connect Unleash {#okta-setup-step-3} + +**1) Navigate to the Provisioning tab** + +**2) Set the Unleash SCIM URL** + +This is provided by the Unleash UI in the [configuring Unleash](how-to-setup-provisioning-with-okta#unleash-setup-step-1) section. + +**2) Set email as the unique identifier** + +**3) Configure actions** + +Turn on "Push New Users", "Push Groups" and "Push Profile Updates". + +**4) Set authentication mode to "HTTP Header"** + +**5) Add your SCIM token** + +This was provided by the Unleash UI in the [configuring Unleash](how-to-setup-provisioning-with-okta#unleash-setup-step-2) section. + +![Connect Unleash](/img/scim-okta-config-5.png) + +### Step 4: Configure Okta Provisioning {#okta-setup-step-4} + +Navigate to the "To App" tab. Turn on "Create Users", "Update User Attributes" and "Deactivate Users". Save your configuration. + +![Configure Okta Provisioning](/img/scim-okta-config-6.png) + +### Step 5: Configure Provisioning Properties {#okta-setup-step-5} + +**1) Set email** + +Set the email field to map to your login property. This is important and ensures that your SSO integration continues to work. + +**2) Remove unneeded properties** + +You should remove all unnecessary properties. This ensures that Okta will reach a steady state when synchronizing. The properties that you must retain are: + +- Username +- Given name +- Family name +- Email +- Primary email type +- Display name + +![Configure Provisioning Attributes](/img/scim-okta-config-7.png) \ No newline at end of file diff --git a/website/docs/reference/provisioning.md b/website/docs/reference/provisioning.md new file mode 100644 index 0000000000..9a6d61722c --- /dev/null +++ b/website/docs/reference/provisioning.md @@ -0,0 +1,31 @@ +--- +id: provisioning +title: Provisioning +--- + +:::info Availability + +Provisioning is only available in Unleash Enterprise. This feature is in beta, please reach out to us if you'd like this feature enabled in your Unleash instance. + +::: + +Unleash supports provisioning through the [SCIM Protocol](https://scim.cloud/), making it easy to manage users and groups directly through your SSO provider. Users and groups that are assigned or unassigned in your Unleash SSO application will automatically be synced to Unleash. Our provisioning implementation only supports soft deletes so your audit log will be preserved when users are deprovisioned. + +See our how to guides on setting up provisioning for [Okta](../how-to/how-to-setup-provisioning-with-okta.md). + +## Advantages + +**Deprovisioning** + +Deprovisioning can be setup on the provider side and allow for automatic clean up of users in a single place. This is especially useful if you're trying to manage the cost of your Unleash instance, since deprovisioned users will not count towards the seat count of your license. See our [how to guides](../how-to/provisioning) for specific provider configurations. + +**Group syncing** + +Some SSO providers, for example Entra, have limitations on the number of users that can be synced using the [group syncing](../how-to/how-to-set-up-group-sso-sync) flow. Provisioning allows your provider to sync groups lazily in the background and side step this limitation. + +## Not supported + +- User password syncing +- User/group role mapping + +If you have a need for these features, please reach out to us. \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index f714f6973b..7c6f280ac8 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -258,6 +258,7 @@ module.exports = { 'reference/public-signup', 'reference/projects', 'reference/project-collaboration-mode', + 'reference/provisioning', 'reference/rbac', 'reference/search-operators', 'reference/segments', @@ -497,6 +498,19 @@ module.exports = { slug: '/how-to/sso', }, }, + { + label: 'Automatic provisioning', + items: [ + 'how-to/how-to-setup-provisioning-with-okta', + ], + type: 'category', + link: { + type: 'generated-index', + title: 'How to: Provisioning', + description: 'Provisioning how-to guides.', + slug: '/how-to/provisioning', + }, + }, ], }, { diff --git a/website/static/img/scim-config-1.png b/website/static/img/scim-config-1.png new file mode 100644 index 0000000000..a32f83b4f1 Binary files /dev/null and b/website/static/img/scim-config-1.png differ diff --git a/website/static/img/scim-config-2.png b/website/static/img/scim-config-2.png new file mode 100644 index 0000000000..3c0181de78 Binary files /dev/null and b/website/static/img/scim-config-2.png differ diff --git a/website/static/img/scim-okta-config-1.png b/website/static/img/scim-okta-config-1.png new file mode 100644 index 0000000000..7095d2b00b Binary files /dev/null and b/website/static/img/scim-okta-config-1.png differ diff --git a/website/static/img/scim-okta-config-2.png b/website/static/img/scim-okta-config-2.png new file mode 100644 index 0000000000..fa608750f6 Binary files /dev/null and b/website/static/img/scim-okta-config-2.png differ diff --git a/website/static/img/scim-okta-config-3.png b/website/static/img/scim-okta-config-3.png new file mode 100644 index 0000000000..1ccc79930d Binary files /dev/null and b/website/static/img/scim-okta-config-3.png differ diff --git a/website/static/img/scim-okta-config-4.png b/website/static/img/scim-okta-config-4.png new file mode 100644 index 0000000000..89d16dd1da Binary files /dev/null and b/website/static/img/scim-okta-config-4.png differ diff --git a/website/static/img/scim-okta-config-5.png b/website/static/img/scim-okta-config-5.png new file mode 100644 index 0000000000..9474594226 Binary files /dev/null and b/website/static/img/scim-okta-config-5.png differ diff --git a/website/static/img/scim-okta-config-6.png b/website/static/img/scim-okta-config-6.png new file mode 100644 index 0000000000..a2580af315 Binary files /dev/null and b/website/static/img/scim-okta-config-6.png differ diff --git a/website/static/img/scim-okta-config-7.png b/website/static/img/scim-okta-config-7.png new file mode 100644 index 0000000000..ba18af78f7 Binary files /dev/null and b/website/static/img/scim-okta-config-7.png differ