- GitLab configuration
- Identity Provider configuration
- User access and linking setup
- How come I can’t add a user after I removed them?
- How do I diagnose why a user is unable to sign in
- How do I verify user’s SAML NameId matches the SCIM externalId
- Update or fix mismatched SCIM externalId and SAML NameId
- I need to change my SCIM app
- The SCIM app is throwing
"User has already been taken","status":409error message
Introduced in GitLab Premium 11.10.
System for Cross-domain Identity Management (SCIM), is an open standard that enables the automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of that group is synchronized between GitLab and the identity provider.
The following actions are available:
- Create users
- Deactivate users
The following identity providers are supported:
- Group Single Sign-On must be configured.
Once Group Single Sign-On has been configured, we can:
- Navigate to the group and click Administration > SAML SSO.
- Click on the Generate a SCIM token button.
- Save the token and URL so they can be used in the next step.
- Set up automatic provisioning and administrative credentials by following the Azure’s SCIM setup documentation.
During this configuration, note the following:
secret tokenare the ones retrieved in the previous step.
- It is recommended to set a notification email and check the Send an email notification when a failure occurs checkbox.
- For mappings, we only leave
Synchronize Azure Active Directory Users to AppNameenabled.
Synchronize Azure Active Directory Groups to AppNameis usually disabled. However, this does not mean Azure AD users cannot be provisioned in groups. Leaving it enabled does not break the SCIM user provisioning, but causes errors in Azure AD that may be confusing and misleading.
You can then test the connection by clicking on Test Connection. If the connection is successful, be sure to save your configuration before moving on. See below for troubleshooting.
The following table below provides an attribute mapping known to work with GitLab. If
your SAML configuration differs from the recommended SAML settings,
modify the corresponding
customappsso settings accordingly. If a mapping is not listed in the
table, use the Azure defaults. For a list of required attributes, refer to the SCIM API documentation.
|Azure Active Directory Attribute||
For guidance, you can view an example configuration in the troubleshooting reference.
- Below the mapping list click on Show advanced options > Edit attribute list for AppName.
idis the primary and required field, and
externalIdis also required.
usernameshould neither be primary nor required as we don’t support that field on GitLab SCIM yet.
- Save all changes.
In the Provisioning step, set the
On.You can control what is actually synced by selecting the
Scope. For example,
Sync only assigned users and groupsonly syncs the users assigned to the application (
Users and groups), otherwise, it syncs the whole Active Directory.
Once enabled, the synchronization details and any errors appears on the bottom of the Provisioning screen, together with a link to the audit events.
externalIdmay cause a number of errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group.
Make sure that the Okta setup matches our documentation exactly, especially the NameID configuration. Otherwise, the Okta SCIM app may not work properly.
- Sign in to Okta.
If you see an Admin button in the top right, click the button. This will ensure you are in the Admin area.If you’re using the Developer Console, click Developer Console in the top bar and select Classic UI. Otherwise, you may not see the buttons described in the following steps:
- In the Application tab, click Add Application.
- Search for GitLab, find and click on the ‘GitLab’ application.
- On the GitLab application overview page, click Add.
- Under Application Visibility select both checkboxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users.
- Click Done to finish adding the application.
- In the Provisioning tab, click Configure API integration.
- Select Enable API integration.
- For Base URL enter the URL obtained from the GitLab SCIM configuration page
- For API Token enter the SCIM token obtained from the GitLab SCIM configuration page
- Click ‘Test API Credentials’ to verify configuration.
- Click Save to apply the settings.
- After saving the API integration details, new settings tabs appear on the left. Choose To App.
- Click Edit.
- Check the box to Enable for both Create Users and Deactivate Users.
- Click Save.
- Assign users in the Assignments tab. Assigned users are created and managed in your GitLab group.
The Okta GitLab application currently only supports SCIM. Continue using the separate Okta SAML SSO configuration along with the new SCIM application described above.
OneLogin provides a “GitLab (SaaS)” app in their catalog, which includes a SCIM integration. As the app is developed by OneLogin, please reach out to OneLogin if you encounter issues.
During the synchronization process, all of your users get GitLab accounts, welcoming them to their respective groups, with an invitation email. When implementing SCIM provisioning, you may want to warn your security-conscious employees about this email.
The following diagram is a general outline on what happens when you add users to your SCIM app:
- Both primary and secondary emails are considered when checking whether a GitLab user account exists.
- Duplicate usernames are also handled, by adding suffix
1upon user creation. For example, due to already existing
As long as Group SAML has been configured, existing GitLab.com users can link to their accounts in one of the following ways:
- By updating their primary email address in their GitLab.com user account to match their identity provider’s user profile email address.
By following these steps:
- Sign in to GitLab.com if needed.
- Click on the GitLab app in the identity provider’s dashboard or visit the GitLab single sign-on URL.
- Click on the Authorize button.
We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users.
New users and existing users on subsequent visits can access the group through the identify provider’s dashboard or by visiting links directly.
In GitLab 14.0 and later, GitLab users created with a SCIM identity display with an Enterprise badge in the Members view.
For role information, please see the Group SAML page
To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user on the identity provider. SCIM providers generally update GitLab with the changes on demand, which is minutes at most. The user’s membership is revoked and they immediately lose access.
This section contains possible solutions for problems you might encounter.
As outlined in the Blocking access section, when you remove a user, they are removed from the group. However, their account is not deleted.
When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists.
Solution: Have a user sign in directly to GitLab, then manually link their account.
Ensure that the user has been added to the SCIM app.
If you receive “User is not linked to a SAML account”, then most likely the user already exists in GitLab. Have the user follow the User access and linking setup instructions.
The Identity (
extern_uid) value stored by GitLab is updated by SCIM whenever
externalId changes. Users cannot sign in unless the GitLab Identity (
extern_uid) value matches the
NameId sent by SAML.
This value is also used by SCIM to match users on the
id, and is updated by SCIM whenever the
externalId values change.
It is important that this SCIM
id and SCIM
externalId are configured to the same value as the SAML
NameId. SAML responses can be traced using debugging tools, and any errors can be checked against our SAML troubleshooting docs.
Group owners can see the list of users and the
externalId stored for each user in the group SAML SSO Settings page.
A possible alternative is to use the SCIM API to manually retrieve the
externalId we have stored for users, also called the
To see how the
external_uid compares to the value returned as the SAML NameId, you can have the user use a SAML Tracer.
Whether the value was changed or you need to map to a different field, ensure
NameId all map to the same field.
If the GitLab
externalId doesn’t match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change.
Be cautious if you revise the fields used by your SCIM identity provider, typically
We use these IDs to look up users. If the identity provider does not know the current values for these fields,
that provider may create duplicate users.
externalId for a user is not correct, and also doesn’t match the SAML NameID,
you can address the problem in the following ways:
- You can have users unlink and relink themselves, based on the “SAML authentication failed: User has already been taken” section.
- You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on.
- It may be possible to use the SCIM API to manually correct the
externalIdstored for users to match the SAML
NameId. To look up a user, you need to know the desired value that matches the
NameIdas well as the current
It is important not to update these to incorrect values, since this causes users to be unable to sign in. It is also important not to assign a value to the wrong user, as this causes users to get signed into the wrong account.
Individual users can follow the instructions in the “SAML authentication failed: User has already been taken” section.
Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to link existing users.
Changing the SAML or SCIM configuration or provider can cause the following problems:
|SAML and SCIM identity mismatch.||First verify that the user’s SAML NameId matches the SCIM externalId and then update or fix the mismatched SCIM externalId and SAML NameId.|
|SCIM identity mismatch between GitLab and the Identify Provider SCIM app.||You can confirm whether you’re hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using SCIM API which shows up in the |
Review the following:
- Ensure that the SCIM value for
idmatches the SAML value for
- Ensure that the SCIM value for
externalIdmatches the SAML value for
Review the following SCIM parameters for sensible values:
emails[type eq "work"].value
When testing the connection, you may encounter an error: You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account. If
Tenant URL and
secret token are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as
.). Removing such characters from the group path typically resolves the error.
When checking the Audit Events for the Provisioning, you can sometimes see the
Namespace can't be blank, Name can't be blank, and User can't be blank.
This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped.
As a workaround, try an alternate mapping:
- Follow the Azure mapping instructions from above.
- Delete the
name.formattedtarget attribute entry.
- Change the
displayNamesource attribute to have