diff options
Diffstat (limited to 'doc/user/group/saml_sso/scim_setup.md')
| -rw-r--r-- | doc/user/group/saml_sso/scim_setup.md | 86 |
1 files changed, 45 insertions, 41 deletions
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index c6444ada165..7c089a289c6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -121,8 +121,12 @@ Once synchronized, changing the field mapped to `id` and `externalId` may cause ### Okta configuration steps -The SAML application that was created during [Single sign-on](index.md#okta-setup-notes) setup for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) now needs to be set up for SCIM. -Before proceeding, be sure to complete the [GitLab configuration](#gitlab-configuration) process. +Before you start this section, complete the [GitLab configuration](#gitlab-configuration) process. +Make sure that you've also set up a SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), +as described in the [Okta setup notes](index.md#okta-setup-notes) + +Make sure that the Okta setup matches our documentation exactly, especially the NameID +configuration. Otherwise, the Okta SCIM app may not work properly. 1. Sign in to Okta. 1. If you see an **Admin** button in the top right, click the button. This will @@ -212,39 +216,7 @@ When the user is added back to the SCIM app, GitLab cannot create a new user bec Solution: Have a user sign in directly to GitLab, then [manually link](#user-access-and-linking-setup) their account. -### Azure - -#### How do I verify my SCIM configuration is correct? - -Review the following: - -- 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`. - -Review the following SCIM parameters for sensible values: - -- `userName` -- `displayName` -- `emails[type eq "work"].value` - -#### Testing Azure connection: invalid credentials - -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. - -#### Azure: (Field) can't be blank sync error - -When checking the Audit Logs 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.` - -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: - -1. Follow the Azure mapping instructions from above. -1. Delete the `name.formatted` target attribute entry. -1. Change the `displayName` source attribute to have `name.formatted` target attribute. - -#### How do I diagnose why a user is unable to sign in +### How do I diagnose why a user is unable to sign in Ensure that the user has been added to the SCIM app. @@ -254,9 +226,9 @@ The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenev 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. -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](./index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](./index.md#troubleshooting). +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](index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](index.md#troubleshooting). -#### How do I verify user's SAML NameId matches the SCIM externalId +### How do I verify user's SAML NameId matches the SCIM externalId Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. @@ -264,7 +236,7 @@ A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list- To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). -#### Update or fix mismatched SCIM externalId and SAML NameId +### 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. @@ -277,15 +249,47 @@ 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: -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](./index.md#message-saml-authentication-failed-user-has-already-been-taken) section. +- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](index.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. - It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-saml-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. To look up a user, you'll need to know the desired value that matches the `NameId` as well as the current `externalId`. It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account. -#### I need to change my SCIM app +### I need to change my SCIM app -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](./index.md#i-need-to-change-my-saml-app) section. +Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section. Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). + +### Azure + +#### How do I verify my SCIM configuration is correct? + +Review the following: + +- 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`. + +Review the following SCIM parameters for sensible values: + +- `userName` +- `displayName` +- `emails[type eq "work"].value` + +#### Testing Azure connection: invalid credentials + +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. + +#### (Field) can't be blank sync error + +When checking the Audit Logs 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.` + +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: + +1. Follow the Azure mapping instructions from above. +1. Delete the `name.formatted` target attribute entry. +1. Change the `displayName` source attribute to have `name.formatted` target attribute. |