Configure SCIM for GitLab.com groups (PREMIUM SAAS)

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

• Create users.
• Remove users (deactivate 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.

Configure GitLab

Prerequisites:

• Group single sign-on must be configured.

To configure GitLab SAML SSO SCIM:

1. On the left sidebar, at the top, select Search GitLab ({search}) to 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:

• Azure Active Directory.
• Okta.

NOTE: Other providers can work with GitLab but they have not been tested and are not supported.

Configure Azure Active Directory

Prerequisites:

• GitLab is configured.

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.

To configure Azure Active Directory 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, Settings and Mappings sections appear.

1. Under Settings, if required, set a notification email and select the Send an email notification when a failure occurs checkbox.
2. Under Mappings, we recommend you:
   1. Keep Provision Azure Active Directory Users enabled and select the Provision Azure Active Directory Users link to configure attribute mappings.
   2. Below the mapping list select the Show advanced options checkbox.
   3. Select the Edit attribute list for customappsso link.
   4. Ensure the id is the primary and required field, and externalId is also required.
   5. Select Save.
3. Return to the Provisioning tab, saving unsaved changes if necessary.
4. Select Edit attribute mappings.
5. Under Mappings:
   1. Select Provision Azure Active Directory Groups.
   2. On the Attribute Mapping page, turn off the Enabled toggle. Leaving it turned on doesn't break the SCIM user provisioning, but it causes errors in Azure Active Directory that may be confusing and misleading.
   3. Select Save.
6. Return to the Provisioning tab, saving unsaved changes if necessary.
7. Select Edit attribute mappings.
8. Turn on the Provisioning Status toggle. Synchronization details and any errors appears on the bottom of the Provisioning screen, together with a link to the audit events.

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

Configure attribute mappings

While configuring Azure Active Directory for SCIM, you configure attribute mappings. For an example, see example configuration.

The following table provides attribute mappings known to work with GitLab.

Each attribute mapping has:

• An Azure Active Directory attribute (source attribute).
• A customappsso attribute (target attribute).
• A matching precedence.

For each attribute:

1. Select the attribute to edit it.
2. Select the required settings.
3. Select Ok.

If your SAML configuration differs from the recommended SAML settings, select the mapping attributes and modify them accordingly. In particular, the objectId source attribute must map to the externalId target attribute.

If a mapping is not listed in the table, use the Azure Active Directory 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:

• You must use the Okta Lifecycle Management product. This product tier is required to use SCIM on Okta.
• GitLab is configured.
• SAML application for Okta set up as described in the Okta setup notes.
• Your Okta SAML setup matches the configuration steps exactly, 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. 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

Introduced in GitLab 14.0, GitLab users created by SAML SSO or SCIM provisioning are displayed with an Enterprise badge in the Members view.

During the synchronization process, all new users:

• Receive GitLab accounts.
• Are welcomed to their groups with an invitation email. You may want to warn your employees to expect this email.

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

graph TD
  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 more information on how GitLab generates passwords for users created through SCIM for GitLab groups, see generated passwords for users created through integrated authentication.

Link SCIM and SAML identities

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.

graph TD
  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]