Restructure SSO & SCIM documentation (#2253)

Author: Charlie-Boyer

docs/hub/_toctree.yml

@@ -7,10 +7,6 @@
   sections:
   - local: enterprise-sso
     title: Single Sign-On (SSO)
-  - local: enterprise-advanced-sso
-    title: Advanced Single Sign-On (SSO)
-  - local: enterprise-scim
-    title: User Provisioning (SCIM)
   - local: audit-logs
     title: Audit Logs
   - local: storage-regions
@@ -480,22 +476,33 @@
     - local: security-sso
       title: Single Sign-On (SSO)
       sections:
-      - local: security-sso-okta-oidc
-        title: How to configure OIDC with Okta
-      - local: security-sso-okta-saml
-        title: How to configure SAML with Okta
-      - local: security-sso-okta-scim
-        title: How to configure SCIM with Okta
-      - local: security-sso-azure-saml
-        title: How to configure SAML with EntraID (Azure AD)
-      - local: security-sso-azure-oidc
-        title: How to configure OIDC with EntraID (Azure AD) 
-      - local: security-sso-entra-id-scim
-        title: How to configure SCIM with EntraID (Azure AD)
-      - local: security-sso-google-saml
-        title: How to configure SAML with Google Workspace
-      - local: security-sso-google-oidc
-        title: How to configure OIDC with Google Workspace
+      - local: security-sso-basic
+        title: Basic SSO
+      - local: enterprise-advanced-sso
+        title: Managed SSO
+      - local: security-sso-user-management
+        title: User Management
+      - local: enterprise-scim
+        title: User Provisioning (SCIM)
+      - local: security-sso-configuration-guides
+        title: Configuration Guides
+        sections:
+        - local: security-sso-okta-oidc
+          title: How to configure OIDC with Okta
+        - local: security-sso-okta-saml
+          title: How to configure SAML with Okta
+        - local: security-sso-okta-scim
+          title: How to configure SCIM with Okta
+        - local: security-sso-azure-saml
+          title: How to configure SAML with EntraID (Azure AD)
+        - local: security-sso-azure-oidc
+          title: How to configure OIDC with EntraID (Azure AD)
+        - local: security-sso-entra-id-scim
+          title: How to configure SCIM with EntraID (Azure AD)
+        - local: security-sso-google-saml
+          title: How to configure SAML with Google Workspace
+        - local: security-sso-google-oidc
+          title: How to configure OIDC with Google Workspace
     - local: security-resource-groups
       title: Advanced Access Control (Resource Groups)
     - local: programmatic-user-access-control

docs/hub/enterprise-advanced-sso.md

@@ -1,22 +1,30 @@
-# Advanced Single Sign-On (SSO)
+# Managed SSO
 
 > [!WARNING]
 > This feature is part of the <a href="https://huggingface.co/contact/sales?from=enterprise" target="_blank">Enterprise Plus</a> plan.
 
-Advanced Single Sign-On (SSO) capabilities extend the standard [SSO features](./security-sso) available in Team & Enterprise plans, offering enhanced control and automation for user management and access across the entire Hugging Face platform for your organization members.
+Managed SSO **replaces the Hugging Face login entirely**. Your Identity Provider becomes the sole authentication method for your organization's members across the entire Hugging Face platform. The organization controls the full user lifecycle, from account creation to deactivation.
 
-## User Provisioning
+For a comparison with Basic SSO, see the [SSO overview](./enterprise-sso).
 
-Advanced SSO introduces automated user provisioning, which simplifies the onboarding and offboarding of users.
+## How it works
 
-*   **Just-In-Time (JIT) Provisioning**: When a user from your organization attempts to log in to Hugging Face for the first time via SSO, an account can be automatically created for them if one doesn't already exist. Their profile information and role mappings can be populated based on attributes from your IdP.
+> [!NOTE]
+> **Managed SSO replaces the Hugging Face login.** Your IdP is the only way for managed users to authenticate on Hugging Face — there is no separate Hugging Face login. Unlike Basic SSO, members do not need a pre-existing Hugging Face account. When a user authenticates through your IdP for the first time, an account is automatically created for them.
 
-<div class="flex justify-center">
-<img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sso/jit-flow-chart.png"/>
-<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sso/jit-flow-chart-dark.png"/>
-</div>
+Your IdP is the mandatory authentication route for all your organization's members interacting with any part of the Hugging Face platform. Members are required to authenticate via your IdP for all Hugging Face services, not just when accessing private or organizational repositories.
+
+When a user is deactivated in your IdP, their Hugging Face account is deactivated as well. This gives your organization complete control over identity, access, and data governance.
+
+## Getting started
 
-*   **System for Cross-domain Identity Management (SCIM)**: For more robust user lifecycle management, SCIM allows your IdP to communicate user identity information to Hugging Face. This enables automatic creation, updates (e.g., name changes, role changes), and deactivation of user accounts on Hugging Face as changes occur in your IdP. This ensures that user access is always up-to-date with their status in your organization.
+Managed SSO cannot be self-configured. To enable Managed SSO for your organization, please <a href="https://huggingface.co/contact/sales?from=enterprise" target="_blank">contact the Hugging Face team</a>. The setup is done in collaboration with our technical team to ensure a smooth transition for your organization.
+
+Both SAML 2.0 and OIDC protocols are supported and can be integrated with popular identity providers such as Okta, Microsoft Entra ID (Azure AD), and Google Workspace.
+
+## User provisioning
+
+Managed SSO introduces automated user provisioning through [SCIM](./enterprise-scim), which manages the entire user lifecycle on Hugging Face. SCIM allows your IdP to communicate user identity information to Hugging Face, enabling automatic creation, updates (e.g., name changes, role changes), and deactivation of user accounts as changes occur in your IdP.
 
 <div class="flex justify-center">
 <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sso/scim-flow-chart.png"/>
@@ -25,21 +33,19 @@ Advanced SSO introduces automated user provisioning, which simplifies the onboar
 
 Learn more about how to set up and manage SCIM in our [dedicated guide](./enterprise-scim).
 
-## Global SSO Enforcement 
-
-Beyond gating access to specific organizational content, Advanced SSO can be configured to make your IdP the mandatory authentication route for all your organization's members interacting with any part of the Hugging Face platform. Your organization's members will be required to authenticate via your IdP for all Hugging Face services, not just when accessing private or organizational repositories.
+## SSO features
 
-This feature is particularly beneficial for organizations requiring a higher degree of control, security, and automation in managing their users on Hugging Face.
+Managed SSO supports [role mapping, resource group mapping, session timeout, and external collaborators](./security-sso-user-management). These features are configurable from your organization's settings.
 
-## Limitations on Managed User Accounts
+## Restrictions on managed accounts
 
 > [!WARNING]
-> Important Considerations for Managed Accounts.
+> Important considerations for managed accounts.
 
-To ensure organizational control and data governance, user accounts provisioned and managed via Advanced SSO ("managed user accounts") have specific limitations:
+To ensure organizational control and data governance, managed user accounts have specific restrictions:
 
-*   **No Personal Content Creation**: Managed users cannot create any content (models, datasets, or Spaces) in their personal user namespace. All content must be created within the Organization.
-*   **Organization-Bound Collaboration**: Managed users are restricted to collaborating solely within their managing Organization. They cannot join other organizations or contribute to repositories outside of their managing Organization. 
-*   **Content Visibility**: Content created by managed users resides within the Organization. While the managed users cannot create public content in their personal profile, they can **create public content within the Organization** if the Organization's settings permit it.
+*   **No personal content creation**: Managed users cannot create any content (models, datasets, or Spaces) in their personal user namespace. All content must be created within the organization.
+*   **Organization-bound collaboration**: Managed users are restricted to collaborating solely within their managing organization. They cannot join other organizations or contribute to repositories outside of their managing organization.
+*   **Content visibility**: Content created by managed users resides within the organization. While the managed users cannot create public content in their personal profile, they can **create public content within the organization** if the organization's settings permit it.
 
 These restrictions maintain your enterprise's security boundaries. For personal projects or broader collaboration outside your organization, members should use a separate, unmanaged Hugging Face account.

docs/hub/enterprise-resource-groups.md

@@ -9,12 +9,12 @@ Resource Groups allow organizations to enforce fine-grained access control to th
   <img
     class="block dark:hidden m-0!"
     src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/enterprise/resource-groups.png"
-    alt="screenshot of Hugging Face Single Sign-On (SSO) feature"
+    alt="screenshot of Hugging Face Resource Groups feature"
   />
   <img
     class="hidden dark:block m-0!"
     src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/enterprise/dark-resource-groups.png"
-    alt="screenshot of Hugging Face Single Sign-On (SSO) feature"
+    alt="screenshot of Hugging Face Resource Groups feature"
   />
 </div>
 

docs/hub/enterprise-scim.md

@@ -1,30 +1,89 @@
 # User Provisioning (SCIM)
 
 > [!WARNING]
-> This feature is part of the <a href="https://huggingface.co/contact/sales?from=enterprise" target="_blank">Enterprise Plus</a> plan.
+> This feature is part of the <a href="https://huggingface.co/enterprise">Enterprise</a> and <a href="https://huggingface.co/contact/sales?from=enterprise" target="_blank">Enterprise Plus</a> plans.
 
-SCIM, or System for Cross-domain Identity Management, is a standard for automating user provisioning. It allows you to connect your Identity Provider (IdP) to Hugging Face to automatically manage your organization's members.
+SCIM (System for Cross-domain Identity Management) is a standard for automating user provisioning. It allows you to connect your Identity Provider (IdP) to Hugging Face to manage your organization's members.
 
-With SCIM, you can:
-- **Provision users**: Automatically create user accounts in your Hugging Face organization when they are assigned the application in your IdP.
-- **Update user attributes**: Changes made to user profiles in your IdP (like name or email) are automatically synced to Hugging Face.
-- **Provision groups**: Create groups in your Hugging Face organization based on groups in your IdP.
-- **Deprovision users**: Automatically deactivate user accounts in your Hugging Face organization when they are unassigned from the application or deactivated in your IdP.
+SCIM works differently depending on your SSO model. For a detailed comparison, see the [SSO overview](./enterprise-sso#user-provisioning-scim).
 
-This ensures that your Hugging Face organization's member list is always in sync with your IdP, streamlining user lifecycle management and improving security.
+## Basic SSO: invitation-based provisioning
+
+With [Basic SSO](./security-sso-basic) (Enterprise plan), SCIM automates the **invitation** of existing Hugging Face users to your organization.
+
+- Users **must already have a Hugging Face account** before they can be provisioned via SCIM
+- When your IdP provisions a user, Hugging Face sends them an **invitation email** to join the organization
+- The user must **accept the invitation** to become a member — provisioning does not grant immediate access
+- SCIM **cannot modify** user profile information (name, email, username) — the user retains full control of their Hugging Face account
+- When a user is deprovisioned in your IdP, their invitation is deactivated and their access to the organization is revoked
+
+## Managed SSO: full lifecycle provisioning
+
+With [Managed SSO](./enterprise-advanced-sso) (Enterprise Plus plan), SCIM manages the **entire user lifecycle** on Hugging Face.
+
+- SCIM **creates a new Hugging Face account** when a user is provisioned — no pre-existing account is needed
+- The user is **immediately added** to the organization as a member, with no invitation step
+- SCIM **can update** user profile information (name, email, username) as changes occur in your IdP
+- When a user is deprovisioned in your IdP, their Hugging Face account is deactivated and their access is revoked
 
 ## How to enable SCIM
 
 To enable SCIM, go to your organization's settings, navigate to the **SSO** tab, and then select the **SCIM** sub-tab.
 
-You will find the **SCIM Tenant URL** and a button to generate an **access token**. You will need both of these to configure your IdP. The SCIM token is a secret and should be stored securely in your IdP's configuration.
+You will find the **SCIM Tenant URL** and a button to generate a **SCIM token**. You will need both of these to configure your IdP. The SCIM token is a secret and should be stored securely in your IdP's configuration.
 
 <div class="flex justify-center">
     <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sso/scim-settings.png"/>
     <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/sso/scim-settings-dark.png"/>
 </div>
 
-Once SCIM is enabled in your IdP, users and groups provisioned will appear in the "Users Management" and "SCIM" tabs respectively.
+Once SCIM is enabled in your IdP, provisioned users will appear in the **Users Management** tab and provisioned groups will appear in the **SCIM** tab in your organization's settings.
+
+## Group provisioning
+
+In addition to user provisioning, SCIM supports **group provisioning**. Groups pushed from your IdP are stored as SCIM groups on Hugging Face and can be linked to [Resource Groups](./enterprise-resource-groups) from the **SCIM** tab in your organization's settings.
+
+When a SCIM group is linked to a Resource Group, membership changes are **automatically synchronized**:
+
+- When a user is **added** to a group in your IdP, they are automatically added to the linked Resource Groups with the configured role.
+- When a user is **removed** from a group in your IdP, they are automatically removed from the linked Resource Groups.
+- When a SCIM group is **deleted** in your IdP, all of its members are removed from the linked Resource Groups.
+
+This allows you to manage Resource Group membership entirely from your Identity Provider, without manual configuration on Hugging Face.
+
+Group provisioning works the same way for both Basic SSO and Managed SSO.
+
+## Supported user attributes
+
+The Hugging Face SCIM endpoint supports the following user attributes:
+
+| Attribute | Description | Basic SSO | Managed SSO |
+| --- | --- | --- | --- |
+| `userName` | Hugging Face username | Read-only | Read/Write |
+| `name.givenName` | First name | Read-only | Read/Write |
+| `name.familyName` | Last name | Read-only | Read/Write |
+| `emails[type eq "work"].value` | Email address | Read-only | Read/Write |
+| `externalId` | IdP-assigned identifier | Read/Write | Read/Write |
+| `active` | Whether the user is an active member | Read/Write | Read/Write |
+
+With Basic SSO, only `active` and `externalId` can be modified via SCIM — all other attributes are controlled by the user on their Hugging Face account.
+
+For group provisioning, the supported attributes are `displayName`, `members`, and `externalId`.
+
+## Deprovisioning
+
+Deprovisioning behavior depends on how the user is removed and which SSO model you use.
+
+**Setting `active` to `false`** (soft deprovision):
+
+- The user loses access to the organization
+- With Basic SSO: the invitation is deactivated
+- With Managed SSO: the user is removed from the organization but their account and content are preserved — this is **reversible** by setting `active` back to `true`
+
+**Deleting the user via SCIM** (hard deprovision):
+
+- With Basic SSO: the user is removed from the organization and all its resource groups. Their Hugging Face account and personal content are **not affected** — they simply lose membership in your organization.
+- With Managed SSO: the user's Hugging Face account is **permanently deleted**, along with all content they created. This action is **irreversible**.
 
 ## Supported Identity Providers