doc/administration/settings/scim_setup.md
{{< details >}}
{{< /details >}}
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:
GitLab supports SCIM with several identity providers. Other identity providers might still work with GitLab, but they have not been tested and are not supported. For help with an unsupported provider, contact the provider directly. GitLab Support can help review 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:
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.
Group synchronization is optional. If you want to configure it, under the Mappings section, first provision the groups:
Select Provision Microsoft Entra ID Groups.
On the Attribute Mapping page, turn on the Enabled toggle.
Under Target Object Actions, select the Create, Update, and Delete checkboxes.
Under Attribute Mappings, edit the first attribute to have a:
displayName.displayName.1.Select Save.
Next, provision the users:
externalId and delete it.objectId.externalId.1.Alwaysid 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 GitLab by marking the identity with active: false, while the SCIM identity remains linked to the GitLab user account.
Deprovisioning a user through SCIM does not remove the linked SAML identity.
To update the user SCIM identity, use the internal GitLab SCIM API.
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. Because the linked SAML identity is retained during deprovisioning, users can immediately sign in using SSO.
{{< 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.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.