doc/administration/settings/scim_setup.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically:
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.
Prerequisites:
To configure GitLab SCIM:
You can configure the following as an identity provider:
[!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.
The SAML application created during single sign-on set up for Okta must be set up for SCIM.
Prerequisites:
To configure Okta for SCIM:
{{< history >}}
{{< /history >}}
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, you configure:
In your app, go to the Provisioning tab and select Get started.
Set the Provisioning Mode to Automatic.
Complete the Admin Credentials using the value of:
Select Test Connection.
If the test is successful, save your configuration.
If the test is unsuccessful, see troubleshooting to try to resolve this.
Select Save.
After saving, the Mappings and Settings sections appear.
Under the Mappings section, first provision the groups:
Select Provision Microsoft Entra ID Groups.
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 might display Enabled: Yes. This behavior is a display bug that you can safely ignore.
Select Save.
Next, provision the users:
externalId and delete it.objectId.externalId.1.id is the primary and required field, and externalId is also required.X in the upper-right corner.[!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 <sup>1</sup> | emails[type eq "work"].value | |
mailNickname | userName | |
displayName OR Join(" ", [givenName], [surname]) <sup>2</sup> | name.formatted | |
Switch([IsSoftDeleted], , "False", "True", "True", "False") <sup>3</sup> | active |
Footnotes:
mail as a source attribute when the userPrincipalName is not an email address or is not deliverable.Join expression if your displayName does not match the format of Firstname Lastname.Each attribute mapping has:
For each attribute:
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.
Under the Settings section:
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
idandexternalIdmight cause errors. These include provisioning errors, duplicate users, and might prevent existing users from accessing the GitLab group.
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.
{{< history >}}
skip_saml_identity_destroy_during_scim_deprovision. Disabled by default.skip_saml_identity_destroy_during_scim_deprovision removed.{{< /history >}}
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.
{{< history >}}
self_managed_scim_group_sync. Disabled by default.self_managed_scim_group_sync removed.{{< /history >}}
In addition to user provisioning, you can use SCIM to synchronize group memberships between your identity provider and GitLab. With this method you can automatically add and remove users from GitLab groups based on their group memberships in your identity provider.
Prerequisites:
SCIM group synchronization works with SAML group links to manage group memberships. When your identity provider sends group membership changes through the SCIM API, GitLab updates user memberships in all GitLab groups that have SAML group links associated with that SCIM group.
SCIM is a one-directional protocol: changes flow from your identity provider to GitLab. If you make changes to SAML group links in GitLab (such as adding or removing them), your identity provider has no way to detect these changes through SCIM.
When your identity provider first provisions a SCIM group (through POST /Groups), GitLab associates the SCIM group ID with all existing SAML group links that have a matching group name.
However, if you add new SAML group links with the same group name after the initial provisioning,
the new group links are not automatically associated with the SCIM group ID.
This means SCIM membership updates from your identity provider do not affect users in the newly added group links.
Support for improvements is proposed in issue 582729.
[!note] To ensure all group links are associated with the SCIM group from the start, you should configure all SAML group links before setting up SCIM group provisioning in your identity provider.
If you need to add group links after the initial provisioning, you can re-provision the SCIM group in your identity provider by deleting the SCIM group provisioning (not the IdP group itself), then recreating it. This action re-associates all current SAML group links with the SCIM group. For more information, refer to your identity provider's documentation for managing SCIM group provisioning.
If you delete a SAML group link in GitLab, members of that group through that link remain in the group. However, SCIM no longer manages their membership in that group because the group link has been removed. If needed, you can manually remove members from the group.
For detailed instructions on configuring group synchronization in your identity provider, refer to the provider's documentation. Examples below:
displayName source attribute is used to find SAML group links with user-friendly names.
- However, if your SAML group links use an object ID for the name,
you must update the source attribute to objectId.[!warning] When multiple SAML group links map to the same GitLab group, users are assigned the highest role across all mapping group links. Users removed from an IdP group stay in a GitLab group if they belong to another SAML group linked to it.
The standard GitLab SCIM application in the Okta application catalog does not support group synchronization. Alternatively, you can create a custom SCIM integration for group synchronization with Okta. For more information, see issue 582729.
See our troubleshooting SCIM guide.