doc/user/group/saml_sso/troubleshooting.md
{{< details >}}
{{< /details >}}
This page contains possible solutions for problems you might encounter when using:
SAML responses are base64 encoded. To decode them on the fly you can use the SAML-tracer browser extension (Firefox, Chrome).
If you cannot install a browser plugin, you can manually generate and capture a SAML response instead.
Pay specific attention to:
NameID, which identifies the user signing in. If the user has previously
signed in, this must match the value that GitLab stored.X509Certificate, which is required to verify the response signature.SubjectConfirmation and Conditions, which can cause errors if misconfigured.Use SAML responses to preview the attribute names and values sent in the assertions list while attempting to sign in using an identity provider.
To generate a SAML Response:
SAML Login button to sign in<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see this video on manually generating a SAML response without using a browser plugin (using Google Chrome), uploaded by GitLab Support.
<!-- Video published on 2024-09-09 -->Regardless of what browser you use, the process is similar to the following:
Right-click on a new browser and select Inspect to open the DevTools window.
Select the Network tab. Make sure that Preserve log is selected.
Switch to the browser page and sign in to GitLab using SAML SSO.
Switch back to the DevTools window and filter for the callback event.
Select the Payload tab for the callback event and right-click to copy the value.
Paste this value into the following command: echo "<value>" | base64 --decode > saml_response.xml.
Open saml_response.xml in a code editor.
If you have an XML "prettifier" installed in your code editor, you should be able to automatically format the response to be easier to read.
{{< details >}}
{{< /details >}}
You can find detailed information about a SAML sign-in in the audit_json.log file.
For example, by searching for system_access, you can find entries that show when a user signed into GitLab using SAML:
{
"severity": "INFO",
"time": "2024-08-13T06:05:35.721Z",
"correlation_id": "01J555EZK136DQ8S7P32G9GEND",
"meta.caller_id": "OmniauthCallbacksController#saml",
"meta.remote_ip": "45.87.213.198",
"meta.feature_category": "system_access",
"meta.user": "bbtest",
"meta.user_id": 16,
"meta.client_id": "user/16",
"author_id": 16,
"author_name": "[email protected]",
"entity_id": 16,
"entity_type": "User",
"created_at": "2024-08-13T06:05:35.708+00:00",
"ip_address": "45.87.213.198",
"with": "saml",
"target_id": 16,
"target_type": "User",
"target_details": "[email protected]",
"entity_path": "bbtest"
}
If you have configured SAML Group Links, the log also shows entries detailing membership being removed:
{
"severity": "INFO",
"time": "2024-08-13T05:24:07.769Z",
"correlation_id": "01J55330SRTKTD5CHMS96DNZEN",
"meta.caller_id": "Auth::SamlGroupSyncWorker",
"meta.remote_ip": "45.87.213.206",
"meta.feature_category": "system_access",
"meta.client_id": "ip/45.87.213.206",
"meta.root_caller_id": "OmniauthCallbacksController#saml",
"id": 179,
"author_id": 6,
"entity_id": 2,
"entity_type": "Group",
"details": {
"remove": "user_access",
"member_id": 7,
"author_name": "BB Test",
"author_class": "User",
"target_id": 6,
"target_type": "User",
"target_details": "BB Test",
"custom_message": "Membership destroyed",
"ip_address": "45.87.213.198",
"entity_path": "group1"
}
}
You can also see details of the user that GitLab received from the SAML provider in auth_json.log, for example:
{
"severity": "INFO",
"time": "2024-08-20T07:01:20.979Z",
"correlation_id": "01J5Q9E59X4P40ZT3MCE35C2A9",
"meta.caller_id": "OmniauthCallbacksController#saml",
"meta.remote_ip": "xxx.xxx.xxx.xxx",
"meta.feature_category": "system_access",
"meta.client_id": "ip/xxx.xxx.xxx.xxx",
"payload_type": "saml_response",
"saml_response": {
"issuer": [
"https://sts.windows.net/03b8c6c5-104b-43e2-aed3-abb07df387cc/"
],
"name_id": "ab260d59-0317-47f5-9afb-885c7a1257ab",
"name_id_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
"name_id_spnamequalifier": null,
"name_id_namequalifier": null,
"destination": "https://dh-gitlab.agounder.com/users/auth/saml/callback",
"audiences": [
"https://dh-gitlab.agounder.com/16.11.6"
],
"attributes": {
"http://schemas.microsoft.com/identity/claims/tenantid": [
"03b8c6c5-104b-43e2-aed3-abb07df387cc"
],
"http://schemas.microsoft.com/identity/claims/objectidentifier": [
"ab260d59-0317-47f5-9afb-885c7a1257ab"
],
"http://schemas.microsoft.com/identity/claims/identityprovider": [
"https://sts.windows.net/03b8c6c5-104b-43e2-aed3-abb07df387cc/"
],
"http://schemas.microsoft.com/claims/authnmethodsreferences": [
"http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password"
],
"email": [
"[email protected]"
],
"firstname": [
"BB"
],
"name": [
"[email protected]"
],
"lastname": [
"Test"
]
},
"in_response_to": "_f8863f68-b5f1-43f0-9534-e73933e6ed39",
"allowed_clock_drift": 2.220446049250313e-16,
"success": true,
"status_code": "urn:oasis:names:tc:SAML:2.0:status:Success",
"status_message": null,
"session_index": "_b4f253e2-aa61-46a4-902b-43592fe30800",
"assertion_encrypted": false,
"response_id": "_392cc747-7c8b-41de-8be0-23f5590d5ded",
"assertion_id": "_b4f253e2-aa61-46a4-902b-43592fe30800"
}
}
You can use one of the following to troubleshoot SAML:
For convenience, some example resources used by the GitLab Support Team are included. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products.
When configuring the idp_cert_fingerprint, you should use a SHA256 fingerprint whenever possible. SHA1 is also supported, but is not recommended. To calculate the fingerprint, run the following command on the certificate file:
openssl x509 -in <certificate.crt> -noout -fingerprint -sha256
Replace <certificate.crt> with the name of the certificate file.
[!note] In GitLab 17.11 and later, the fingerprint algorithm is automatically detected based on fingerprint length.
In GitLab 17.10 and earlier, SHA1 is the default fingerprint algorithm. To use a SHA256 fingerprint, you must specify the algorithm:
rubyidp_cert_fingerprint_algorithm: "http://www.w3.org/2001/04/xmlenc#sha256"
When the certificate used for your identity provider changes (for example when updating or renewing the certificate), you must update the certificate fingerprint as well. You can find the certificate fingerprint in your identity provider's UI. If you cannot get the certificate in the identity provider UI, follow the steps in the calculate the fingerprint documentation.
This error means that the identity provider doesn't recognize GitLab as a valid sender and receiver of SAML requests. Make sure to:
issuer string.These errors all come from a similar place, the SAML certificate. SAML requests must be validated using either a fingerprint, a certificate, or a validator.
For this requirement, be sure to take the following into account:
idp_cert_fingerprint. The values should be the same.<ds:KeyInfo><ds:X509Data><ds:X509Certificate>).If none of the previously described scenarios is valid, the request fails with one of the mentioned errors.
Email can't be blank errorsThe identity provider server needs to pass certain information in order for GitLab to either
create an account, or match the login information to an existing account. email
is the minimum amount of information that needs to be passed. If the identity provider server
is not providing this information, all SAML requests fail.
Make sure this information is provided.
Another issue that can result in this error is when the correct information is being sent by
the identity provider, but the attributes don't match the names in the OmniAuth info hash. In this case,
you must set attribute_statements in the SAML configuration to
map the attribute names in your SAML Response to the corresponding OmniAuth info hash names.
SAML authentication failed: SAML NameID is missing from your SAML response.You might get an error that states SAML authentication failed: SAML NameID is missing from your SAML response. Please contact your administrator.
This issue occurs when you try sign into GitLab using Group SSO, but your SAML response did not include a NameID.
To resolve this issue:
NameID.NameID.SAML authentication failed: Extern uid has already been taken.You might get an error that states SAML authentication failed: Extern uid has already been taken. Please contact your administrator to generate a unique external_uid (NameID).
This issue occurs when you try to link your existing GitLab account to a SAML identity using Group SSO, but there is an existing GitLab account with your current NameID.
To resolve this issue, tell your administrator to re-generate a unique Extern UID (NameID) for your IdP account. Make sure this new Extern UID adheres to the GitLab NameID constraints.
If you do not wish to use that GitLab user with the SAML login, you can unlink the GitLab account from the SAML app.
SAML authentication failed: User has already been takenThe user that you're signed in with already has SAML linked to a different identity, or the NameID value has changed.
Here are possible causes and solutions:
| Cause | Solution |
|---|---|
| You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, unlink the previous SAML identity from this GitLab account before attempting to sign in again. |
The NameID changes every time the user requests SSO identification | Check the NameID is not set with Transient format, or the NameID is not changing on subsequent requests. |
SAML authentication failed: Email has already been taken| Cause | Solution |
|---|---|
| If a GitLab user account exists with the same email address, but the account is not associated with a SAML identity. | On GitLab.com, the user needs to link their account. On GitLab Self-Managed, administrators can configure the instance to automatically link the SAML identity with the GitLab user account when they first sign in. |
User accounts are created in one of the following ways:
Getting both of these errors at the same time suggests the NameID capitalization provided by the identity provider didn't exactly match the previous value for that user:
SAML authentication failed: Extern UID has already been takenUser has already been takenThis can be prevented by configuring the NameID to return a consistent value. Fixing this for an individual user involves changing the identifier for the user. For GitLab.com, the user needs to unlink their SAML from the GitLab account.
Request to link SAML account must be authorizedEnsure that the user who is trying to link their GitLab account has been added as a user within the identity provider's SAML app.
Alternatively, the SAML response may be missing the InResponseTo attribute in the
samlp:Response tag, which is expected by the SAML gem.
The identity provider administrator should ensure that the login is
initiated by the service provider and not only the identity provider.
There is already a GitLab account associated with this email address.{{< details >}}
{{< /details >}}
A user can see this message when they are trying to manually link SAML to their existing GitLab.com account:
There is already a GitLab account associated with this email address.
Sign in with your existing credentials to connect your organization's account
To resolve this problem, the user should check they are using the correct GitLab password to sign in. The user first needs to reset their password if both:
SAML Name ID and email address do not match your user account{{< details >}}
{{< /details >}}
Users might get an error that states "SAML Name ID and email address do not match your user account. Contact an administrator." This means:
extern_uid value. Both the NameID and the extern_uid are case-sensitive. For more information, see manage user SAML identity.The workaround is that a GitLab group Owner uses the SAML API to update the user's SAML extern_uid.
The extern_uid value must match the Name ID value sent by the SAML identity provider (IdP). Depending on the IdP configuration
this may be a generated unique ID, an email address, or other value.
Certificate element missing in response (ds:x509certificate)This error suggests that the IdP is not configured to include the X.509 certificate in the SAML response:
Certificate element missing in response (ds:x509certificate) and not cert provided at settings
The X.509 certificate must be included in the response. To resolve this problem, configure your IdP to include the X.509 certificate in the SAML response.
For more information, see the documentation on additional configuration for SAML apps on your IdP.
NameIDIn troubleshooting, any authenticated user can use the API to verify the NameID GitLab already has linked to their user by visiting https://gitlab.com/api/v4/user and checking the extern_uid under identities.
For GitLab Self-Managed, administrators can use the users API to see the same information.
When using SAML for groups, group members of a role with the appropriate permissions can make use of the members API to view group SAML identity information for members of the group.
This can then be compared to the NameID sent by the identity provider by decoding the
message with a SAML debugging tool. These values must match to
identify users.
Ensure that the GitLab single sign-on URL (for GitLab.com) or the instance URL (for GitLab Self-Managed) has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app.
For GitLab.com, alternatively, when users need to link SAML to their existing GitLab.com account, provide the GitLab single sign-on URL and instruct users not to use the SAML app on first sign in.
{{< details >}}
{{< /details >}}
If the user receives a 404 after signing in successfully, check if you have IP restrictions configured. IP restriction settings are configured:
Because SAML SSO for groups is a paid feature, your subscription expiring can result in a 404 error when you're signing in using SAML SSO on GitLab.com.
If all users are receiving a 404 when attempting to sign in using SAML, confirm
there is an active subscription being used in this SAML SSO namespace.
If you receive a 404 during setup when using "verify configuration", make sure you have used the correct
SHA-1 generated fingerprint.
If a user is trying to sign in for the first time and the GitLab single sign-on URL has not been configured, they may see a 404. As outlined in the user access section, a group Owner needs to provide the URL to users.
If the top-level group has restricted membership by email domain, and a user with an email domain that is not allowed tries to sign in with SSO, that user might receive a 404. Users might have multiple accounts, and their SAML identity might be linked to their personal account which has an email address that is different than the company domain. To check this, verify the following:
If all users are receiving a 404 after signing in to the identity provider (IdP):
assertion_consumer_service_url:
Assertion Consumer Service URL or equivalent when setting up the SAML app on your IdP.404 is related to the user having too many groups assigned to them in their Azure IdP.If a subset of users receive a 404 error after they sign in to the IdP, first verify what audit events are returned if the user is added to the group and then immediately removed. Alternatively, if the user can successfully sign in, but they do not show as a member of the top-level group:
Ensure the user has been added to the SAML identity provider, and SCIM if configured.
Ensure the user's SCIM identity's active attribute is true using the SCIM API.
If the active attribute is false, you can do one of the following to possibly resolve the issue:
Trigger a sync for the user in the SCIM identity provider. For example, Azure has a "Provision on demand" option.
Remove and re-add the user in the SCIM identity provider.
Have the user unlink their account if possible, then link their account.
Use the internal SCIM API to update the user's SCIM identity using your group's SCIM token. If you do not know your group's SCIM token, reset the token and update the SCIM identity provider app with the new token. Example request:
curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --header "Content-Type: application/scim+json" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }'
{{< details >}}
{{< /details >}}
If you see a "500 error" in GitLab when you are redirected back from the SAML sign-in page, this could indicate that:
email or mail.gitlab.rb file for identity provider_cert_fingerprint or identity provider_cert file is incorrect.gitlab.rb file is set to enable identity provider_cert_fingerprint, and identity provider_cert is being provided, or the reverse.{{< details >}}
{{< /details >}}
If you see a "422 error" in GitLab when you are redirected from the SAML sign-in page, you might have an incorrectly configured Assertion Consumer Service (ACS) URL on the identity provider.
Make sure the ACS URL points to https://gitlab.example.com/users/auth/saml/callback, where
gitlab.example.com is the URL of your GitLab instance.
If the ACS URL is correct, and you still have errors, review the other Troubleshooting sections.
You might get a 422 error that states "Email is not allowed. Please use your regular email address."
This message might indicate that you must add or remove a domain from your domain allowlist or denylist settings.
Prerequisites:
To implement this workaround:
{{< details >}}
{{< /details >}}
The following are the most likely reasons that a user is blocked when signing in through SAML:
gitlab_rails['omniauth_block_auto_created_users'] = true is set and this is the user's first time signing in.required_groups are configured but the user is not a member of one.The Google Workspace documentation on SAML app error messages is helpful for debugging if you are seeing an error from Google while signing in. Pay particular attention to the following 403 errors:
app_not_configuredapp_not_configured_for_userThe member's email address is not linked to a SAML account{{< details >}}
{{< /details >}}
This error appears when you try to invite a user to a GitLab.com group (or subgroup or project within a group) that has SAML SSO enforcement enabled.
If you see this message after trying to invite a user to a group:
Additionally, see troubleshooting users receiving a 404 after sign in.
The SAML response did not contain an email address.If you see this error:
The SAML response did not contain an email address.
Either the SAML identity provider is not configured to send the attribute, or the
identity provider directory does not have an email address value for your user
This error appears when:
Ensure the SAML identity provider is configured to send a supported mail attribute:
<Attribute Name="email">
<AttributeValue>[email protected]‹/AttributeValue>
</Attribute>
Attribute names starting with phrases such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims and http://schemas.microsoft.com/ws/2008/06/identity/claims/ are supported by default beginning in GitLab 16.7.
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress">
<AttributeValue>[email protected]‹/AttributeValue>
</Attribute>
{{< details >}}
{{< /details >}}
If the global SAML group membership lock is enabled, only administrators can manage group members and service accounts through the UI. If a group Owner needs to manage service accounts, they can use the group members API instead.
If you're still having issues, see the GitLab Support knowledge base.