- User cannot be added after they are removed
- User cannot sign in
- Unsure if user’s SAML
NameIdmatches the SCIM
- Mismatched SCIM
- Change SCIM app
- SCIM app returns
"User has already been taken","status":409error
- Search Rails logs for SCIM requests
- Azure Active Directory
This section contains possible solutions for problems you might encounter.
User cannot be added after they are removed
When you remove a user, they are removed from the group but their account is not deleted (see remove access).
When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists.
To solve this problem:
- Have the user sign in directly to GitLab.
- Manually link their account.
User cannot sign in
The following are possible solutions for problems where users cannot sign in:
- Ensure that the user was added to the SCIM app.
- If you receive the
User is not linked to a SAML accounterror, the user probably already exists in GitLab. Have the user follow the Link SCIM and SAML identities instructions.
- The Identity (
extern_uid) value stored by GitLab is updated by SCIM whenever
externalIdchanges. Users cannot sign in unless the GitLab Identity (
extern_uid) value matches the
NameIdsent by SAML. This value is also used by SCIM to match users on the
id, and is updated by SCIM whenever the
- The SCIM
externalIdmust be configured to the same value as the SAML
NameId. You can trace SAML responses using debugging tools, and check any errors against the SAML troubleshooting information.
Unsure if user’s SAML
NameId matches the SCIM
To check if a user’s SAML
NameId matches their SCIM
- Administrators can use the Admin Area to list SCIM identities for a user.
- Group owners can see the list of users and the identifier stored for each user in the group SAML SSO Settings page.
- You can use the SCIM API to manually retrieve the
external_uidGitLab has stored for users and compare the value for each user from the SAML API .
- Have the user use a SAML Tracer and compare the
external_uidto the value returned as the SAML
extern_uid and SAML
Whether the value was changed or you need to map to a different field, the following must map to the same field:
If the GitLab
extern_uid doesn’t match the SAML
NameId, it must be updated for the user to sign in. Your identity
provider should be configured to do this update. In some cases the identity provider cannot do the update, for example
when a user lookup fails because of an ID change.
Be cautious if you revise the fields used by your SCIM identity provider, typically
GitLab uses 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.
extern_uid for a user is not correct, and also doesn’t match the SAML
- Have users unlink and relink themselves, based on the SAML authentication failed: User has already been taken section.
- Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on.
- Use the SCIM API to manually correct the
extern_uidstored for users to match the SAML
NameId. To look up a user, you must know the desired value that matches the
NameIdas well as the current
You must not:
- Update these to incorrect values because this causes users to be unable to sign in.
- Assign a value to the wrong user because this causes users to be signed in to the wrong account.
Change SCIM app
When the SCIM app changes:
- Users can follow the instructions in the Change the SAML app section.
- Administrators of the identity provider can:
- Remove users from the SCIM app, which unlinks all removed users.
- Turn on sync for the new SCIM app to link existing users.
SCIM app returns
"User has already been taken","status":409 error
Changing the SAML or SCIM configuration or provider can cause the following problems:
- SAML and SCIM identity mismatch. To solve this problem:
- SCIM identity mismatch between GitLab and the identity provider SCIM app. To solve this problem:
- Use the SCIM API, which displays the user’s
extern_uidstored in GitLab and compares it with the user
externalIdin the SCIM app.
- Use the same SCIM API to update the SCIM
extern_uidfor the user on GitLab.com.
- Use the SCIM API, which displays the user’s
Search Rails logs for SCIM requests
GitLab.com administrators can search for SCIM requests in the
api_json.log using the
pubsub-rails-inf-gprd-* index in
Kibana. Use the following filters based
on the internal group SCIM API:
In a relevant log entry, the
json.params.value shows the values of SCIM parameters GitLab receives. Use these values
to verify if SCIM parameters configured in an identity provider’s SCIM app are communicated to GitLab as intended.
For example, use these values as a definitive source on why an account was provisioned with a certain set of details. This information can help where an account was SCIM provisioned with details that do not match the SCIM app configuration.
Azure Active Directory
The following troubleshooting information is specifically for SCIM provisioned through Azure Active Directory.
Verify my SCIM configuration is correct
- The matching precedence for
- The SCIM value for
externalIdmatches the SAML value for
Review the following SCIM parameters for sensible values:
emails[type eq "work"].value
invalid credentials error when testing connection
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
Tenant URL and
secret token are correct, check whether your group path contains characters that may be considered
invalid JSON primitives (such as
.). Removing or URL encoding these characters in the group path typically resolves the error.
(Field) can't be blank sync error
When checking the Audit Events for the provisioning, you sometimes see a
Namespace can't be blank, Name can't be blank,
and User can't be blank. error.
This error can occur 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.
- Delete the
name.formattedtarget attribute entry.
- Change the
displayNamesource attribute to have
Failed to match an entry in the source and target systems Group 'Group-Name' error
Group provisioning in Azure can fail with the
Failed to match an entry in the source and target systems Group 'Group-Name'
error. The error response can include a HTML result of the GitLab URL
This error is harmless and occurs because group provisioning was turned on but GitLab SCIM integration does not support it nor require it. To remove the error, follow the instructions in the Azure configuration guide to disable the option to synchronize Azure Active Directory groups to AppName.
The following troubleshooting information is specifically for SCIM provisioned through Okta.
Error authenticating: null message when testing API SCIM credentials
When testing the API credentials in your Okta SCIM application, you may encounter an error:
Error authenticating: null
Okta needs to be able to connect to your GitLab instance to provision or deprovision users.
In your Okta SCIM application, check that the SCIM Base URL is correct and pointing to a valid GitLab SCIM API endpoint URL. Check the following documentation to find information on this URL for:
For self-managed GitLab instances, ensure that GitLab is publicly available so Okta can connect to it. If needed, you can allow access to Okta IP addresses on your firewall.