diff options
Diffstat (limited to 'doc/user/group/saml_sso/troubleshooting_scim.md')
| -rw-r--r-- | doc/user/group/saml_sso/troubleshooting_scim.md | 156 |
1 files changed, 96 insertions, 60 deletions
diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 6f8aed4b386..22562c51e9e 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -8,93 +8,120 @@ info: To determine the technical writer assigned to the Stage/Group associated w This section contains possible solutions for problems you might encounter. -## How come I can't add a user after I removed them? +## User cannot be added after they are removed -As outlined in the [Blocking access section](scim_setup.md#blocking-access), when you remove a user, they are removed from the group. However, their account is not deleted. +When you remove a user, they are removed from the group but their account is not deleted +(see [remove access](scim_setup.md#remove-access)). 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](scim_setup.md#user-access-and-linking-setup) their account. +To solve this problem: -## How do I diagnose why a user is unable to sign in +1. Have the user sign in directly to GitLab. +1. [Manually link](scim_setup.md#link-scim-and-saml-identities) their account. -Ensure that the user has been added to the SCIM app. +## User cannot sign in -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](scim_setup.md#user-access-and-linking-setup) instructions. +The following are possible solutions for problems where users cannot sign in: -The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users cannot sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. +- Ensure that the user was added to the SCIM app. +- If you receive the `User is not linked to a SAML account` error, the user probably already exists in GitLab. Have the + user follow the [Link SCIM and SAML identities](scim_setup.md#link-scim-and-saml-identities) instructions. +- The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `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 `id` or `externalId` values change. +- The SCIM `id` and SCIM `externalId` must be configured to the same value as the SAML `NameId`. You can trace SAML responses + using [debugging tools](troubleshooting.md#saml-debugging-tools), and check any errors against the + [SAML troubleshooting](troubleshooting.md) information. -This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. +## Unsure if user's SAML `NameId` matches the SCIM `externalId` -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](troubleshooting.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](troubleshooting.md). +To check if a user's SAML `NameId` matches their SCIM `externalId`: -## How do I verify user's SAML NameId matches the SCIM externalId +- Administrators can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). +- 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](../../../api/scim.md) to manually retrieve the `external_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . +- Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `external_uid` to + the value returned as the SAML `NameId`. -Administrators can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). +## Mismatched SCIM `extern_uid` and SAML `NameId` -Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. +Whether the value was changed or you need to map to a different field, the following must map to the same field: -A possible alternative is to use the [SCIM API](../../../api/scim.md) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. +- `id` +- `externalId` +- `NameId` -To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools). - -## Update or fix mismatched SCIM externalId and SAML NameId - -Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `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. +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 `id` and `externalId`. -We use these IDs to look up users. If the identity provider does not know the current values for these fields, +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. -If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, -you can address the problem in the following ways: +If the `extern_uid` for a user is not correct, and also doesn't match the SAML `NameID`, either: + +- Have users unlink and relink themselves, based on the + [SAML authentication failed: User has already been taken](troubleshooting.md#message-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](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML + `NameId`. To look up a user, you must know the desired value that matches the `NameId` as well as the current + `extern_uid`. -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](troubleshooting.md#message-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. -- Use the [SCIM API](../../../api/scim.md) to manually correct the `externalId` stored for users to match the SAML `NameId`. - To look up a user, you need to know the desired value that matches the `NameId` as well as the current `externalId`. +You must not: -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. +- 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. -## I need to change my SCIM app +## Change SCIM app -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#change-the-saml-app) section. +When the SCIM app changes: -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](scim_setup.md#user-access-and-linking-setup). +- Users can follow the instructions in the [Change the SAML app](index.md#change-the-saml-app) section. +- Administrators of the identity provider can: + 1. Remove users from the SCIM app, which unlinks all removed users. + 1. Turn on sync for the new SCIM app to [link existing users](scim_setup.md#link-scim-and-saml-identities). -## The SCIM app is throwing `"User has already been taken","status":409` error message +## SCIM app returns `"User has already been taken","status":409` error Changing the SAML or SCIM configuration or provider can cause the following problems: -| Problem | Solution | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | -| SCIM identity mismatch between GitLab and the identity 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 the [SCIM API](../../../api/scim.md) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md) to update the SCIM `id` for the user on GitLab.com. | +- SAML and SCIM identity mismatch. To solve this problem: + 1. [Verify that the user's SAML `NameId` matches the SCIM `extern_uid`](#unsure-if-users-saml-nameid-matches-the-scim-externalid). + 1. [Update or fix the mismatched SCIM `extern_uid` and SAML `NameId`](#mismatched-scim-extern_uid-and-saml-nameid). +- SCIM identity mismatch between GitLab and the identity provider SCIM app. To solve this problem: + 1. Use the [SCIM API](../../../api/scim.md), which displays the user's `extern_uid` stored in GitLab and compares it with the user `externalId` in + the SCIM app. + 1. Use the same SCIM API to update the SCIM `extern_uid` for the user on GitLab.com. ## 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](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based on the internal -[SCIM API](../../../development/internal_api/index.md#scim-api): +[Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based +on the internal [SCIM API](../../../development/internal_api/index.md#scim-api): - `json.path`: `/scim/v2/groups/<group-path>` - `json.params.value`: `<externalId>` -In a relevant log entry, the `json.params.value` shows the values of SCIM parameters GitLab receives. These values can be used to verify if SCIM parameters configured in an -identity provider's SCIM app are communicated to GitLab as intended. For example, we can 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 appear to be incongruent with what might have been configured within an identity -provider's SCIM app. +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. -## Azure +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. -### How do I verify my SCIM configuration is correct? +## Azure Active Directory -Review the following: +The following troubleshooting information is specifically for SCIM provisioned through Azure Active Directory. -- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. -- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. +### Verify my SCIM configuration is correct + +Ensure that: + +- The matching precedence for `externalId` is 1. +- The SCIM value for `externalId` matches the SAML value for `NameId`. Review the following SCIM parameters for sensible values: @@ -102,28 +129,37 @@ Review the following SCIM parameters for sensible values: - `displayName` - `emails[type eq "work"].value` -### Testing Azure connection: invalid credentials +### `invalid credentials` error when testing connection + +When testing the connection, you may encounter an error: + +```plaintext +You appear to have entered invalid credentials. Please confirm +you are using the correct information for an administrative account +``` -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. +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 or URL encoding these characters in the group path typically resolves the error. -### (Field) can't be blank sync error +### `(Field) can't be blank` sync error -When checking the Audit Events for the Provisioning, you can sometimes see the -error `Namespace can't be blank, Name can't be blank, and User can't be blank.` +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 is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. +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: -1. Follow the Azure mapping instructions from above. +1. Follow the [Azure mapping instructions](scim_setup.md#configure-attribute-mappings). 1. Delete the `name.formatted` target attribute entry. 1. Change the `displayName` source attribute to have `name.formatted` target attribute. -### Failed to match an entry in the source and target systems Group 'Group-Name' +### `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 message, -and the error response can include a HTML result of the GitLab URL `https://gitlab.com/users/sign_in`. +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 `https://gitlab.com/users/sign_in`. -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 -[`Synchronize Azure Active Directory Groups to AppName`](scim_setup.md#configure-azure-active-directory). +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](scim_setup.md#configure-azure-active-directory). |