How to configure SCIM with Okta

This guide explains how to set up SCIM user and group provisioning between Okta and your Hugging Face organization using SCIM.

This feature is part of the Enterprise and Enterprise Plus plans.

Step 1: Get SCIM configuration from Hugging Face

1. Navigate to your organization’s settings page on Hugging Face.
2. Go to the SSO tab, then click on the SCIM sub-tab.
3. Copy the SCIM Tenant URL. You will need this for the Okta configuration.
4. Click Generate an access token. A new SCIM token will be generated. Copy this token immediately and store it securely, as you will not be able to see it again.

Step 2: Enter Admin Credentials

1. In Okta, go to Applications and select your Hugging Face app.
2. Go to the General tab and click Edit on App Settings
3. For the Provisioning option select SCIM, click Save
4. Go to the Provisioning tab and click Edit.
5. Enter the SCIM Tenant URL as the SCIM connector base URL.
6. Enter userName for Unique identifier field for users.
7. Select all necessary actions for Supported provisioning actions.
8. Select HTTP Header for Authentication Mode.
9. Enter the Access Token you generated as the Authorization Bearer Token.
10. Click Test Connector Configuration to verify the connection.
11. Save your changes.

Step 3: Configure Provisioning

1. In the Provisioning tab, click To App from the side nav.
2. Click Edit and check to Enable all the features you need, i.e. Create, Update, Delete Users.
3. Click Save at the bottom.

Step 4: Configure Attribute Mappings

1. While still in the Provisioning tab scroll down to Attribute Mappings section
2. The default attribute mappings often require adjustments for robust provisioning. We recommend using the following configuration. You can delete attributes that are not here:

Step 5: Assign Users or Groups

1. Visit the Assignments tab, click Assign
2. Click Assign to People or Assign to Groups
3. After finding the User or Group that needs to be assigned, click Assign next to their name
4. In the mapping modal the Username needs to be edited to comply with the following rules.

• Only regular characters and `-` are accepted in the Username.
• `--` (double dash) is forbidden.
• `-` cannot start or end the name.
• Digit-only names are not accepted.
• Minimum length is 2 and maximum length is 42.
• Username has to be unique within your org.

5. Scroll down and click Save and Go Back
6. Click Done
7. Confirm that users or groups are created, updated, or deactivated in your Hugging Face organization as expected.

Step 6: Push Okta Groups to Hugging Face via SCIM

Before you can link groups to Hugging Face Resource Groups, you need to push your Okta groups to Hugging Face using the Push Groups tab. This is separate from assigning users to the app in Step 5.

Okta does not support using the same group for app assignment (Step 5) and Group Push. Use a dedicated group for pushing — keep your push groups separate from your assignment groups.

1. In the Okta Admin Console, go to Applications and select your Hugging Face app.
2. Click the Push Groups tab.
3. Click + Push Groups and select Find groups by name.
4. Search for the Okta group you want to push and select it from the results.
5. Choose how to handle the group in Hugging Face:
   • Create Group: Creates a new SCIM group in your Hugging Face organization.
   • Link Group: Links to an existing group already in your Hugging Face organization.
6. Click Save. To push additional groups, click Save & Add Another and repeat.

Once pushed, the group will appear under SCIM Groups in your Hugging Face organization settings (SSO → SCIM tab). Any membership changes you make to the group in Okta will automatically sync to Hugging Face.

Step 7: Link SCIM Groups to Hugging Face Resource Groups

Once your groups are provisioned from Okta, you can link them to Hugging Face Resource Groups to manage permissions at scale. This allows all members of a SCIM group to automatically receive specific roles (like read or write) for a collection of resources.

Before linking, make sure the Resource Group you want to link is empty (has no existing members) and does not have auto-join enabled. Both conditions are required — linking will fail otherwise.

1. In your Hugging Face organization settings, navigate to the SSO -> SCIM tab. You will see a list of your provisioned groups under SCIM Groups.
2. Locate the group you wish to configure and click Link resource groups in its row.
3. A dialog will appear. Click Link a Resource Group.
4. From the dropdown menus, select the Resource Group you want to link and the Role Assignment you want to grant to the members of the SCIM group.
5. Click Link to SCIM group and save the mapping.

Once linked, the Resource Group becomes SCIM-managed: any members already in the SCIM group are immediately added to the Resource Group (backfill), and all future membership changes in Okta are automatically reflected. Manual membership edits on the Resource Group via the Hub UI or API will be blocked.

Update on GitHub