From 33646908f53acbf708bc5154a1195cb966d273af Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 15 Apr 2026 18:30:30 +0000 Subject: [PATCH 1/6] Update SSO and SCIM documentation with Entra ID setup details - auth_setup.md: Add Entra ID SAML walkthrough (Enterprise App creation, SAML configuration, attribute mapping), SP URL formats, SLO note, group name vs Object ID warning, SAML Settings API reference with curl example, JIT provisioning behavior, NameID format, SAML user lifecycle table, SAML+SCIM interaction section, manual management flags table, troubleshooting section, advanced pysaml2 env vars - scim_setup.md: Expand Entra ID section with detailed step-by-step provisioning (enable provisioning, required/recommended/optional attribute mappings, mappings to remove with 501 warning, group provisioning, group mapping API example, start provisioning), add shared group mapping reference (roles_groups, workspaces_groups, projects_groups with formats and behavior), SCIM user lifecycle table, SAML+SCIM interaction section, comprehensive troubleshooting, update prerequisites to note PAT support Co-authored-by: niklub --- docs/source/guide/auth_setup.md | 199 ++++++++++++++++++++++- docs/source/guide/scim_setup.md | 273 +++++++++++++++++++++++++++----- 2 files changed, 428 insertions(+), 44 deletions(-) diff --git a/docs/source/guide/auth_setup.md b/docs/source/guide/auth_setup.md index 77818fdd0131..8fae8e9c6ef2 100644 --- a/docs/source/guide/auth_setup.md +++ b/docs/source/guide/auth_setup.md @@ -52,9 +52,12 @@ The details will vary depending on your IdP, but in general you will complete th 3. In the **Organization** field, ensure the domain matches the domain used for your organization in your IdP. 4. Copy the following URLs: - * **Assertion Consumer Service (ACS) URL with Audience (EntityID), and Recipient (Reply) details**---The IdP uses this URL to redirect users to after a successful authentication. - * **Login URL**---This is the URL that users will use to log in to Label Studio. - * **Logout URL**---This is the URL used to redirect users after successfully logging out of Label Studio. + * **Assertion Consumer Service (ACS) URL with Audience (EntityID), and Recipient (Reply) details**---The IdP uses this URL to redirect users to after a successful authentication. Format: `https:///saml//acs` + * **Login URL**---This is the URL that users will use to log in to Label Studio. Format: `https:///saml//login` + * **Logout URL**---This is the URL used to redirect users after successfully logging out of Label Studio. Format: `https:///saml//logout` + +!!! note + Label Studio does not implement SAML Single Logout (SLO) to the IdP. The logout URL only ends the local Label Studio session. #### From your IdP: @@ -96,13 +99,15 @@ If your Entra ID is configured with default claim URIs, use: | LastName | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | | Groups | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` | - +!!! warning "Important: Group names vs. Object IDs in Entra ID" + If you use group-based mappings (roles, workspaces, projects), you must configure Entra ID to send **group names** (not Object IDs) in the groups claim. In **User Attributes & Claims → Groups returned in claim**, select **Groups assigned to the application** and set **Source attribute** to `sAMAccountName` or another human-readable group property. Sending Object IDs instead of names will prevent group mappings from working correctly. #### From Label Studio: 1. Return to the SSO & SAML page. 2. Upload the metadata XML file or specify the metadata URL. -3. Set up group mappings. These can also be added or edited later. +3. Select the appropriate IdP provider preset (e.g. `azure` for Entra ID) to auto-fill attribute mapping names, or configure them manually to match what your IdP sends. +4. Set up group mappings. These can also be added or edited later. Ensure the group name you enter is the same as the group name sent as an attribute in a SAML authentication response by your IdP. @@ -117,15 +122,140 @@ If your Entra ID is configured with default claim URIs, use: You can map a group to different roles across multiple projects. You can also map multiple groups to the same roles and the same projects. For more information on roles, see [Roles in Label Studio Enterprise](manage_users#Roles-in-Label-Studio-Enterprise). If you select **Inherit**, the group will inherit the role set above under **Organization Roles to Groups Mapping.** If the group is inheriting the Not Activated role, the users are mapped to the project, but they are not actually assigned to the project until the group is synced (meaning that the user authenticates with SSO). -4. Click **Save**. +5. Click **Save**. + +6. Test the configuration by logging in to Label Studio Enterprise with your SSO account. -5. Test the configuration by logging in to Label Studio Enterprise with your SSO account. +#### Group mapping behavior +| Mapping Type | Behavior | +| --- | --- | +| Organization Roles (`roles_groups`) | If a user belongs to multiple role groups, the most elevated role wins. Available roles: Administrator, Manager, Reviewer, Annotator. The Owner role cannot be assigned via SAML or SCIM. | +| Workspaces (`workspaces_groups`) | A user can be mapped to multiple workspaces through multiple group memberships. Workspaces are automatically created if they do not exist when a mapping is triggered. | +| Projects (`projects_groups`) | Format: `{"project_id": , "group": "", "role": ""}`. Available project roles: Annotator, Reviewer, or Inherit. The most elevated role wins when a user is in multiple groups mapped to the same project. | + +!!! note + Group name matching is **case-sensitive** for all mapping types. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. + +### SAML SSO Settings API + +You can also configure SAML settings programmatically using the API: + +| Method | Endpoint | Description | +| --- | --- | --- | +| `GET` | `/api/saml/settings` | Retrieve current SAML settings (includes computed SP URLs) | +| `POST` | `/api/saml/settings` | Update SAML settings (partial update supported) | +| `DELETE` | `/api/saml/settings` | Reset SAML configuration | +| `POST` | `/api/saml/settings/validate-metadata-url` | Validate a metadata URL is reachable and contains valid XML | + +!!! warning + Using `DELETE /api/saml/settings` clears all SCIM group assignments (`WorkspaceGroupAssignment`, `OrganizationGroupAssignment`, and `ProjectGroupAssignment` records) and resets `ScimGroupSettings` for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments. + +**Example: Configure SAML via the API** + +```bash +curl -X POST "https:///api/saml/settings" \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{ + "domain": "contoso.com", + "metadata_url": "https://login.microsoftonline.com//federationmetadata/2007-06/federationmetadata.xml?appid=", + "idp_provider": "azure", + "mapping_email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", + "mapping_first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", + "mapping_last_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", + "mapping_groups": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", + "roles_groups": [ + ["Administrator", "LS-Admins"], + ["Annotator", "LS-Annotators"] + ], + "workspaces_groups": [ + ["Engineering", "LS-Engineering-Team"] + ], + "projects_groups": [ + {"project_id": 42, "group": "LS-Project42-Reviewers", "role": "Reviewer"} + ] + }' +``` ### Setup SAML SSO with Okta video tutorial +### Set up SAML SSO with Microsoft Entra ID + +To set up SAML SSO specifically with Microsoft Entra ID (formerly Azure AD): + +#### Step 1: Create the Enterprise Application in Entra ID + +1. In the Azure Portal, go to **Entra ID → Enterprise Applications → New Application**. +2. Select **Create your own application** → **Integrate any other application not found in the gallery**. +3. Name it (e.g. `Label Studio SSO`) and create it. + +#### Step 2: Configure SAML in Entra ID + +1. Go to **Single sign-on → SAML**. +2. Under **Basic SAML Configuration**: + - **Identifier (Entity ID)**: Paste the ACS URL from Label Studio. + - **Reply URL (ACS URL)**: Paste the same ACS URL. + - **Sign on URL**: Paste the Login URL from Label Studio. +3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#from-your-idp). +4. Under **SAML Signing Certificate**, download the **Federation Metadata XML** file (or copy the **App Federation Metadata URL**). + +#### Step 3: Configure SAML in Label Studio + +1. Go to **Organization → SSO & SAML**. +2. In the **Domain** field, enter the email domain(s) for your organization (comma-separated, e.g. `contoso.com`). This is used for domain-based SSO routing when users enter their email on the login page. +3. Upload the **Federation Metadata XML** file downloaded from Entra ID, or paste the **App Federation Metadata URL** in the metadata URL field. +4. Select `azure` as the IdP provider preset to auto-fill attribute mapping names, or configure them manually. +5. Configure group mappings as needed. +6. Click **Save**. + +#### Step 4: Assign users and test + +1. In Entra ID, go to **Enterprise Application → Users and groups → Add user/group**. +2. Assign users or groups to the application. +3. Test by navigating to the Label Studio Login URL, or by going to `https:///saml/sso-domain` and entering your email---Label Studio will look up the SAML config by domain and redirect to Entra ID. +4. After authenticating with Entra ID, you should be redirected back to Label Studio and logged in. + + +## JIT (Just-In-Time) provisioning + +When a user authenticates via SAML for the first time and no account exists, Label Studio automatically creates the account: + +- The user is created with the email from the SAML assertion. +- First name and last name are set from the assertion attributes (if mapped). +- The user is added to the organization with the **organization's default role**. +- Group mappings are then applied: org role, workspaces, and projects are assigned based on the SAML groups attribute. + +On subsequent SAML logins, the user's name is updated from the assertion, and group mappings are re-evaluated (roles, workspaces, projects are synced to match current group membership). + +### NameID format + +Label Studio uses `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` as the default NameID format. The user's identity is resolved from the configured email attribute in the assertion, not from the NameID value. + +## SAML user lifecycle + +| Event | What happens in Label Studio | +| --- | --- | +| **First SAML login (new user)** | Account created (JIT), added to org with default role, then group mappings applied immediately. | +| **First SAML login (existing user, different org)** | User added to this org with default role, group mappings applied. | +| **Subsequent SAML login** | Name updated from assertion. Group mappings re-evaluated: roles, workspaces, and projects synced to match current groups (subject to manual management flags). | +| **User removed from all role groups** | If `manual_role_management` is off: role set to Deactivated on next login. If on: role unchanged. | +| **User removed from Entra ID app assignment** | No automatic change in Label Studio---user simply cannot authenticate via SSO anymore. Pair with SCIM deactivation for full lifecycle management. | + + +## SAML and SCIM interaction + +If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions: + +- **Group mappings are configured separately.** SAML settings (`/api/saml/settings`) and SCIM settings (`/api/scim/settings`) each have their own `roles_groups`, `workspaces_groups`, and `projects_groups`. You can configure identical mappings in both, or use different mappings for each protocol. +- **SCIM project mappings take precedence over SAML.** When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts. +- **Deleting SAML settings clears SCIM group assignments.** Using `DELETE /api/saml/settings` wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward. +- **`manual_role_management` is shared.** The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior. +- **SSO login can still change roles even with SCIM.** If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes---potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two. + +For more information on SCIM setup, see [Set up SCIM2 for Label Studio](scim_setup.html). ## Manage user access only with SSO @@ -139,6 +269,15 @@ MANUAL_ROLE_MANAGEMENT=0 Setting these options disables the Label Studio API and UI options to assign roles and workspaces for specific users within Label Studio and relies entirely on the settings in the environment variable file. +| Flag | Scope | Default | Effect when disabled (`0` / `False`) | +| --- | --- | --- | --- | +| `MANUAL_ROLE_MANAGEMENT` | Org roles | `True` (manual allowed) | Org roles are managed exclusively by SAML/SCIM. Users removed from all role groups are set to Deactivated. Overridable per-org in SAML settings. | +| `MANUAL_WORKSPACE_MANAGEMENT` | Workspaces | `True` (manual allowed) | Workspace membership is managed exclusively by SAML/SCIM. On each SAML login, workspaces are fully re-synced from groups. SCIM removes workspace memberships when users leave groups. | +| `MANUAL_PROJECT_MEMBER_MANAGEMENT` | Projects | `True` (manual allowed) | Project membership is managed exclusively by SAML/SCIM. Project memberships are removed when users leave groups. | + +!!! note + The `manual_role_management` flag has a per-organization override in SAML settings (`SamlSettings.manual_role_management`). When set, the SAML override takes precedence over the environment/billing default for both SAML and SCIM role removal behavior. + !!! info Tip If you are using the SaaS version of Label Studio (Label Studio Enterprise Cloud) and would like to enable these restrictions for your organization, [open a ticket](https://support.humansignal.com/hc/en-us/requests/new) to submit your request. @@ -146,4 +285,48 @@ Setting these options disables the Label Studio API and UI options to assign rol ### Login page URL -You can also set the `LOGIN_PAGE_URL` environment variable to redirect the login page to the specified URL. \ No newline at end of file +You can also set the `LOGIN_PAGE_URL` environment variable to redirect the login page to the specified URL. + +## Troubleshooting SAML SSO + +### SSO login redirects to an error page + +- Verify the **ACS URL** in your IdP matches exactly what Label Studio shows in SSO & SAML settings. +- Verify the IdP metadata (URL or XML) is correctly configured in Label Studio. +- Check that the **domain** in Label Studio SAML settings matches the user's email domain. +- Ensure the user is assigned to the Enterprise Application in your IdP. + +### User created with wrong role after SSO login + +- Verify the `mapping_groups` attribute name matches what your IdP sends (check the SAML assertion). +- For Entra ID: ensure it sends **group names** (not Object IDs) in the groups claim. +- Verify the group name in your IdP exactly matches (case-sensitive) the name in Label Studio SAML settings. +- If using both SAML and SCIM with different role mappings, the last one to run wins. + +### Attributes not being extracted from SAML assertion + +- Use a SAML debugging tool (e.g. browser extension) to inspect the raw assertion and confirm attribute names. +- Label Studio auto-detects attribute name format (URI vs short name) from metadata, but may not always match. Configure `mapping_email`, `mapping_first_name`, etc. explicitly if auto-detection fails. +- Entra ID full URI attribute names are case-sensitive. + +### Email case mismatches + +Label Studio normalizes all emails to lowercase for both SAML and SCIM operations. `Alice@Contoso.com` and `alice@contoso.com` are treated as the same user. No special configuration is needed. + +### Group name mismatches + +Group name matching in SAML settings is **case-sensitive**. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. + + +## Advanced SAML configuration + +For advanced SAML configuration, the following environment variables control pysaml2 SP behavior: + +| Variable | Default | Description | +| --- | --- | --- | +| `SAML_ALLOW_UNSOLICITED` | (pysaml2 default) | Accept IdP-initiated SSO | +| `SAML_AUTHN_REQUESTS_SIGNED` | (pysaml2 default) | Sign authentication requests | +| `SAML_WANT_ASSERTIONS_SIGNED` | (pysaml2 default) | Require signed assertions | +| `SAML_WANT_RESPONSE_SIGNED` | (pysaml2 default) | Require signed responses | +| `SAML_WANT_ASSERTIONS_OR_RESPONSE_SIGNED` | (pysaml2 default) | Require at least one signed | +| `DISABLE_SAML_SSL_VALIDATION` | (not set) | Disable SSL cert validation for metadata fetch | diff --git a/docs/source/guide/scim_setup.md b/docs/source/guide/scim_setup.md index e156cd7230d6..a7c34b2223f5 100644 --- a/docs/source/guide/scim_setup.md +++ b/docs/source/guide/scim_setup.md @@ -31,7 +31,7 @@ For more information on SCIM workflows, see [How SCIM works with Label Studio En !!! note Okta or similar SSO providers have SCIM integration based on SSO. -* You will need to provide a [Legacy token](access_tokens#Legacy-tokens), and it must be associated with the Owner role of your organization. +* You will need a Label Studio API token from the organization owner. Both [Legacy tokens](access_tokens#Legacy-tokens) and JWT-based Personal Access Tokens (PATs) are supported. ## Set up SCIM integration with Okta @@ -151,45 +151,246 @@ To unassign a group from the application, follow the steps for [Unassigning the ## Set up SCIM with Microsoft Entra ID (Azure AD) -Label Studio Enterprise supports SCIM provisioning with Microsoft Entra ID (formerly Azure AD). The setup is similar to Okta, but requires specific attribute mapping configuration. +Label Studio Enterprise supports SCIM provisioning with Microsoft Entra ID (formerly Azure AD). You can use the same Enterprise Application created for SAML SSO, or create a separate one for SCIM provisioning. Using the same application is simpler when you want both SSO and provisioning. -### Supported user attributes +### Step 1: Create or reuse the Enterprise Application -Label Studio Enterprise supports a limited set of SCIM user attributes for provisioning. When configuring attribute mappings in Microsoft Entra ID, only include the attributes listed below. +If creating a new application specifically for SCIM: -| SCIM Attribute | Description | Required | -|---|---|---| -| `emails[type eq "work"].value` | User's email address (primary identifier) | Yes | -| `userName` | Username (mapped to email in Label Studio) | Yes | -| `active` | Whether the user is active | Yes | -| `name.givenName` | User's first name | No | -| `name.familyName` | User's last name | No | +1. In the Azure Portal, go to **Entra ID → Enterprise Applications → New Application**. +2. Select **Create your own application** → **Integrate any other application not found in the gallery**. +3. Name it (e.g. `Label Studio SCIM`) and create it. + +### Step 2: Enable provisioning + +1. Open your Enterprise Application → **Provisioning** → **Get started**. +2. Set **Provisioning Mode** to **Automatic**. +3. Under **Admin Credentials**: + - **Tenant URL**: `https:///scim/v2` (both `/scim/v2` and `/scim/` are accepted) + - **Secret Token**: A Label Studio API token from the organization owner (legacy token or PAT) +4. Click **Test Connection** to verify connectivity. +5. Click **Save**. + +### Step 3: Configure user attribute mappings + +Go to **Provisioning → Mappings → Provision Microsoft Entra ID Users**. + +#### Required mappings + +| Entra ID Attribute | SCIM Target Attribute | Required | Notes | +| --- | --- | --- | --- | +| `userPrincipalName` | `userName` | **Yes** | Must be a valid email address. Label Studio uses this as the user's email and login identifier. If your UPNs are not email addresses, map `mail` instead. | +| `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | `active` | **Yes** | Controls user activation/deactivation. When set to `false`, the user's org role becomes **Deactivated**. | + +#### Recommended mappings + +| Entra ID Attribute | SCIM Target Attribute | Required | Notes | +| --- | --- | --- | --- | +| `givenName` | `name.givenName` | No | First name, displayed in the Label Studio UI. | +| `surname` | `name.familyName` | No | Last name, displayed in the Label Studio UI. | + +#### Optional mappings (no effect) + +These attributes are accepted by the SCIM endpoint but have no functional impact in Label Studio: + +| Entra ID Attribute | SCIM Target Attribute | Notes | +| --- | --- | --- | +| `objectId` | `externalId` | Ignored on write---Label Studio always returns the user's email as `externalId` regardless of the inbound value. | +| `displayName` | `displayName` | Read-only in Label Studio; always derived from `first_name + last_name`. | +| `preferredLanguage` | `locale` | Ignored; always returns `en-US`. | + +#### Mappings to remove !!! warning "Unsupported attributes cause provisioning errors" - Mapping attributes that Label Studio does not support will result in **HTTP 501 (Not Implemented)** errors during SCIM provisioning. You must remove all excess Microsoft Entra ID attribute mappings like these: + Remove any default Entra ID mappings that target attributes not supported by Label Studio's SCIM endpoint. Leaving unsupported mappings in place will result in **HTTP 501 (Not Implemented)** errors during provisioning. Common mappings to remove: - * `displayName` - * `preferredLanguage` + * `mailNickname` + * `facsimileTelephoneNumber` + * `mobile` + * `physicalDeliveryOfficeName` + * `streetAddress`, `state`, `postalCode`, `country` * `name.formatted` - * `externalId` - -### Configure Microsoft Entra ID provisioning - -1. In the [Microsoft Entra admin center](https://entra.microsoft.com), select **Enterprise apps** in the left menu. -2. Select your enterprise application. -3. Select **Provisioning** in the left menu. -4. Set the **Tenant URL** to `https:///scim/v2/`. -5. Set the **Secret Token** to the [Legacy token](access_tokens#Legacy-tokens) associated with the Owner account in Label Studio. - - This must be the Legacy token, not the Personal Access Token. It must also be associated with the user in the Owner role. -6. Under **Mappings**, open **Provision Microsoft Entra ID Users**. -7. Remove all attribute mappings except the supported ones listed above. - - Keep: - * `emails[type eq "work"].value` → `userPrincipalName` - * `userName` → `userPrincipalName` - * `active` → `Switch([IsSoftDeleted], , "False", "True", "True", "False")` - * `name.givenName` → `givenName` - * `name.familyName` → `surname` -8. Under **Mappings**, open **Provision Microsoft Entra ID Groups** and ensure it is enabled if you want to use group-based role assignment. -9. For group provisioning, configure SCIM group settings in Label Studio (see [Set up group mapping](#set-up-group-mapping) above). + * Any `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:*` attributes + +!!! note + Entra ID typically does **not** send the `emails` array in its SCIM payloads. Label Studio derives the email from `userName` when `emails` is absent, as long as `userName` is a valid email address. If your tenant's UPNs are not email addresses (e.g. `jsmith@contoso.local`), map `mail` to `userName` instead. + +### Step 4: Configure group provisioning + +Go to **Provisioning → Mappings → Provision Microsoft Entra ID Groups**. + +#### Required group mappings + +| Entra ID Attribute | SCIM Target Attribute | Required | Notes | +| --- | --- | --- | --- | +| `displayName` | `displayName` | **Yes** | The group name. This value must **exactly match** (case-sensitive) the group names configured in Label Studio's SCIM settings. | +| `members` | `members` | **Yes** | The list of group members. Entra ID sends member additions/removals as PATCH operations. | + +#### Assigning groups to the application + +Only groups that are **assigned to the Enterprise Application** in Entra ID will be provisioned: + +1. Go to **Enterprise Application → Users and groups → Add user/group**. +2. Select the security groups you want to provision. +3. Click **Assign**. + +The `displayName` of each assigned group is what Label Studio uses to match against its mapping rules. + +### Step 5: Configure SCIM group mappings in Label Studio + +This is where you tell Label Studio what each Entra ID group **means**---which role, workspace, or project access it grants. + +Configure mappings via the API: + +```bash +curl -X POST "https:///api/scim/settings" \ + -H "Authorization: Token " \ + -H "Content-Type: application/json" \ + -d '{ + "roles_groups": [ + ["Administrator", "LS-Admins"], + ["Manager", "LS-Managers"], + ["Reviewer", "LS-Reviewers"], + ["Annotator", "LS-Annotators"] + ], + "workspaces_groups": [ + ["Engineering", "LS-Engineering-Team"], + ["QA", "LS-QA-Team"] + ], + "projects_groups": [ + {"project_id": 42, "group": "LS-Project42-Annotators", "role": "Annotator"}, + {"project_id": 42, "group": "LS-Project42-Reviewers", "role": "Reviewer"}, + {"project_id": 99, "group": "LS-AllProjects", "role": "Inherit"} + ] + }' +``` + +Or configure them in the Label Studio UI under **Organization → SCIM Settings**. + +For detailed information on the mapping format and behavior, see [Group mapping reference](#group-mapping-reference) below. + +### Step 6: Start provisioning + +1. Go to **Provisioning → Overview**. +2. Click **Start provisioning**. +3. Entra ID will perform an initial sync cycle (can take 20--40 minutes for the first cycle). +4. Subsequent incremental syncs run approximately every 40 minutes. + +You can trigger an on-demand sync from the **Provision on demand** option for individual users. + + +## Group mapping reference + +Both SAML and SCIM use the same group mapping format and the same underlying mapping logic. The mapping types are configured independently for each protocol (SAML settings and SCIM settings are separate), but the behavior is identical. + +### Organization role mapping (`roles_groups`) + +Maps a group from your IdP to an organization-level role. + +**Format:** `["", ""]` + +**Available roles:** + +| Role Name | Description | +| --- | --- | +| `Administrator` | Full organization admin access | +| `Manager` | Can manage projects and members | +| `Reviewer` | Can review annotations | +| `Annotator` | Can annotate tasks | + +!!! note + `Owner` cannot be assigned via SAML or SCIM---it is explicitly excluded from group mappings. `Not Activated` and `Deactivated` are internal system states managed automatically and should not be used in `roles_groups` mappings. + +**Behavior when a user is in multiple role groups:** The most elevated role wins. For example, if a user is in both an Annotator group and a Manager group, they get the Manager role. + +**Behavior when a user is removed from all role groups:** Their role is set to Deactivated (subject to the `manual_role_management` flag). + +### Workspace mapping (`workspaces_groups`) + +Maps a group from your IdP to a Label Studio workspace. + +**Format:** `["", ""]` + +- Workspaces are **automatically created** when a SCIM group push or SAML login triggers the mapping. However, the `/api/scim/settings` endpoint validates that referenced workspaces already exist---create them first, or use the UI to save settings. +- A user can be mapped to multiple workspaces through multiple group memberships. +- **SCIM:** removal respects the `manual_workspace_management` billing flag---if enabled, users are not automatically removed from workspaces when they leave a group. +- **SAML:** workspace sync behavior is controlled by the `MANUAL_WORKSPACE_MANAGEMENT` environment variable (default: `True`). When `False`, all SAML-mapped workspaces are reset and re-applied on each login. + +### Project role mapping (`projects_groups`) + +Maps a group from your IdP to membership in a specific project, with a project-level role. + +**Format:** `{"project_id": , "group": "", "role": ""}` + +**Available project roles:** + +| Role | Description | +| --- | --- | +| `Inherit` | User gets project access but inherits their organization role (no explicit project role assigned) | +| `Annotator` | Explicit annotator role on the project | +| `Reviewer` | Explicit reviewer role on the project | + +- `project_id` must be an existing project in your organization. +- The most elevated role wins when a user is in multiple groups mapped to the same project. +- Removal respects the `manual_project_member_management` billing flag. +- **When SCIM project group assignments exist for a user, SAML project sync is skipped** for that user to avoid conflicts. + + +## SCIM user lifecycle + +| Event | What happens in Label Studio | +| --- | --- | +| **User provisioned** | Account created with the organization's default role (configured in Organization settings). Role is then updated when group sync runs. | +| **User already exists in another org** | User is added to this organization with the default role. Profile fields (name, etc.) are **not** overwritten---only the org membership is created. | +| **User added to a role group** | Role upgraded to the mapped role (or highest if in multiple groups). | +| **User removed from a role group** | Role falls back to the next-highest mapped role, or Deactivated if no role groups remain (subject to `manual_role_management`). | +| **User deactivated in Entra ID / Okta** | `active` set to `false` → role becomes Deactivated. | +| **User reactivated in Entra ID / Okta** | `active` set to `true` → role restored from SCIM group mappings, or the organization's default role if no mappings exist. | +| **User deleted in Entra ID / Okta** | Soft-deleted in Label Studio (deactivated, not removed). | + + +## SAML and SCIM interaction + +If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions: + +- **Group mappings are configured separately.** SAML settings (`/api/saml/settings`) and SCIM settings (`/api/scim/settings`) each have their own `roles_groups`, `workspaces_groups`, and `projects_groups`. You can configure identical mappings in both, or use different mappings for each protocol. +- **SCIM project mappings take precedence over SAML.** When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts. +- **Deleting SAML settings clears SCIM group assignments.** Using `DELETE /api/saml/settings` wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments. +- **`manual_role_management` is shared.** The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior. +- **SSO login can still change roles even with SCIM.** If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes---potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two. + +For more information on SAML SSO setup, see [Set up SSO authentication for Label Studio](auth_setup.html). + + +## Troubleshooting + +### Provisioning test connection fails + +- Verify the SCIM endpoint URL ends with `/scim/v2` (or `/scim/`). +- Verify the bearer token belongs to the **organization owner** (SCIM API requires owner-level authentication). Both legacy API tokens and PATs are accepted. +- Check that the Label Studio instance is reachable from the internet (or via your network configuration). + +### User created but has wrong role + +1. Verify the user is assigned to the correct group in your IdP. +2. Verify the group is assigned to the Enterprise Application (in Entra ID) or pushed to the application (in Okta). +3. Verify the group `displayName` in your IdP exactly matches (case-sensitive) the name in Label Studio SCIM settings. +4. Ensure a provisioning cycle has completed after the group assignment (or trigger on-demand provisioning). + +### Users not appearing in workspaces or projects + +- Group provisioning must be enabled in the attribute mappings. +- The group must be **assigned** to the Enterprise Application (just existing in Entra ID is not enough). +- SCIM group settings in Label Studio must be configured **before** or **at the same time as** the groups are pushed. If settings are configured after groups were already synced, save the SCIM settings again to trigger re-evaluation. + +### Unsupported attribute errors in provisioning logs + +Remove any default IdP attribute mappings that target attributes not in the Label Studio SCIM schema. See the [Mappings to remove](#mappings-to-remove) section above for common attributes to remove. + +### Email case mismatches + +Label Studio normalizes all emails to lowercase for both SAML and SCIM operations. `Alice@Contoso.com` and `alice@contoso.com` are treated as the same user. No special configuration is needed. + +### Group name mismatches + +Group name matching in SCIM settings is **case-sensitive**. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. From 85adc0b3665877a3c49787f61fdab84cad48259c Mon Sep 17 00:00:00 2001 From: Caitlin Date: Wed, 22 Apr 2026 21:25:39 -0500 Subject: [PATCH 2/6] updating to match UI --- docs/source/guide/auth_setup.md | 38 +++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/source/guide/auth_setup.md b/docs/source/guide/auth_setup.md index 8fae8e9c6ef2..db6694f20a98 100644 --- a/docs/source/guide/auth_setup.md +++ b/docs/source/guide/auth_setup.md @@ -22,20 +22,25 @@ To more easily [manage access to Label Studio Enterprise](manage_users.html), yo ## Set up SAML SSO -The organization Owner or Administrator for Label Studio Enterprise can set up SSO & SAML for the instance. Label Studio Enterprise supports the following IdPs: +The organization Owner or Administrator for Label Studio Enterprise can set up SSO & SAML. + +Label Studio Enterprise supports the following IdPs: - [Okta](https://www.youtube.com/watch?v=Dr-_hyWIw4M) - [Google SAML](google_saml.html) - [Ping Federate and Ping Identity SAML SSO Setup Example](pingone.html) -- OneLogin - Microsoft Entra ID (formerly Azure Active Directory, Azure AD) - Auth0 - Others that use SAML assertions -After setting up the SSO, you can use native authentication to access the Label Studio UI, however it's not a recommended option especially for the user with the Owner role. +After setting up the SSO, you can use native authentication to access the Label Studio UI. -- You can use SSO along with normal login. This is not a recommended option. +- You can use SSO along with a normal login. This is not a recommended option, especially for the user in the Owner role. -- You can prevent a user from creating his own organization by using [DISABLE_SIGNUP_WITHOUT_LINK](admin_user#Require-invites-for-new-users) option. +- You can prevent users from registering a new account through the `/user/signup` page by setting the following environment variable: + +```bash +LABEL_STUDIO_DISABLE_SIGNUP_WITHOUT_LINK=true +``` ### Connect your Identity Provider to Label Studio Enterprise @@ -45,14 +50,13 @@ The details will vary depending on your IdP, but in general you will complete th #### From Label Studio: -1. Go to the **Organization** page. +1. Go to **Organization > Security > SSO & SCIM**. If you do not see the option to select **Organization**, you are not logged in with the appropriate role. -2. Select **SSO & SAML** in the upper right. -3. In the **Organization** field, ensure the domain matches the domain used for your organization in your IdP. -4. Copy the following URLs: - - * **Assertion Consumer Service (ACS) URL with Audience (EntityID), and Recipient (Reply) details**---The IdP uses this URL to redirect users to after a successful authentication. Format: `https:///saml//acs` +2. Under **Domain**, ensure the domain matches the domain used for your organization in your IdP. Click **Next**. +3. Select your IdP and copy the service provider details: + * **ACS URL**---The IdP uses this URL to redirect users to after a successful authentication. Format: `https:///saml//acs` + * **Entity ID**---The IdP uses this URL to identify the service provider. Format: `https:///saml//acs` * **Login URL**---This is the URL that users will use to log in to Label Studio. Format: `https:///saml//login` * **Logout URL**---This is the URL used to redirect users after successfully logging out of Label Studio. Format: `https:///saml//logout` @@ -74,8 +78,10 @@ The details will vary depending on your IdP, but in general you will complete th | Last or family name | LastName | | Group name | Groups | -!!! note Note - Different Identity Providers use different attribute names. Label Studio provides **presets** in the SSO & SAML settings page to quickly configure the correct attribute mappings for popular IdPs. You can also manually configure custom attribute names if your IdP uses different values. +!!! info Tip + Different Identity Providers use different attribute names. + + Label Studio provides presets in the SSO & SAML settings page to quickly configure the correct attribute mappings for popular IdPs. You can also manually configure custom attribute names if your IdP uses different values. **Attribute presets by IdP:** @@ -100,7 +106,11 @@ If your Entra ID is configured with default claim URIs, use: | Groups | `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` | !!! warning "Important: Group names vs. Object IDs in Entra ID" - If you use group-based mappings (roles, workspaces, projects), you must configure Entra ID to send **group names** (not Object IDs) in the groups claim. In **User Attributes & Claims → Groups returned in claim**, select **Groups assigned to the application** and set **Source attribute** to `sAMAccountName` or another human-readable group property. Sending Object IDs instead of names will prevent group mappings from working correctly. + If you use group-based mappings (roles, workspaces, projects), you must configure Entra ID to send **group names** (not Object IDs) in the groups claim. + + In **User Attributes & Claims > Groups returned in claim**, select **Groups assigned to the application** and set **Source attribute** to `sAMAccountName` or another human-readable group property. + + Sending Object IDs instead of names will prevent group mappings from working correctly. #### From Label Studio: From d19b9abaf7b45f6451c9b98dc52186990e7dd13a Mon Sep 17 00:00:00 2001 From: Caitlin Date: Thu, 23 Apr 2026 11:21:25 -0500 Subject: [PATCH 3/6] restructuring page --- docs/source/guide/auth_setup.md | 211 ++++++++++++++++++-------------- 1 file changed, 116 insertions(+), 95 deletions(-) diff --git a/docs/source/guide/auth_setup.md b/docs/source/guide/auth_setup.md index db6694f20a98..ff54e348b7a2 100644 --- a/docs/source/guide/auth_setup.md +++ b/docs/source/guide/auth_setup.md @@ -20,7 +20,7 @@ Set up single sign-on using SAML to manage access to Label Studio using your exi To more easily [manage access to Label Studio Enterprise](manage_users.html), you can map SAML groups to both `roles` or `workspaces`. -## Set up SAML SSO +## SAML SSO in Label Studio Enterprise The organization Owner or Administrator for Label Studio Enterprise can set up SSO & SAML. @@ -28,46 +28,50 @@ Label Studio Enterprise supports the following IdPs: - [Okta](https://www.youtube.com/watch?v=Dr-_hyWIw4M) - [Google SAML](google_saml.html) - [Ping Federate and Ping Identity SAML SSO Setup Example](pingone.html) -- Microsoft Entra ID (formerly Azure Active Directory, Azure AD) +- [Microsoft Entra ID (formerly Azure Active Directory, Azure AD)](#IdP-specific-setup-guides) - Auth0 - Others that use SAML assertions -After setting up the SSO, you can use native authentication to access the Label Studio UI. +!!! note + After setting up the SSO, you can use native authentication to access the Label Studio UI. -- You can use SSO along with a normal login. This is not a recommended option, especially for the user in the Owner role. + Note that you can use SSO along with a normal login. However, this is not a recommended option, especially for the user in the Owner role. -- You can prevent users from registering a new account through the `/user/signup` page by setting the following environment variable: -```bash -LABEL_STUDIO_DISABLE_SIGNUP_WITHOUT_LINK=true -``` -### Connect your Identity Provider to Label Studio Enterprise +## Set up SAML SSO (general steps) Set up Label Studio Enterprise as a Service Provider (SP) with your Identity Provider (IdP) to use SAML authentication. -The details will vary depending on your IdP, but in general you will complete the following steps: +The details will vary depending on your IdP, but in general you will complete the following steps. -#### From Label Studio: +For more information on setting up SAML SSO with specific IdPs, see the [IdP-specific setup guides](#IdP-specific-setup-guides). + +### Step 1: Set domain and gather URLs from Label Studio 1. Go to **Organization > Security > SSO & SCIM**. If you do not see the option to select **Organization**, you are not logged in with the appropriate role. 2. Under **Domain**, ensure the domain matches the domain used for your organization in your IdP. Click **Next**. -3. Select your IdP and copy the service provider details: +3. Under **Configure SAML**, select your IdP and copy the service provider details: * **ACS URL**---The IdP uses this URL to redirect users to after a successful authentication. Format: `https:///saml//acs` * **Entity ID**---The IdP uses this URL to identify the service provider. Format: `https:///saml//acs` - * **Login URL**---This is the URL that users will use to log in to Label Studio. Format: `https:///saml//login` - * **Logout URL**---This is the URL used to redirect users after successfully logging out of Label Studio. Format: `https:///saml//logout` + +Before continuing, you will need return to your IdP and use the ACS URL and Entity ID to generate a metadata XML file or a metadata URL from your IdP. !!! note + If you want to provide login/logout URLs, you can use the following format: + * **Login URL**---`https:///saml//login` + * **Logout URL**---`https:///saml//logout` + Label Studio does not implement SAML Single Logout (SLO) to the IdP. The logout URL only ends the local Label Studio session. -#### From your IdP: + +### Step 2: Get metadata from your IdP 1. Paste the URLs copied from Label Studio in the appropriate location. 2. Generate a metadata XML file, or a URL that specifies the metadata for the IdP. -3. Set up or confirm setup of the following SAML attributes. Label Studio Enterprise expects specific attribute mappings for user identities. +3. Set up or confirm setup of the following SAML attributes. Label Studio expects specific attribute mappings for user identities. **The default attribute names are:** @@ -112,29 +116,31 @@ If your Entra ID is configured with default claim URIs, use: Sending Object IDs instead of names will prevent group mappings from working correctly. -#### From Label Studio: +### Step 3: Add the metadata to Label Studio and verify SAML attributes -1. Return to the SSO & SAML page. -2. Upload the metadata XML file or specify the metadata URL. -3. Select the appropriate IdP provider preset (e.g. `azure` for Entra ID) to auto-fill attribute mapping names, or configure them manually to match what your IdP sends. -4. Set up group mappings. These can also be added or edited later. +1. Return to the **Configure SAML** step. +2. Upload the metadata XML file or specify the metadata URL. Click **Save and continue**. +3. Under **SAML Attributes**, you will see your attribute mapping names pre-filled using presets. You can also configure these manually to match what your IdP sends. - Ensure the group name you enter is the same as the group name sent as an attribute in a SAML authentication response by your IdP. +### Step 4: Set up group mappings - * **Organization Roles to Groups Mapping**---Map groups to roles at the organization level. The role set at the organization level is the default role of the user and is automatically assigned to workspaces and projects. For more information on roles, see [Roles in Label Studio Enterprise](manage_users#Roles-in-Label-Studio-Enterprise). +Under the the **Configure SAML** step, you can set up group mappings. These can also be added or edited later. + +Ensure the group name you enter is the same as the group name sent as an attribute in a SAML authentication response by your IdP. + +* **Organization Roles to Groups Mapping**---Map groups to roles at the organization level. The role set at the organization level is the default role of the user and is automatically assigned to workspaces and projects. For more information on roles, see [Roles in Label Studio Enterprise](manage_users#Roles-in-Label-Studio-Enterprise). - You can map multiple groups to the same role. Note that users who are **Not Activated** or **Deactivated** do not count towards the seat limit for your account. - * **Workspaces to Groups Mapping**---Add groups as members to workspaces. Users with Manager, Reviewer, or Annotator roles can only see workspaces after they've been added as a member to that workspace. + You can map multiple groups to the same role. Note that users who are **Not Activated** or **Deactivated** do not count towards the seat limit for your account. +* **Workspaces to Groups Mapping**---Add groups as members to workspaces. Users with Manager, Reviewer, or Annotator roles can only see workspaces after they've been added as a member to that workspace. - Select an existing workspace or create a new one. You can map multiple groups to the same workspace. - * **Projects to Groups Mapping**---Map groups to roles at the project level. Project-level roles can be **Annotator**, **Reviewer**, or **Inherit**. + Select an existing workspace or create a new one. You can map multiple groups to the same workspace. +* **Projects to Groups Mapping**---Map groups to roles at the project level. Project-level roles can be **Annotator**, **Reviewer**, or **Inherit**. - You can map a group to different roles across multiple projects. You can also map multiple groups to the same roles and the same projects. For more information on roles, see [Roles in Label Studio Enterprise](manage_users#Roles-in-Label-Studio-Enterprise). + You can map a group to different roles across multiple projects. You can also map multiple groups to the same roles and the same projects. For more information on roles, see [Roles in Label Studio Enterprise](manage_users#Roles-in-Label-Studio-Enterprise). - If you select **Inherit**, the group will inherit the role set above under **Organization Roles to Groups Mapping.** If the group is inheriting the Not Activated role, the users are mapped to the project, but they are not actually assigned to the project until the group is synced (meaning that the user authenticates with SSO). -5. Click **Save**. + If you select **Inherit**, the group will inherit the role set above under **Organization Roles to Groups Mapping.** If the group is inheriting the Not Activated role, the users are mapped to the project, but they are not actually assigned to the project until the group is synced (meaning that the user authenticates with SSO). -6. Test the configuration by logging in to Label Studio Enterprise with your SSO account. +Click **Save**. Test the configuration by logging in to Label Studio Enterprise with your SSO account. #### Group mapping behavior @@ -144,10 +150,12 @@ If your Entra ID is configured with default claim URIs, use: | Workspaces (`workspaces_groups`) | A user can be mapped to multiple workspaces through multiple group memberships. Workspaces are automatically created if they do not exist when a mapping is triggered. | | Projects (`projects_groups`) | Format: `{"project_id": , "group": "", "role": ""}`. Available project roles: Annotator, Reviewer, or Inherit. The most elevated role wins when a user is in multiple groups mapped to the same project. | -!!! note - Group name matching is **case-sensitive** for all mapping types. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. +!!! warning "Important" + **Group name matching is case-sensitive for all mapping types.** + + `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. -### SAML SSO Settings API +## SAML SSO Settings API You can also configure SAML settings programmatically using the API: @@ -188,47 +196,6 @@ curl -X POST "https:///api/saml/settings" \ }' ``` -### Setup SAML SSO with Okta video tutorial - - - -### Set up SAML SSO with Microsoft Entra ID - -To set up SAML SSO specifically with Microsoft Entra ID (formerly Azure AD): - -#### Step 1: Create the Enterprise Application in Entra ID - -1. In the Azure Portal, go to **Entra ID → Enterprise Applications → New Application**. -2. Select **Create your own application** → **Integrate any other application not found in the gallery**. -3. Name it (e.g. `Label Studio SSO`) and create it. - -#### Step 2: Configure SAML in Entra ID - -1. Go to **Single sign-on → SAML**. -2. Under **Basic SAML Configuration**: - - **Identifier (Entity ID)**: Paste the ACS URL from Label Studio. - - **Reply URL (ACS URL)**: Paste the same ACS URL. - - **Sign on URL**: Paste the Login URL from Label Studio. -3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#from-your-idp). -4. Under **SAML Signing Certificate**, download the **Federation Metadata XML** file (or copy the **App Federation Metadata URL**). - -#### Step 3: Configure SAML in Label Studio - -1. Go to **Organization → SSO & SAML**. -2. In the **Domain** field, enter the email domain(s) for your organization (comma-separated, e.g. `contoso.com`). This is used for domain-based SSO routing when users enter their email on the login page. -3. Upload the **Federation Metadata XML** file downloaded from Entra ID, or paste the **App Federation Metadata URL** in the metadata URL field. -4. Select `azure` as the IdP provider preset to auto-fill attribute mapping names, or configure them manually. -5. Configure group mappings as needed. -6. Click **Save**. - -#### Step 4: Assign users and test - -1. In Entra ID, go to **Enterprise Application → Users and groups → Add user/group**. -2. Assign users or groups to the application. -3. Test by navigating to the Label Studio Login URL, or by going to `https:///saml/sso-domain` and entering your email---Label Studio will look up the SAML config by domain and redirect to Entra ID. -4. After authenticating with Entra ID, you should be redirected back to Label Studio and logged in. - - ## JIT (Just-In-Time) provisioning When a user authenticates via SAML for the first time and no account exists, Label Studio automatically creates the account: @@ -297,46 +264,100 @@ Setting these options disables the Label Studio API and UI options to assign rol You can also set the `LOGIN_PAGE_URL` environment variable to redirect the login page to the specified URL. +### Disable signup without link + +You can prevent users from registering a new account through the `/user/signup` page by setting the following environment variable: + +```bash +LABEL_STUDIO_DISABLE_SIGNUP_WITHOUT_LINK=true +``` + + +## Advanced SAML configuration + +For advanced SAML configuration, the following environment variables control pysaml2 SP behavior: + +| Variable | Default | Description | +| --- | --- | --- | +| `SAML_ALLOW_UNSOLICITED` | (pysaml2 default) | Accept IdP-initiated SSO | +| `SAML_AUTHN_REQUESTS_SIGNED` | (pysaml2 default) | Sign authentication requests | +| `SAML_WANT_ASSERTIONS_SIGNED` | (pysaml2 default) | Require signed assertions | +| `SAML_WANT_RESPONSE_SIGNED` | (pysaml2 default) | Require signed responses | +| `SAML_WANT_ASSERTIONS_OR_RESPONSE_SIGNED` | (pysaml2 default) | Require at least one signed | +| `DISABLE_SAML_SSL_VALIDATION` | (not set) | Disable SSL cert validation for metadata fetch | + +## IdP-specific setup guides + +This section contains IdP-specific setup guides for SAML SSO. + +{% details Okta video tutorial %} + +{% enddetails %} + +{% details Microsoft Entra ID %} + +To set up SAML SSO specifically with Microsoft Entra ID (formerly Azure AD): + +#### Step 1: Create the Enterprise Application in Entra ID + +1. In the Azure Portal, go to **Entra ID → Enterprise Applications → New Application**. +2. Select **Create your own application** → **Integrate any other application not found in the gallery**. +3. Name it (e.g. `Label Studio SSO`) and create it. + +#### Step 2: Configure SAML in Entra ID + +1. Go to **Single sign-on → SAML**. +2. Under **Basic SAML Configuration**: + - **Identifier (Entity ID)**: Paste the ACS URL from Label Studio. + - **Reply URL (ACS URL)**: Paste the same ACS URL. + - **Sign on URL**: Paste the Login URL from Label Studio. +3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#from-your-idp). +4. Under **SAML Signing Certificate**, download the **Federation Metadata XML** file (or copy the **App Federation Metadata URL**). + +#### Step 3: Configure SAML in Label Studio + +1. Go to **Organization → SSO & SAML**. +2. In the **Domain** field, enter the email domain(s) for your organization (comma-separated, e.g. `contoso.com`). This is used for domain-based SSO routing when users enter their email on the login page. +3. Upload the **Federation Metadata XML** file downloaded from Entra ID, or paste the **App Federation Metadata URL** in the metadata URL field. +4. Select `azure` as the IdP provider preset to auto-fill attribute mapping names, or configure them manually. +5. Configure group mappings as needed. +6. Click **Save**. + +#### Step 4: Assign users and test + +1. In Entra ID, go to **Enterprise Application → Users and groups → Add user/group**. +2. Assign users or groups to the application. +3. Test by navigating to the Label Studio Login URL, or by going to `https:///saml/sso-domain` and entering your email---Label Studio will look up the SAML config by domain and redirect to Entra ID. +4. After authenticating with Entra ID, you should be redirected back to Label Studio and logged in. + +{% enddetails %} + ## Troubleshooting SAML SSO -### SSO login redirects to an error page +#### SSO login redirects to an error page - Verify the **ACS URL** in your IdP matches exactly what Label Studio shows in SSO & SAML settings. - Verify the IdP metadata (URL or XML) is correctly configured in Label Studio. - Check that the **domain** in Label Studio SAML settings matches the user's email domain. - Ensure the user is assigned to the Enterprise Application in your IdP. -### User created with wrong role after SSO login +#### User created with wrong role after SSO login - Verify the `mapping_groups` attribute name matches what your IdP sends (check the SAML assertion). - For Entra ID: ensure it sends **group names** (not Object IDs) in the groups claim. - Verify the group name in your IdP exactly matches (case-sensitive) the name in Label Studio SAML settings. - If using both SAML and SCIM with different role mappings, the last one to run wins. -### Attributes not being extracted from SAML assertion +#### Attributes not being extracted from SAML assertion - Use a SAML debugging tool (e.g. browser extension) to inspect the raw assertion and confirm attribute names. - Label Studio auto-detects attribute name format (URI vs short name) from metadata, but may not always match. Configure `mapping_email`, `mapping_first_name`, etc. explicitly if auto-detection fails. - Entra ID full URI attribute names are case-sensitive. -### Email case mismatches +#### Email case mismatches Label Studio normalizes all emails to lowercase for both SAML and SCIM operations. `Alice@Contoso.com` and `alice@contoso.com` are treated as the same user. No special configuration is needed. -### Group name mismatches - -Group name matching in SAML settings is **case-sensitive**. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. - - -## Advanced SAML configuration - -For advanced SAML configuration, the following environment variables control pysaml2 SP behavior: +#### Group name mismatches -| Variable | Default | Description | -| --- | --- | --- | -| `SAML_ALLOW_UNSOLICITED` | (pysaml2 default) | Accept IdP-initiated SSO | -| `SAML_AUTHN_REQUESTS_SIGNED` | (pysaml2 default) | Sign authentication requests | -| `SAML_WANT_ASSERTIONS_SIGNED` | (pysaml2 default) | Require signed assertions | -| `SAML_WANT_RESPONSE_SIGNED` | (pysaml2 default) | Require signed responses | -| `SAML_WANT_ASSERTIONS_OR_RESPONSE_SIGNED` | (pysaml2 default) | Require at least one signed | -| `DISABLE_SAML_SSL_VALIDATION` | (not set) | Disable SSL cert validation for metadata fetch | +Group name matching in SAML settings is **case-sensitive**. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. \ No newline at end of file From dd26bc225cc683a11e6714a7785c1bcb8f1bae23 Mon Sep 17 00:00:00 2001 From: Caitlin Date: Thu, 23 Apr 2026 12:54:05 -0500 Subject: [PATCH 4/6] updating scim page to match structure of sso page --- docs/source/guide/scim_setup.md | 353 ++++++++++++++++++++------------ 1 file changed, 217 insertions(+), 136 deletions(-) diff --git a/docs/source/guide/scim_setup.md b/docs/source/guide/scim_setup.md index a7c34b2223f5..f14c34606998 100644 --- a/docs/source/guide/scim_setup.md +++ b/docs/source/guide/scim_setup.md @@ -33,9 +33,171 @@ For more information on SCIM workflows, see [How SCIM works with Label Studio En * You will need a Label Studio API token from the organization owner. Both [Legacy tokens](access_tokens#Legacy-tokens) and JWT-based Personal Access Tokens (PATs) are supported. -## Set up SCIM integration with Okta +## Set up SCIM (general steps) -!!! attention "important" +The following steps apply to any SCIM 2.0-compatible identity provider. For IdP-specific walkthroughs, see [IdP-specific setup guides](#IdP-specific-setup-guides). + +### Step 1: Add Label Studio as an application in your IdP + +If you have not already created an application for Label Studio as part of your SSO setup, create one now in your IdP. SCIM provisioning is typically configured on the same application used for SSO (SAML 2.0). + +### Step 2: Enable SCIM provisioning + +In your IdP's application settings, enable SCIM (or "automatic") provisioning and configure the connection: + +| Setting | Value | +|---------|-------| +| **SCIM connector base URL** | `https:///scim/v2/` | +| **Authorization** | `Bearer `, where the token is a Label Studio API token from the organization owner. Both [Legacy tokens](access_tokens#Legacy-tokens) and JWT-based Personal Access Tokens (PATs) are supported. | +| **Unique identifier field for users** | `email` | + +After entering these values, use your IdP's **Test Connection** feature (if available) to verify that Label Studio is reachable and the token is valid. + +### Step 3: Configure user attribute mappings + +Map your IdP's user attributes to SCIM target attributes. The following attributes are supported by Label Studio: + +| SCIM Target Attribute | Required | Notes | +|-----------------------|----------|-------| +| `userName` | **Yes** | Must be a valid email address. Label Studio uses this as the user's login identifier and email. | +| `active` | **Yes** | Controls user activation and deactivation. When set to `false`, the user's role becomes **Deactivated**. | +| `name.givenName` | No | First name, displayed in the Label Studio UI. | +| `name.familyName` | No | Last name, displayed in the Label Studio UI. | + +!!! warning "Remove unsupported attribute mappings" + Many IdPs include default mappings for attributes that Label Studio does not support (e.g. phone numbers, addresses, enterprise extension attributes). Remove any mappings that are not listed above. Unsupported attributes will result in **HTTP 501** errors during provisioning. + +### Step 4: Enable provisioning actions + +Enable the following provisioning actions in your IdP (the exact labels vary by provider): + +- Create users +- Update user attributes +- Deactivate users + +### Step 5: Configure group provisioning + +If you plan to use groups to manage roles, workspace membership, and project access, enable group provisioning in your IdP. The required group attributes are: + +| SCIM Target Attribute | Required | Notes | +|-----------------------|----------|-------| +| `displayName` | **Yes** | The group name. This must **exactly match** (case-sensitive) the group names configured in Label Studio's SCIM settings. | +| `members` | **Yes** | The list of group members. | + +### Step 6: Configure group mappings in Label Studio + +In Label Studio, go to **Organization > Security > SSO & SCIM** to map your IdP groups to roles, workspaces, and projects: + +* **Organization Roles to Groups Mapping** -- Map groups to organization-level roles (Administrator, Manager, Reviewer, or Annotator). The most elevated role wins if a user belongs to multiple groups. For more information on roles, see [Roles in Label Studio Enterprise](admin_roles). +* **Workspaces to Groups Mapping** -- Add groups as members to workspaces. Users with Manager, Reviewer, or Annotator roles can only access workspaces they have been added to. +* **Projects to Groups Mapping** -- Map groups to project-level roles (Annotator, Reviewer, or Inherit). A group can have different roles across different projects. + +You can also configure these mappings via the API. For details, see [Group mapping reference](#Group-mapping-reference). + +### Step 7: Assign users and groups to the application + +In your IdP, assign the users and/or groups that should be provisioned to the Label Studio application. Only assigned users and groups are synced. + +### Step 8: Start provisioning + +Trigger an initial sync from your IdP. Depending on the provider, the first sync cycle may take longer than subsequent incremental syncs. Monitor your IdP's provisioning logs for errors. + +After provisioning completes, verify in Label Studio that users appear with the expected roles and group memberships. + + + + + + +## Group mapping reference + +Both SAML and SCIM use the same group mapping format and the same underlying mapping logic. The mapping types are configured independently for each protocol (SAML settings and SCIM settings are separate), but the behavior is identical. + +### Organization role mapping (`roles_groups`) + +Maps a group from your IdP to an organization-level role. + +**Format:** `["", ""]` + +**Available roles:** + +| Role Name | Description | +| --- | --- | +| `Administrator` | Full organization admin access | +| `Manager` | Can manage projects and members | +| `Reviewer` | Can review annotations | +| `Annotator` | Can annotate tasks | + +!!! note + `Owner` cannot be assigned via SAML or SCIM---it is explicitly excluded from group mappings. `Not Activated` and `Deactivated` are internal system states managed automatically and should not be used in `roles_groups` mappings. + +**Behavior when a user is in multiple role groups:** The most elevated role wins. For example, if a user is in both an Annotator group and a Manager group, they get the Manager role. + +**Behavior when a user is removed from all role groups:** Their role is set to Deactivated (subject to the `manual_role_management` flag). + +### Workspace mapping (`workspaces_groups`) + +Maps a group from your IdP to a Label Studio workspace. + +**Format:** `["", ""]` + +- Workspaces are **automatically created** when a SCIM group push or SAML login triggers the mapping. However, the `/api/scim/settings` endpoint validates that referenced workspaces already exist---create them first, or use the UI to save settings. +- A user can be mapped to multiple workspaces through multiple group memberships. +- **SCIM:** removal respects the `manual_workspace_management` billing flag---if enabled, users are not automatically removed from workspaces when they leave a group. +- **SAML:** workspace sync behavior is controlled by the `MANUAL_WORKSPACE_MANAGEMENT` environment variable (default: `True`). When `False`, all SAML-mapped workspaces are reset and re-applied on each login. + +### Project role mapping (`projects_groups`) + +Maps a group from your IdP to membership in a specific project, with a project-level role. + +**Format:** `{"project_id": , "group": "", "role": ""}` + +**Available project roles:** + +| Role | Description | +| --- | --- | +| `Inherit` | User gets project access but inherits their organization role (no explicit project role assigned) | +| `Annotator` | Explicit annotator role on the project | +| `Reviewer` | Explicit reviewer role on the project | + +- `project_id` must be an existing project in your organization. +- The most elevated role wins when a user is in multiple groups mapped to the same project. +- Removal respects the `manual_project_member_management` billing flag. +- **When SCIM project group assignments exist for a user, SAML project sync is skipped** for that user to avoid conflicts. + + +## SCIM user lifecycle + +| Event | What happens in Label Studio | +| --- | --- | +| **User provisioned** | Account created with the organization's default role (configured in Organization settings). Role is then updated when group sync runs. | +| **User already exists in another org** | User is added to this organization with the default role. Profile fields (name, etc.) are **not** overwritten---only the org membership is created. | +| **User added to a role group** | Role upgraded to the mapped role (or highest if in multiple groups). | +| **User removed from a role group** | Role falls back to the next-highest mapped role, or Deactivated if no role groups remain (subject to `manual_role_management`). | +| **User deactivated in Entra ID / Okta** | `active` set to `false` → role becomes Deactivated. | +| **User reactivated in Entra ID / Okta** | `active` set to `true` → role restored from SCIM group mappings, or the organization's default role if no mappings exist. | +| **User deleted in Entra ID / Okta** | Soft-deleted in Label Studio (deactivated, not removed). | + + +## SAML and SCIM interaction + +If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions: + +- **Group mappings are configured separately.** SAML settings (`/api/saml/settings`) and SCIM settings (`/api/scim/settings`) each have their own `roles_groups`, `workspaces_groups`, and `projects_groups`. You can configure identical mappings in both, or use different mappings for each protocol. +- **SCIM project mappings take precedence over SAML.** When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts. +- **Deleting SAML settings clears SCIM group assignments.** Using `DELETE /api/saml/settings` wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments. +- **`manual_role_management` is shared.** The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior. +- **SSO login can still change roles even with SCIM.** If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes---potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two. + +For more information on SAML SSO setup, see [Set up SSO authentication for Label Studio](auth_setup.html). + +## IdP-specific setup guides + +This section contains IdP-specific setup guides for SCIM. + +{% details Okta %} + +!!! warning "Important" This video demonstrates the use of `userName` in the 'Unique Identifier Field for Users' field. It is essential to use `email` as the unique identifier instead of `userName`; otherwise, SCIM will not function correctly with users who were created prior to the SCIM integration. @@ -44,14 +206,14 @@ To manage access to Label Studio Enterprise, add the application to your SCIM pr Okta uses a Bearer (request header should be `Authorization: Bearer `) token to interact with REST API endpoints of the application to provision and deprovision access. -### Add Label Studio Enterprise as an application (if not complete) +#### Step 1: Add Label Studio Enterprise as an application (if not complete) 1. Navigate to **Applications > Applications** in Okta. Click **Create App Integration**. 2. Select **SAML 2.0**. Enter an app name (for example, _Label Studio Enterprise_). 3. Under **Configure SAML**, set up the SAML integration following the steps outlined in [Set up SSO guide](auth_setup.html). 4. Make sure Label Studio Enterprise appears in the list of active applications. -### Enable SCIM provisioning +#### Step 2: Enable SCIM provisioning 1. Navigate to **Applications > Applications** in Okta. 2. Select **Label Studio Enterprise**. @@ -69,7 +231,7 @@ Complete the following fields: | **Supported provisioning actions** | Select the following items:
- Import New Users and Profile Updates
- Push New Users
- Push Profile Updates
- Push Groups | | **HTTP Header → `Authorization: Bearer `** | Enter the [Legacy token](access_tokens#Legacy-tokens) associated with the Owner account in Label Studio.
For Label Studio, `Token` and `Bearer` are the same tokens. However, it's important to use `Bearer` instead of `Token` in the request header. | -### SCIM settings and application triggers +#### Step 3: SCIM settings and application triggers 1. On the application page navigate to **Provisioning** tab and select **To App** in the left menu. Click **Edit** in the right corner. 2. Enable the following items: @@ -77,7 +239,7 @@ Complete the following fields: - Update User Attributes - Deactivate Users -### Assign the application to a single user +#### Step 4: Assign the application to a single user You can assign the application on both the **user** page and **application** page. @@ -88,40 +250,39 @@ You can assign the application on both the **user** page and **application** pag After you click **Done**, Okta will send the requests to create users accordingly in the Label Studio Enterprise. -### Unassigning the application for users +#### Step 5: Unassigning the application for users 1. On the application page navigate to **Assignments** tab. 2. Select **People** in the left menu. 3. Click the delete cross against the user you would like to unassign. 4. Confirm the unassignment. -### Assign the application to a group +#### Step 6: Assign the application to a group The most convenient way to manage access to the application is via groups. You can assign Label Studio to groups and manage the groups in Okta. The changes will be propagated to the application. -### Set up group mapping in Label Studio +#### Step 7: Set up group mapping in Label Studio -1. In Label Studio, click the menu in the upper left and select **Organization**. +In Label Studio, go to **Organization > Security > SSO & SCIM** to set up group mapping. -2. Select **SCIM** in the upper right. -3. Update roles and workspaces mapping. Ensure the group name you enter is the same as the group name being sent by your SCIM provider. +Here you can update roles and workspaces mapping. Ensure the group name you enter is the same as the group name being sent by your SCIM provider. For more information on group mapping, see [Group mapping reference](#Group-mapping-reference). - * **Organization Roles to Groups Mapping**---Map groups to roles at the organization level. The role set at the organization level is the default role of the user and is automatically assigned to workspaces and projects. For more information on roles, see [Roles in Label Studio Enterprise](admin_roles). +* **Organization Roles to Groups Mapping**---Map groups to roles at the organization level. The role set at the organization level is the default role of the user and is automatically assigned to workspaces and projects. For more information on roles, see [Roles in Label Studio Enterprise](admin_roles). - You can map multiple groups to the same role. Note that users who are **Not Activated** or **Deactivated** do not count towards the seat limit for your account. - * **Workspaces to Groups Mapping**---Add groups as members to workspaces. Users with Manager, Reviewer, or Annotator roles can only see workspaces after they've been added as a member to that workspace. + You can map multiple groups to the same role. Note that users who are **Not Activated** or **Deactivated** do not count towards the seat limit for your account. +* **Workspaces to Groups Mapping**---Add groups as members to workspaces. Users with Manager, Reviewer, or Annotator roles can only see workspaces after they've been added as a member to that workspace. - Select an existing workspace or create a new one. You can map multiple groups to the same workspace. - * **Projects to Groups Mapping**---Map groups to roles at the project level. Project-level roles can be **Annotator**, **Reviewer**, or **Inherit**. + Select an existing workspace or create a new one. You can map multiple groups to the same workspace. +* **Projects to Groups Mapping**---Map groups to roles at the project level. Project-level roles can be **Annotator**, **Reviewer**, or **Inherit**. - You can map a group to different roles across multiple projects. You can also map multiple groups to the same roles and the same projects. For more information on roles, see [Roles in Label Studio Enterprise](admin_roles). + You can map a group to different roles across multiple projects. You can also map multiple groups to the same roles and the same projects. For more information on roles, see [Roles in Label Studio Enterprise](admin_roles). - If you select **Inherit**, the group will inherit the role set above under **Organization Roles to Groups Mapping.** If the group is inheriting the Not Activated role, the users are mapped to the project, but they are not actually assigned to the project until the group is synced (meaning that the user authenticates first). + If you select **Inherit**, the group will inherit the role set above under **Organization Roles to Groups Mapping.** If the group is inheriting the Not Activated role, the users are mapped to the project, but they are not actually assigned to the project until the group is synced (meaning that the user authenticates first). -### Assign a group to the application +#### Step 8: Assign a group to the application 1. Using Okta, navigate to the **application** page and open the **Assignments** tab. -2. Select **Assign → Assign** to Groups and choose the group. +2. Select **Assign > Assign** to Groups and choose the group. 3. Set attribute **Active to true**. After saving the group assignment, the update will be queued and sent to Label Studio. @@ -129,16 +290,16 @@ After saving the group assignment, the update will be queued and sent to Label S !!! note Alternatively, you can push the changes immediately to Label Studio. -### Sync groups to the application +#### Step 9: Sync groups to the application 1. Using Okta, navigate to the **application** page and open the **Push Groups** tab. 2. Click **Push Groups** and select **Find groups by name**. 3. Find the group you would like to sync to Label Studio. -4. 4. Choose either **Create Group** or **Link Group**, if you already have a workplace with the same name as specified on the **SCIM** >> **Settings** page. +4. Choose either **Create Group** or **Link Group**, if you already have a workplace with the same name as specified on the **SCIM** >> **Settings** page. -### Unassigning the application for groups +#### Unassigning the application for groups -To unassign a group from the application, follow the steps for [Unassigning the application for users](#Unassigning-the-application-for-users). +To unassign a group from the application: 1. On the **application** page, navigate to the **Assignments** tab. 2. Select **Group** in the left menu. @@ -149,21 +310,23 @@ To unassign a group from the application, follow the steps for [Unassigning the Check this video tutorial to remove a user and group. -## Set up SCIM with Microsoft Entra ID (Azure AD) +{% enddetails %} + +{% details Microsoft Entra ID (formerly Azure AD) %} Label Studio Enterprise supports SCIM provisioning with Microsoft Entra ID (formerly Azure AD). You can use the same Enterprise Application created for SAML SSO, or create a separate one for SCIM provisioning. Using the same application is simpler when you want both SSO and provisioning. -### Step 1: Create or reuse the Enterprise Application +#### Step 1: Create or reuse the Enterprise Application If creating a new application specifically for SCIM: -1. In the Azure Portal, go to **Entra ID → Enterprise Applications → New Application**. -2. Select **Create your own application** → **Integrate any other application not found in the gallery**. +1. In the Azure Portal, go to **Entra ID > Enterprise Applications > New Application**. +2. Select **Create your own application** > **Integrate any other application not found in the gallery**. 3. Name it (e.g. `Label Studio SCIM`) and create it. -### Step 2: Enable provisioning +#### Step 2: Enable provisioning -1. Open your Enterprise Application → **Provisioning** → **Get started**. +1. Open your Enterprise Application and select **Provisioning > Get started**. 2. Set **Provisioning Mode** to **Automatic**. 3. Under **Admin Credentials**: - **Tenant URL**: `https:///scim/v2` (both `/scim/v2` and `/scim/` are accepted) @@ -171,25 +334,25 @@ If creating a new application specifically for SCIM: 4. Click **Test Connection** to verify connectivity. 5. Click **Save**. -### Step 3: Configure user attribute mappings +#### Step 3: Configure user attribute mappings -Go to **Provisioning → Mappings → Provision Microsoft Entra ID Users**. +Go to **Provisioning > Mappings > Provision Microsoft Entra ID Users**. -#### Required mappings +##### Required mappings | Entra ID Attribute | SCIM Target Attribute | Required | Notes | | --- | --- | --- | --- | | `userPrincipalName` | `userName` | **Yes** | Must be a valid email address. Label Studio uses this as the user's email and login identifier. If your UPNs are not email addresses, map `mail` instead. | | `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | `active` | **Yes** | Controls user activation/deactivation. When set to `false`, the user's org role becomes **Deactivated**. | -#### Recommended mappings +##### Recommended mappings | Entra ID Attribute | SCIM Target Attribute | Required | Notes | | --- | --- | --- | --- | | `givenName` | `name.givenName` | No | First name, displayed in the Label Studio UI. | | `surname` | `name.familyName` | No | Last name, displayed in the Label Studio UI. | -#### Optional mappings (no effect) +##### Optional mappings (no effect) These attributes are accepted by the SCIM endpoint but have no functional impact in Label Studio: @@ -199,7 +362,7 @@ These attributes are accepted by the SCIM endpoint but have no functional impact | `displayName` | `displayName` | Read-only in Label Studio; always derived from `first_name + last_name`. | | `preferredLanguage` | `locale` | Ignored; always returns `en-US`. | -#### Mappings to remove +##### Mappings to remove !!! warning "Unsupported attributes cause provisioning errors" Remove any default Entra ID mappings that target attributes not supported by Label Studio's SCIM endpoint. Leaving unsupported mappings in place will result in **HTTP 501 (Not Implemented)** errors during provisioning. Common mappings to remove: @@ -215,28 +378,28 @@ These attributes are accepted by the SCIM endpoint but have no functional impact !!! note Entra ID typically does **not** send the `emails` array in its SCIM payloads. Label Studio derives the email from `userName` when `emails` is absent, as long as `userName` is a valid email address. If your tenant's UPNs are not email addresses (e.g. `jsmith@contoso.local`), map `mail` to `userName` instead. -### Step 4: Configure group provisioning +#### Step 4: Configure group provisioning -Go to **Provisioning → Mappings → Provision Microsoft Entra ID Groups**. +Go to **Provisioning > Mappings > Provision Microsoft Entra ID Groups**. -#### Required group mappings +##### Required group mappings | Entra ID Attribute | SCIM Target Attribute | Required | Notes | | --- | --- | --- | --- | | `displayName` | `displayName` | **Yes** | The group name. This value must **exactly match** (case-sensitive) the group names configured in Label Studio's SCIM settings. | | `members` | `members` | **Yes** | The list of group members. Entra ID sends member additions/removals as PATCH operations. | -#### Assigning groups to the application +##### Assigning groups to the application Only groups that are **assigned to the Enterprise Application** in Entra ID will be provisioned: -1. Go to **Enterprise Application → Users and groups → Add user/group**. +1. Go to **Enterprise Application > Users and groups > Add user/group**. 2. Select the security groups you want to provision. 3. Click **Assign**. The `displayName` of each assigned group is what Label Studio uses to match against its mapping rules. -### Step 5: Configure SCIM group mappings in Label Studio +#### Step 5: Configure SCIM group mappings in Label Studio This is where you tell Label Studio what each Entra ID group **means**---which role, workspace, or project access it grants. @@ -265,132 +428,50 @@ curl -X POST "https:///api/scim/settings" \ }' ``` -Or configure them in the Label Studio UI under **Organization → SCIM Settings**. +Or configure them in the Label Studio UI under **Organization > SCIM Settings**. For detailed information on the mapping format and behavior, see [Group mapping reference](#group-mapping-reference) below. -### Step 6: Start provisioning +#### Step 6: Start provisioning -1. Go to **Provisioning → Overview**. +1. Go to **Provisioning > Overview**. 2. Click **Start provisioning**. 3. Entra ID will perform an initial sync cycle (can take 20--40 minutes for the first cycle). 4. Subsequent incremental syncs run approximately every 40 minutes. You can trigger an on-demand sync from the **Provision on demand** option for individual users. +{% enddetails %} -## Group mapping reference - -Both SAML and SCIM use the same group mapping format and the same underlying mapping logic. The mapping types are configured independently for each protocol (SAML settings and SCIM settings are separate), but the behavior is identical. - -### Organization role mapping (`roles_groups`) - -Maps a group from your IdP to an organization-level role. - -**Format:** `["", ""]` - -**Available roles:** - -| Role Name | Description | -| --- | --- | -| `Administrator` | Full organization admin access | -| `Manager` | Can manage projects and members | -| `Reviewer` | Can review annotations | -| `Annotator` | Can annotate tasks | - -!!! note - `Owner` cannot be assigned via SAML or SCIM---it is explicitly excluded from group mappings. `Not Activated` and `Deactivated` are internal system states managed automatically and should not be used in `roles_groups` mappings. - -**Behavior when a user is in multiple role groups:** The most elevated role wins. For example, if a user is in both an Annotator group and a Manager group, they get the Manager role. - -**Behavior when a user is removed from all role groups:** Their role is set to Deactivated (subject to the `manual_role_management` flag). - -### Workspace mapping (`workspaces_groups`) - -Maps a group from your IdP to a Label Studio workspace. - -**Format:** `["", ""]` - -- Workspaces are **automatically created** when a SCIM group push or SAML login triggers the mapping. However, the `/api/scim/settings` endpoint validates that referenced workspaces already exist---create them first, or use the UI to save settings. -- A user can be mapped to multiple workspaces through multiple group memberships. -- **SCIM:** removal respects the `manual_workspace_management` billing flag---if enabled, users are not automatically removed from workspaces when they leave a group. -- **SAML:** workspace sync behavior is controlled by the `MANUAL_WORKSPACE_MANAGEMENT` environment variable (default: `True`). When `False`, all SAML-mapped workspaces are reset and re-applied on each login. - -### Project role mapping (`projects_groups`) - -Maps a group from your IdP to membership in a specific project, with a project-level role. - -**Format:** `{"project_id": , "group": "", "role": ""}` - -**Available project roles:** - -| Role | Description | -| --- | --- | -| `Inherit` | User gets project access but inherits their organization role (no explicit project role assigned) | -| `Annotator` | Explicit annotator role on the project | -| `Reviewer` | Explicit reviewer role on the project | - -- `project_id` must be an existing project in your organization. -- The most elevated role wins when a user is in multiple groups mapped to the same project. -- Removal respects the `manual_project_member_management` billing flag. -- **When SCIM project group assignments exist for a user, SAML project sync is skipped** for that user to avoid conflicts. - - -## SCIM user lifecycle - -| Event | What happens in Label Studio | -| --- | --- | -| **User provisioned** | Account created with the organization's default role (configured in Organization settings). Role is then updated when group sync runs. | -| **User already exists in another org** | User is added to this organization with the default role. Profile fields (name, etc.) are **not** overwritten---only the org membership is created. | -| **User added to a role group** | Role upgraded to the mapped role (or highest if in multiple groups). | -| **User removed from a role group** | Role falls back to the next-highest mapped role, or Deactivated if no role groups remain (subject to `manual_role_management`). | -| **User deactivated in Entra ID / Okta** | `active` set to `false` → role becomes Deactivated. | -| **User reactivated in Entra ID / Okta** | `active` set to `true` → role restored from SCIM group mappings, or the organization's default role if no mappings exist. | -| **User deleted in Entra ID / Okta** | Soft-deleted in Label Studio (deactivated, not removed). | - - -## SAML and SCIM interaction - -If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions: - -- **Group mappings are configured separately.** SAML settings (`/api/saml/settings`) and SCIM settings (`/api/scim/settings`) each have their own `roles_groups`, `workspaces_groups`, and `projects_groups`. You can configure identical mappings in both, or use different mappings for each protocol. -- **SCIM project mappings take precedence over SAML.** When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts. -- **Deleting SAML settings clears SCIM group assignments.** Using `DELETE /api/saml/settings` wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments. -- **`manual_role_management` is shared.** The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior. -- **SSO login can still change roles even with SCIM.** If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes---potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two. - -For more information on SAML SSO setup, see [Set up SSO authentication for Label Studio](auth_setup.html). - - -## Troubleshooting +## Troubleshooting SCIM -### Provisioning test connection fails +##### Provisioning test connection fails - Verify the SCIM endpoint URL ends with `/scim/v2` (or `/scim/`). - Verify the bearer token belongs to the **organization owner** (SCIM API requires owner-level authentication). Both legacy API tokens and PATs are accepted. - Check that the Label Studio instance is reachable from the internet (or via your network configuration). -### User created but has wrong role +##### User created but has wrong role 1. Verify the user is assigned to the correct group in your IdP. 2. Verify the group is assigned to the Enterprise Application (in Entra ID) or pushed to the application (in Okta). 3. Verify the group `displayName` in your IdP exactly matches (case-sensitive) the name in Label Studio SCIM settings. 4. Ensure a provisioning cycle has completed after the group assignment (or trigger on-demand provisioning). -### Users not appearing in workspaces or projects +##### Users not appearing in workspaces or projects - Group provisioning must be enabled in the attribute mappings. - The group must be **assigned** to the Enterprise Application (just existing in Entra ID is not enough). - SCIM group settings in Label Studio must be configured **before** or **at the same time as** the groups are pushed. If settings are configured after groups were already synced, save the SCIM settings again to trigger re-evaluation. -### Unsupported attribute errors in provisioning logs +##### Unsupported attribute errors in provisioning logs Remove any default IdP attribute mappings that target attributes not in the Label Studio SCIM schema. See the [Mappings to remove](#mappings-to-remove) section above for common attributes to remove. -### Email case mismatches +##### Email case mismatches Label Studio normalizes all emails to lowercase for both SAML and SCIM operations. `Alice@Contoso.com` and `alice@contoso.com` are treated as the same user. No special configuration is needed. -### Group name mismatches +##### Group name mismatches Group name matching in SCIM settings is **case-sensitive**. `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. From 395fa1a069658843d854b48c5b5d72d77cc329a5 Mon Sep 17 00:00:00 2001 From: Caitlin Date: Tue, 19 May 2026 13:36:26 -0500 Subject: [PATCH 5/6] bumping up the idp sections --- docs/source/guide/auth_setup.md | 100 +++++++++--------- docs/source/guide/scim_setup.md | 179 ++++++++++++++++---------------- 2 files changed, 144 insertions(+), 135 deletions(-) diff --git a/docs/source/guide/auth_setup.md b/docs/source/guide/auth_setup.md index ff54e348b7a2..e50bb440a57a 100644 --- a/docs/source/guide/auth_setup.md +++ b/docs/source/guide/auth_setup.md @@ -155,7 +155,59 @@ Click **Save**. Test the configuration by logging in to Label Studio Enterprise `LS-Admins` and `ls-admins` are treated as different groups. Ensure exact casing matches between your IdP group names and Label Studio mapping configurations. -## SAML SSO Settings API +## IdP-specific setup guides + +This section contains IdP-specific setup guides for SAML SSO. + +### Okta + +To set up SAML SSO specifically with Okta: + +{% details Okta video tutorial %} + +{% enddetails %} + +### Entra ID + +To set up SAML SSO specifically with Microsoft Entra ID (formerly Azure AD): + +{% details Microsoft Entra ID %} + +#### Step 1: Create the Enterprise Application in Entra ID + +1. In the Microsoft Entra admin center, go to **Enterprise Apps > New Application**. +2. Select **Create your own application > Integrate any other application not found in the gallery**. +3. Name it (e.g. `Label Studio SSO`) and create it. + +#### Step 2: Configure SAML in Entra ID + +1. Go to **Single sign-on > SAML**. +2. Under **Basic SAML Configuration**: + - **Identifier (Entity ID)**: Paste the ACS URL from Label Studio. + - **Reply URL (ACS URL)**: Paste the same ACS URL. + - **Sign on URL**: Paste the Login URL from Label Studio. +3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#from-your-idp). +4. Under **SAML Signing Certificate**, download the **Federation Metadata XML** file (or copy the **App Federation Metadata URL**). + +#### Step 3: Configure SAML in Label Studio + +1. Go to **Organization > SSO & SAML**. +2. In the **Domain** field, enter the email domain(s) for your organization (comma-separated, e.g. `contoso.com`). This is used for domain-based SSO routing when users enter their email on the login page. +3. Upload the **Federation Metadata XML** file downloaded from Entra ID, or paste the **App Federation Metadata URL** in the metadata URL field. +4. Select `azure` as the IdP provider preset to auto-fill attribute mapping names, or configure them manually. +5. Configure group mappings as needed. +6. Click **Save**. + +#### Step 4: Assign users and test + +1. In Entra ID, go to **Enterprise Application > Users and groups > Add user/group**. +2. Assign users or groups to the application. +3. Test by navigating to the Label Studio Login URL, or by going to `https:///saml/sso-domain` and entering your email---Label Studio will look up the SAML config by domain and redirect to Entra ID. +4. After authenticating with Entra ID, you should be redirected back to Label Studio and logged in. + +{% enddetails %} + +## SAML SSO settings API You can also configure SAML settings programmatically using the API: @@ -286,52 +338,6 @@ For advanced SAML configuration, the following environment variables control pys | `SAML_WANT_ASSERTIONS_OR_RESPONSE_SIGNED` | (pysaml2 default) | Require at least one signed | | `DISABLE_SAML_SSL_VALIDATION` | (not set) | Disable SSL cert validation for metadata fetch | -## IdP-specific setup guides - -This section contains IdP-specific setup guides for SAML SSO. - -{% details Okta video tutorial %} - -{% enddetails %} - -{% details Microsoft Entra ID %} - -To set up SAML SSO specifically with Microsoft Entra ID (formerly Azure AD): - -#### Step 1: Create the Enterprise Application in Entra ID - -1. In the Azure Portal, go to **Entra ID → Enterprise Applications → New Application**. -2. Select **Create your own application** → **Integrate any other application not found in the gallery**. -3. Name it (e.g. `Label Studio SSO`) and create it. - -#### Step 2: Configure SAML in Entra ID - -1. Go to **Single sign-on → SAML**. -2. Under **Basic SAML Configuration**: - - **Identifier (Entity ID)**: Paste the ACS URL from Label Studio. - - **Reply URL (ACS URL)**: Paste the same ACS URL. - - **Sign on URL**: Paste the Login URL from Label Studio. -3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#from-your-idp). -4. Under **SAML Signing Certificate**, download the **Federation Metadata XML** file (or copy the **App Federation Metadata URL**). - -#### Step 3: Configure SAML in Label Studio - -1. Go to **Organization → SSO & SAML**. -2. In the **Domain** field, enter the email domain(s) for your organization (comma-separated, e.g. `contoso.com`). This is used for domain-based SSO routing when users enter their email on the login page. -3. Upload the **Federation Metadata XML** file downloaded from Entra ID, or paste the **App Federation Metadata URL** in the metadata URL field. -4. Select `azure` as the IdP provider preset to auto-fill attribute mapping names, or configure them manually. -5. Configure group mappings as needed. -6. Click **Save**. - -#### Step 4: Assign users and test - -1. In Entra ID, go to **Enterprise Application → Users and groups → Add user/group**. -2. Assign users or groups to the application. -3. Test by navigating to the Label Studio Login URL, or by going to `https:///saml/sso-domain` and entering your email---Label Studio will look up the SAML config by domain and redirect to Entra ID. -4. After authenticating with Entra ID, you should be redirected back to Label Studio and logged in. - -{% enddetails %} - ## Troubleshooting SAML SSO #### SSO login redirects to an error page diff --git a/docs/source/guide/scim_setup.md b/docs/source/guide/scim_setup.md index f14c34606998..7f67abdeaddb 100644 --- a/docs/source/guide/scim_setup.md +++ b/docs/source/guide/scim_setup.md @@ -105,95 +105,11 @@ Trigger an initial sync from your IdP. Depending on the provider, the first sync After provisioning completes, verify in Label Studio that users appear with the expected roles and group memberships. - - - - -## Group mapping reference - -Both SAML and SCIM use the same group mapping format and the same underlying mapping logic. The mapping types are configured independently for each protocol (SAML settings and SCIM settings are separate), but the behavior is identical. - -### Organization role mapping (`roles_groups`) - -Maps a group from your IdP to an organization-level role. - -**Format:** `["", ""]` - -**Available roles:** - -| Role Name | Description | -| --- | --- | -| `Administrator` | Full organization admin access | -| `Manager` | Can manage projects and members | -| `Reviewer` | Can review annotations | -| `Annotator` | Can annotate tasks | - -!!! note - `Owner` cannot be assigned via SAML or SCIM---it is explicitly excluded from group mappings. `Not Activated` and `Deactivated` are internal system states managed automatically and should not be used in `roles_groups` mappings. - -**Behavior when a user is in multiple role groups:** The most elevated role wins. For example, if a user is in both an Annotator group and a Manager group, they get the Manager role. - -**Behavior when a user is removed from all role groups:** Their role is set to Deactivated (subject to the `manual_role_management` flag). - -### Workspace mapping (`workspaces_groups`) - -Maps a group from your IdP to a Label Studio workspace. - -**Format:** `["", ""]` - -- Workspaces are **automatically created** when a SCIM group push or SAML login triggers the mapping. However, the `/api/scim/settings` endpoint validates that referenced workspaces already exist---create them first, or use the UI to save settings. -- A user can be mapped to multiple workspaces through multiple group memberships. -- **SCIM:** removal respects the `manual_workspace_management` billing flag---if enabled, users are not automatically removed from workspaces when they leave a group. -- **SAML:** workspace sync behavior is controlled by the `MANUAL_WORKSPACE_MANAGEMENT` environment variable (default: `True`). When `False`, all SAML-mapped workspaces are reset and re-applied on each login. - -### Project role mapping (`projects_groups`) - -Maps a group from your IdP to membership in a specific project, with a project-level role. - -**Format:** `{"project_id": , "group": "", "role": ""}` - -**Available project roles:** - -| Role | Description | -| --- | --- | -| `Inherit` | User gets project access but inherits their organization role (no explicit project role assigned) | -| `Annotator` | Explicit annotator role on the project | -| `Reviewer` | Explicit reviewer role on the project | - -- `project_id` must be an existing project in your organization. -- The most elevated role wins when a user is in multiple groups mapped to the same project. -- Removal respects the `manual_project_member_management` billing flag. -- **When SCIM project group assignments exist for a user, SAML project sync is skipped** for that user to avoid conflicts. - - -## SCIM user lifecycle - -| Event | What happens in Label Studio | -| --- | --- | -| **User provisioned** | Account created with the organization's default role (configured in Organization settings). Role is then updated when group sync runs. | -| **User already exists in another org** | User is added to this organization with the default role. Profile fields (name, etc.) are **not** overwritten---only the org membership is created. | -| **User added to a role group** | Role upgraded to the mapped role (or highest if in multiple groups). | -| **User removed from a role group** | Role falls back to the next-highest mapped role, or Deactivated if no role groups remain (subject to `manual_role_management`). | -| **User deactivated in Entra ID / Okta** | `active` set to `false` → role becomes Deactivated. | -| **User reactivated in Entra ID / Okta** | `active` set to `true` → role restored from SCIM group mappings, or the organization's default role if no mappings exist. | -| **User deleted in Entra ID / Okta** | Soft-deleted in Label Studio (deactivated, not removed). | - - -## SAML and SCIM interaction - -If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions: - -- **Group mappings are configured separately.** SAML settings (`/api/saml/settings`) and SCIM settings (`/api/scim/settings`) each have their own `roles_groups`, `workspaces_groups`, and `projects_groups`. You can configure identical mappings in both, or use different mappings for each protocol. -- **SCIM project mappings take precedence over SAML.** When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts. -- **Deleting SAML settings clears SCIM group assignments.** Using `DELETE /api/saml/settings` wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments. -- **`manual_role_management` is shared.** The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior. -- **SSO login can still change roles even with SCIM.** If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes---potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two. - -For more information on SAML SSO setup, see [Set up SSO authentication for Label Studio](auth_setup.html). - ## IdP-specific setup guides -This section contains IdP-specific setup guides for SCIM. +### Okta + +To set up SCIM provisioning specifically with Okta: {% details Okta %} @@ -312,7 +228,11 @@ To unassign a group from the application: {% enddetails %} -{% details Microsoft Entra ID (formerly Azure AD) %} +### Entra ID + +To set up SCIM provisioning specifically with Microsoft Entra ID (formerly Azure AD): + +{% details Microsoft Entra ID %} Label Studio Enterprise supports SCIM provisioning with Microsoft Entra ID (formerly Azure AD). You can use the same Enterprise Application created for SAML SSO, or create a separate one for SCIM provisioning. Using the same application is simpler when you want both SSO and provisioning. @@ -443,6 +363,89 @@ You can trigger an on-demand sync from the **Provision on demand** option for in {% enddetails %} +## Group mapping reference + +Both SAML and SCIM use the same group mapping format and the same underlying mapping logic. The mapping types are configured independently for each protocol (SAML settings and SCIM settings are separate), but the behavior is identical. + +### Organization role mapping (`roles_groups`) + +Maps a group from your IdP to an organization-level role. + +**Format:** `["", ""]` + +**Available roles:** + +| Role Name | Description | +| --- | --- | +| `Administrator` | Full organization admin access | +| `Manager` | Can manage projects and members | +| `Reviewer` | Can review annotations | +| `Annotator` | Can annotate tasks | + +!!! note + `Owner` cannot be assigned via SAML or SCIM---it is explicitly excluded from group mappings. `Not Activated` and `Deactivated` are internal system states managed automatically and should not be used in `roles_groups` mappings. + +**Behavior when a user is in multiple role groups:** The most elevated role wins. For example, if a user is in both an Annotator group and a Manager group, they get the Manager role. + +**Behavior when a user is removed from all role groups:** Their role is set to Deactivated (subject to the `manual_role_management` flag). + +### Workspace mapping (`workspaces_groups`) + +Maps a group from your IdP to a Label Studio workspace. + +**Format:** `["", ""]` + +- Workspaces are **automatically created** when a SCIM group push or SAML login triggers the mapping. However, the `/api/scim/settings` endpoint validates that referenced workspaces already exist---create them first, or use the UI to save settings. +- A user can be mapped to multiple workspaces through multiple group memberships. +- **SCIM:** removal respects the `manual_workspace_management` billing flag---if enabled, users are not automatically removed from workspaces when they leave a group. +- **SAML:** workspace sync behavior is controlled by the `MANUAL_WORKSPACE_MANAGEMENT` environment variable (default: `True`). When `False`, all SAML-mapped workspaces are reset and re-applied on each login. + +### Project role mapping (`projects_groups`) + +Maps a group from your IdP to membership in a specific project, with a project-level role. + +**Format:** `{"project_id": , "group": "", "role": ""}` + +**Available project roles:** + +| Role | Description | +| --- | --- | +| `Inherit` | User gets project access but inherits their organization role (no explicit project role assigned) | +| `Annotator` | Explicit annotator role on the project | +| `Reviewer` | Explicit reviewer role on the project | + +- `project_id` must be an existing project in your organization. +- The most elevated role wins when a user is in multiple groups mapped to the same project. +- Removal respects the `manual_project_member_management` billing flag. +- **When SCIM project group assignments exist for a user, SAML project sync is skipped** for that user to avoid conflicts. + + +## SCIM user lifecycle + +| Event | What happens in Label Studio | +| --- | --- | +| **User provisioned** | Account created with the organization's default role (configured in Organization settings). Role is then updated when group sync runs. | +| **User already exists in another org** | User is added to this organization with the default role. Profile fields (name, etc.) are **not** overwritten---only the org membership is created. | +| **User added to a role group** | Role upgraded to the mapped role (or highest if in multiple groups). | +| **User removed from a role group** | Role falls back to the next-highest mapped role, or Deactivated if no role groups remain (subject to `manual_role_management`). | +| **User deactivated in Entra ID / Okta** | `active` set to `false` → role becomes Deactivated. | +| **User reactivated in Entra ID / Okta** | `active` set to `true` → role restored from SCIM group mappings, or the organization's default role if no mappings exist. | +| **User deleted in Entra ID / Okta** | Soft-deleted in Label Studio (deactivated, not removed). | + + +## SAML and SCIM interaction + +If your organization uses both SAML SSO and SCIM provisioning, be aware of the following interactions: + +- **Group mappings are configured separately.** SAML settings (`/api/saml/settings`) and SCIM settings (`/api/scim/settings`) each have their own `roles_groups`, `workspaces_groups`, and `projects_groups`. You can configure identical mappings in both, or use different mappings for each protocol. +- **SCIM project mappings take precedence over SAML.** When SCIM-driven project group assignments exist for a user, SAML skips its project role sync for that user entirely, to avoid conflicts. +- **Deleting SAML settings clears SCIM group assignments.** Using `DELETE /api/saml/settings` wipes all group assignment records and resets SCIM group settings for the organization. If you need to reconfigure SAML, re-save your SCIM settings afterward and wait for the next group sync to rebuild assignments. +- **`manual_role_management` is shared.** The per-org override in SAML settings takes precedence over the billing/environment default for both SAML and SCIM role removal behavior. +- **SSO login can still change roles even with SCIM.** If a user authenticates via SAML and SAML role mappings are configured, the role may be re-evaluated on login based on SAML group attributes---potentially overriding a role set by SCIM. To avoid this, either use the same mappings in both, or configure role mappings in only one of the two. + +For more information on SAML SSO setup, see [Set up SSO authentication for Label Studio](auth_setup.html). + + ## Troubleshooting SCIM ##### Provisioning test connection fails From 7e3cdfef37945e0ffa2a6ce421c2d171a22e0c8a Mon Sep 17 00:00:00 2001 From: Caitlin Date: Tue, 19 May 2026 13:40:51 -0500 Subject: [PATCH 6/6] fixing links --- docs/source/guide/auth_setup.md | 2 +- docs/source/guide/scim_setup.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/guide/auth_setup.md b/docs/source/guide/auth_setup.md index e50bb440a57a..8791fa748d56 100644 --- a/docs/source/guide/auth_setup.md +++ b/docs/source/guide/auth_setup.md @@ -186,7 +186,7 @@ To set up SAML SSO specifically with Microsoft Entra ID (formerly Azure AD): - **Identifier (Entity ID)**: Paste the ACS URL from Label Studio. - **Reply URL (ACS URL)**: Paste the same ACS URL. - **Sign on URL**: Paste the Login URL from Label Studio. -3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#from-your-idp). +3. Under **User Attributes & Claims**, configure the attribute mappings using the Entra ID presets [shown above](#Step-2-Get-metadata-from-your-IdP). 4. Under **SAML Signing Certificate**, download the **Federation Metadata XML** file (or copy the **App Federation Metadata URL**). #### Step 3: Configure SAML in Label Studio diff --git a/docs/source/guide/scim_setup.md b/docs/source/guide/scim_setup.md index 7f67abdeaddb..ad968f0bae74 100644 --- a/docs/source/guide/scim_setup.md +++ b/docs/source/guide/scim_setup.md @@ -240,8 +240,8 @@ Label Studio Enterprise supports SCIM provisioning with Microsoft Entra ID (form If creating a new application specifically for SCIM: -1. In the Azure Portal, go to **Entra ID > Enterprise Applications > New Application**. -2. Select **Create your own application** > **Integrate any other application not found in the gallery**. +1. In the Microsoft Entra admin center, go to **Enterprise Apps > New Application**. +2. Select **Create your own application > Integrate any other application not found in the gallery**. 3. Name it (e.g. `Label Studio SCIM`) and create it. #### Step 2: Enable provisioning