Configure SCIM for GitLab Self-Managed

DETAILS: Tier: Premium, Ultimate Offering: GitLab 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.
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.
• Microsoft Entra ID (formerly Azure Active Directory)

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.

Configure Microsoft Entra ID (formerly Azure Active Directory)

• Changed to Microsoft Entra ID terminology in GitLab 16.10.

Prerequisites:

• GitLab is configured for SCIM.
• The SAML application for Microsoft Entra ID is set up.

The SAML application created during single sign-on set up for Azure Active Directory must be set up for SCIM. For an example, see example configuration.

NOTE: You must configure SCIM provisioning exactly as detailed in the following instructions. If misconfigured, you will encounter issues with user provisioning and sign in, which require a lot of effort to resolve. If you have any trouble or questions with any step, contact GitLab support.

To configure Microsoft Entra ID, you configure:

• Microsoft Entra ID for SCIM.
• Settings.
• Mappings, including attribute mappings.

Configure Microsoft Entra ID for SCIM

1. In your app, go to the Provisioning tab and select Get started.

2. Set the Provisioning Mode to Automatic.

3. Complete the Admin Credentials using the value of:

   • SCIM API endpoint URL in GitLab for the Tenant URL field.
   • Your SCIM token in GitLab for the Secret Token field.

4. Select Test Connection.

   If the test is successful, save your configuration.

   If the test is unsuccessful, see troubleshooting to try to resolve this.

5. Select Save.

After saving, the Mappings and Settings sections appear.

Configure mappings

Under the Mappings section, first provision the groups:

1. Select Provision Microsoft Entra ID Groups.

2. On the Attribute Mapping page, turn off the Enabled toggle.

   SCIM group provisioning is not supported in GitLab. Leaving group provisioning enabled does not break the SCIM user provisioning, but it causes errors in the Entra ID SCIM provisioning log that might be confusing and misleading.

   NOTE: Even when Provision Microsoft Entra ID Groups is disabled, the mappings section may display "Enabled: Yes". This behavior is a display bug that you can safely ignore.

3. Select Save.

Next, provision the users:

1. Select Provision Microsoft Entra ID Users.
2. Ensure that the Enabled toggle is set to Yes.
3. Ensure that all Target Object Actions are enabled.
4. Under Attribute Mappings, configure mappings to match the configured attribute mappings:
   1. Optional. In the customappsso Attribute column, find externalId and delete it.
   2. Edit the first attribute to have a:
      • source attribute of objectId.
      • target attribute of externalId.
      • matching precedence of 1.
   3. Update the existing customappsso attributes to match the configured attribute mappings.
   4. Delete any additional attributes that are not present in the attribute mappings table. They do not cause problems if they are not deleted, but GitLab does not consume the attributes.
5. Under the mapping list, select the Show advanced options checkbox.
6. Select the Edit attribute list for customappsso link.
7. Ensure the id is the primary and required field, and externalId is also required.
8. Select Save, which returns you to the Attribute Mapping configuration page.
9. Close the Attribute Mapping configuration page by clicking the X in the top right corner.

Configure attribute mappings

NOTE: While Microsoft transitions from Azure Active Directory to Entra ID naming schemes, you might notice inconsistencies in your user interface. If you're having trouble, you can view an older version of this document or contact GitLab Support.

While configuring Entra ID for SCIM, you configure attribute mappings. For an example, see example configuration.

The following table provides attribute mappings that are required for GitLab.

Source attribute	Target attribute	Matching precedence
objectId	externalId	1
userPrincipalName OR mail 1	emails[type eq "work"].value
mailNickname	userName
displayName OR Join(" ", [givenName], [surname]) 2	name.formatted
Switch([IsSoftDeleted], , "False", "True", "True", "False") 3	active

Footnotes:

1. Use mail as a source attribute when the userPrincipalName is not an email address or is not deliverable.
2. Use the Join expression if your displayName does not match the format of Firstname Lastname.
3. This is an expression mapping type, not a direct mapping. Select Expression in the Mapping type dropdown list.

Each attribute mapping has:

• A customappsso Attribute, which corresponds to target attribute.
• A Microsoft Entra ID Attribute, which corresponds to source attribute.
• A matching precedence.

For each attribute:

1. Edit the existing attribute or add a new attribute.
2. Select the required source and target attribute mappings from the dropdown lists.
3. Select Ok.
4. Select Save.

If your SAML configuration differs from the recommended SAML settings, select the mapping attributes and modify them accordingly. The source attribute that you map to the externalId target attribute must match the attribute used for the SAML NameID.

If a mapping is not listed in the table, use the Microsoft Entra ID defaults. For a list of required attributes, refer to the internal instance SCIM API documentation.

Configure settings

Under the Settings section:

1. Optional. If desired, select the Send an email notification when a failure occurs checkbox.
2. Optional. If desired, select the Prevent accidental deletion checkbox.
3. If necessary, select Save to ensure all changes have been saved.

After you have configured the mappings and the settings, return to the app overview page and select Start provisioning to start automatic SCIM provisioning of users in GitLab.

WARNING: Once synchronized, changing the field mapped to id and externalId might cause errors. These include provisioning errors, duplicate users, and might prevent existing users from accessing the 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.