SCIM config troubleshooting (#10478)

website/docs/how-to/how-to-setup-provisioning-with-entra.md

@@ -10,6 +10,12 @@ title: Set up Entra provisioning
 
 ## Unleash Configuration {#unleash-setup}
 
+:::info
+
+Before you begin, ensure that you have a strategy in place to prevent being [locked out of all admin accounts](/troubleshooting#got-locked-out-of-an-admin-account-after-configuring-scim).
+
+:::
+
 ### 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 Entra later.

website/docs/how-to/how-to-setup-provisioning-with-okta.md

@@ -11,6 +11,12 @@ pagination_next: how-to/how-to-setup-provisioning-with-entra
 
 ## Unleash Configuration {#unleash-setup}
 
+:::info
+
+Before you begin, ensure that you have a strategy in place to prevent [being locked out of all admin accounts](/troubleshooting#got-locked-out-of-an-admin-account-after-configuring-scim).
+
+:::
+
 ### 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.

website/docs/reference/scim.md

@@ -13,23 +13,16 @@ import SearchPriority from '@site/src/components/SearchPriority';
 
 :::
 
-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.
+[SCIM](https://scim.cloud/) automates user and group provisioning between an identity provider (IdP) and an application like Unleash. This makes it easy to manage users and groups directly through your [SSO](/reference/sso) provider. This automation offers several key benefits:
 
-See our how to guides on setting up provisioning for [Okta](../how-to/how-to-setup-provisioning-with-okta.md) or [Entra](../how-to/how-to-setup-provisioning-with-entra.md) (formerly known as Azure).
+- **Improved security**: When an employee leaves, their account is instantly deprovisioned, reducing security risks.
+- **Reduced administrative overhead**: New team members are automatically given the correct permissions, eliminating the need for manual setup.
+- **Consistency**: SCIM ensures that user access and group memberships are consistent and up-to-date across all connected applications. With SCIM, your IdP can sync groups lazily in the background, circumventing limitations on the number of users that can be synced with some SSO providers.
 
-## Advantages
+Our implementation supports user and group provisioning, but not password syncing or role mapping. It uses soft-deletes to preserve audit logs when you deprovision users.
 
-**Deprovisioning**
+See our how-to guides on setting up provisioning for [Okta](../how-to/how-to-setup-provisioning-with-okta.md) or [Entra](../how-to/how-to-setup-provisioning-with-entra.md).
 
-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.
+## Retain admin access
 
-**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.
+When setting up a SCIM integration with Unleash, you must configure a method for role management to avoid being locked out of admin accounts. To do this, either assign the admin role to an IdP group that is synced with Unleash or create a dedicated, non-SCIM managed recovery admin account for emergency use. For full instructions, including what to do if you're already locked out, see our complete [troubleshooting guide](/troubleshooting#got-locked-out-of-an-admin-account-after-configuring-scim).

website/docs/troubleshooting.mdx

@@ -133,4 +133,35 @@ You can use the `curl` command-line tool to inspect the response headers from yo
 If a documented Unleash feature isn't showing up in your Admin UI, check the following:
 
 - Is the feature included in your [Unleash plan and version](/availability)?
-- Is the feature in beta? If so, reach out to us to get early access.
+- Is the feature in beta? If so, reach out to us to get early access.
+
+## Got locked out of an Admin account after configuring SCIM
+
+When you integrate Unleash with an identity provider (IdP) like [Okta](../how-to/how-to-setup-provisioning-with-okta) or [Entra ID](../how-to/how-to-setup-provisioning-with-entra) via [SCIM](/reference/scim), your IdP becomes the source of truth for user information.
+This can have an unintended side effect: users, including the one who set up the integration, might lose their admin permissions.
+
+When your IdP syncs a user with Unleash, it sends over the user's attributes. However, the standard SCIM protocol does not have a field for user roles. If role information isn't specified, Unleash defaults the user to the Viewer role for security reasons.
+This means that even if you manually reassign the Admin role to a user in the Unleash UI, the change will be reset during the next SCIM sync.
+
+### Recommended approaches
+
+#### Manage roles with user groups
+
+By creating a [group](/reference/rbac#user-groups) in Unleash and assigning it an admin role, and then configuring your IdP to push that group and its membership via SCIM, you get fully automated permission management:
+
+1. In the Unleash Admin UI, go to **Admin settins > User config > Groups** and create a new group, for example `Unleash Admins`.
+2. Assign the Admin role or your desired [custom-root role](/reference/rbac#custom-root-roles) to this group.
+3. In your IdP, ensure you have a corresponding group and configure your SCIM integration.
+4. Once configured, any user you add to the `Unleash Admins` group in your IdP will automatically gain admin privileges in Unleash.
+
+#### Create a recovery admin account
+
+You can create a dedicated admin account that is not managed by SCIM. This account can be used for initial setup or as an emergency backup if you get locked out:
+1. In Unleash, create a new user with email address outside of your IdP.
+2. Assign an admin role. 
+
+This ensures that the user's permissions are managed solely within Unleash and will not be affected by SCIM syncs.
+
+### What if I'm already locked out?
+
+If you've already enabled SCIM and lost all admin access, please contact our support team. We can create a temporary admin user for you while you correct your SCIM configuration.