Set up SCIM2 for Label Studio

System for Cross-domain Identity Management (SCIM) is a popular protocol to manage access for services and applications across an organization.

Using a SCIM provider, you can manage access to Label Studio Enterprise workspaces, and grant roles to individual users and groups.

Requirements

Label Studio Enterprise uses the SCIM Version 2.0 standard.

Label Studio Enterprise follows SCIM RFC 5741 and can be integrated with any access management services that support the standard.

For more information on SCIM workflows, see How SCIM works with Label Studio Enterprise.

Prerequisites

• SCIM interacts with your SSO integration. Before you begin, you must have SSO already configured. If you do not have SSO set up yet, then follow Set up SSO.

!!! note Okta or similar SSO providers have SCIM integration based on SSO.

• You will need to provide a Legacy token, and it must be associated with the Owner role of your organization.

Set up SCIM integration with Okta

!!! attention "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.

To manage access to Label Studio Enterprise, add the application to your SCIM provider (Okta).

Okta uses a Bearer (request header should be Authorization: Bearer <token>) 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)

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.
4. Make sure Label Studio Enterprise appears in the list of active applications.

Enable SCIM provisioning

1. Navigate to Applications > Applications in Okta.
2. Select Label Studio Enterprise.
3. Select the General tab and select Enable SCIM provisioning.
4. Select the Provisioning tab.
5. Select Integration in the left menu.
6. Click Edit in the right corner.

Complete the following fields:

• Import New Users and Profile Updates
• Push New Users
• Push Profile Updates
• Push Groups | | HTTP Header → Authorization: Bearer <token> | Enter the Legacy token 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

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:
   • Create Users
   • Update User Attributes
   • Deactivate Users

Assign the application to a single user

You can assign the application on both the user page and application page.

1. On the application page navigate to Assignments tab.
2. Click Assign and select Assign to People.
3. Select the people you would like to be added to Label Studio Enterprise.
4. Click Done.

After you click Done, Okta will send the requests to create users accordingly in the Label Studio Enterprise.

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

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

1. In Label Studio, click the menu in the upper left and select Organization.

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.

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

     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.

     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.

     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

1. Using Okta, navigate to the application page and open the Assignments tab.
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.

!!! note Alternatively, you can push the changes immediately to Label Studio.

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.

Unassigning the application for groups

To unassign a group from the application, follow the steps for Unassigning the application for users.

1. On the application page, navigate to the Assignments tab.
2. Select Group in the left menu.
3. Click the delete cross against the group you would like to unassign.
4. Confirm the unassignment.

<i>Check this video tutorial to remove a user and group.</i>

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.

Supported user attributes

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.

!!! 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:

* `displayName`
* `preferredLanguage`
* `name.formatted`
* `externalId`

Configure Microsoft Entra ID provisioning

1. In the Microsoft Entra admin center, 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://<LABEL_STUDIO_BASE_URL>/scim/v2/.

5. Set the Secret Token to the Legacy token 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 above).