doc/user/group/saml_sso/scim_setup.md
{{< details >}}
{{< /details >}}
You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically:
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 GitLab Self-Managed.
Prerequisites:
To configure GitLab SAML SSO SCIM:
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.
{{< 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 for SCIM:
After saving, 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 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.
Select Save.
Next, provision the users:
externalId and delete it.objectIdexternalId1id is the primary and required field, and externalId is also required.X in the upper-right corner.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
idandexternalIdmay cause errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group.
[!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 |
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.Expression in the Mapping type dropdown list.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 group SCIM API documentation.
The SAML application created during single sign-on set up for Okta must be set up for SCIM.
Prerequisites:
To configure Okta for SCIM:
During the synchronization process, all new users:
{{< history >}}
bso_minimal_access_fallback. Disabled by default.{{< /history >}}
When restricted access is enabled and no subscription seats are available, users provisioned through SCIM are assigned the Minimal Access role.
When this happens, users are successfully created with Minimal Access (response HTTP 201 Created), and the user's roles attribute reflects this assignment. Subsequent role update operations may fail if no seats are available.
For more information, see Provisioning behavior with SAML, SCIM, and LDAP.
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:
The member's email address is not linked to a SAML account]
D -->|Yes| G[Associate SCIM identity to user]
During provisioning:
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:
For role information, see the Group SAML page.
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:
Remove or deactivate a user on the identity provider to remove their access to:
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]
{{< 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 group memberships are restored.