Configure SCIM for GitLab.com groups

Tier: Premium, Ultimate Offering: GitLab.com

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

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

GitLab SAML SSO SCIM doesn’t support updating users.

When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider.

The internal GitLab group SCIM API implements part of the RFC7644 protocol. Identity providers can use the internal GitLab group SCIM API to develop a SCIM app.

To set up SCIM on GitLab self-managed, see Configure SCIM for self-managed GitLab instances.

Configure GitLab

Prerequisites:

To configure GitLab SAML SSO SCIM:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Settings > SAML SSO.
  3. 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 one of the following as an identity provider:

note
Other 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 Microsoft Entra ID (formerly Azure Active Directory)

History
  • Changed to Microsoft Entra ID terminology in GitLab 16.10.

Prerequisites:

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 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 before continuing, or see the troubleshooting information.
  5. Select Save.

After saving, 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 may 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 following 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 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.

caution
Once synchronized, changing the field mapped to id and externalId may cause errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group.

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  
  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 group SCIM API documentation.

Configure Okta

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

Prerequisites:

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. Search for GitLab, find and select the GitLab application.
  5. On the GitLab application overview page, select Add.
  6. Under Application Visibility select both checkboxes. Currently 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.

User access

During the synchronization process, all new users:

The following diagram describes what happens when you add users to your SCIM app:

%%{init: { "fontFamily": "GitLab Sans" }}%% graph TD accTitle: Adding users to your SCIM application accDescr: How GitLab determines whether or not to associate a SCIM identity with a user. A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exist?) B -->|No| C[GitLab creates user with SCIM identity] B -->|Yes| D(GitLab: Is the user part of the group?) D -->|No| E(GitLab: Is SSO enforcement enabled?) E -->|No| G E -->|Yes| F[GitLab sends message back:\nThe member's email address is not linked to a SAML account] D -->|Yes| G[Associate SCIM identity to user]

During provisioning:

  • Both primary and secondary emails are considered when checking whether a GitLab user account exists.
  • Duplicate usernames are handled by adding suffix 1 when creating the user. For example, if test_user already exists, test_user1 is used. If test_user1 already exists, GitLab increments the suffix to find an unused username. If no unused username is found after 4 tries, a random string is attached to the username.

On subsequent visits, new and existing users can access groups either:

  • Through the identity provider’s dashboard.
  • By visiting links directly.

For role information, see the Group SAML page.

Passwords for users created through SCIM for GitLab groups

GitLab requires passwords for all user accounts. For users created using SCIM provisioning, GitLab automatically generates a random password, and users do not need to set one during their first sign-in. For more information on how GitLab generates passwords for users created through SCIM for GitLab groups, see generated passwords for users created through integrated authentication.

If group SAML is configured and you have an existing GitLab.com account, users can link their SCIM and SAML identities. Users should do this before synchronization is turned on because there can be provisioning errors for existing users when synchronization is active.

To link your SCIM and SAML identities:

  1. Update the primary email address in your GitLab.com user account to match the user profile email address in your identity provider.
  2. Link your SAML identity.

Remove access

Remove or deactivate a user on the identity provider to remove their access to:

  • The top-level group.
  • All subgroups and projects.

After the identity provider performs a sync based on its configured schedule, the user’s membership is revoked and they lose access.

When you enable SCIM, this does not automatically remove existing users who do not have a SAML identity.

note
Deprovisioning does not delete the GitLab user account.
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TD accTitle: Deprovisioning users accDescr: How removing users from your SCIM app removes them from GitLab groups. A[Remove User from SCIM app] -->|IdP sends request to GitLab| B(GitLab: Is the user part of the group?) B -->|No| C[Nothing to do] B -->|Yes| D[GitLab removes user from GitLab group]

Reactivate access

History
  • 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 group memberships are restored.