Configure SCIM for self-managed GitLab instances

DETAILS: Tier: Premium, Ultimate Offering: Self-managed

• Introduced in GitLab 15.8.

You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically:

• Create users.
• Block users.
• Re-add users (reactivate SCIM identity).

The internal GitLab SCIM API implements part of the RFC7644 protocol.

If you are a GitLab.com user, see configuring SCIM for GitLab.com groups.

Configure GitLab

Prerequisites:

• Configure SAML single sign-on.

To configure GitLab SCIM:

1. On the left sidebar, at the bottom, select Admin area.
2. Select Settings > General.
3. Expand the SCIM Token section and select Generate a SCIM token.
4. For configuration of your identity provider, save the:
   • Token from the Your SCIM token field.
   • URL from the SCIM API endpoint URL field.

Configure an identity provider

You can configure the following as an identity provider:

• Okta.

NOTE: Other identity providers can work with GitLab but they have not been tested and are not supported. You should contact the provider for support. GitLab support can assist by reviewing related log entries.

Configure Okta

The SAML application created during single sign-on set up for Okta must be set up for SCIM.

Prerequisites:

• You must use the Okta Lifecycle Management product. This product tier is required to use SCIM on Okta.
• GitLab is configured for SCIM.
• The SAML application for Okta set up as described in the Okta setup notes.
• Your Okta SAML setup matches the configuration steps, especially the NameID configuration.

To configure Okta for SCIM:

1. Sign in to Okta.
2. In the upper-right corner, select Admin. The button is not visible from the Admin area.
3. In the Application tab, select Browse App Catalog.
4. Find and select the GitLab application.
5. On the GitLab application overview page, select Add Integration.
6. Under Application Visibility, select both checkboxes. The GitLab application does not support SAML authentication so the icon should not be shown to users.
7. Select Done to finish adding the application.
8. In the Provisioning tab, select Configure API integration.
9. Select Enable API integration.
   • For Base URL, paste the URL you copied from SCIM API endpoint URL on the GitLab SCIM configuration page.
   • For API Token, paste the SCIM token you copied from Your SCIM token on the GitLab SCIM configuration page.
10. To verify the configuration, select Test API Credentials.
11. Select Save.
12. After saving the API integration details, new settings tabs appear on the left. Select To App.
13. Select Edit.
14. Select the Enable checkbox for both Create Users and Deactivate Users.
15. Select Save.
16. Assign users in the Assignments tab. Assigned users are created and managed in your GitLab group.

Remove access

Removing or deactivating a user on the identity provider blocks the user on the GitLab instance, while the SCIM identity remains linked to the GitLab user.

To update the user SCIM identity, use the internal GitLab SCIM API.

Reactivate access

• Introduced in GitLab 16.0 with a flag named skip_saml_identity_destroy_during_scim_deprovision. Disabled by default.
• Generally available in GitLab 16.4. Feature flag skip_saml_identity_destroy_during_scim_deprovision removed.

After a user is removed or deactivated through SCIM, you can reactivate that user by adding them to the SCIM identity provider.

After the identity provider performs a sync based on its configured schedule, the user's SCIM identity is reactivated and their GitLab instance access is restored.

Troubleshooting

See our troubleshooting SCIM guide.