diff options
Diffstat (limited to 'doc/user/group/saml_sso/scim_setup.md')
| -rw-r--r-- | doc/user/group/saml_sso/scim_setup.md | 82 |
1 files changed, 60 insertions, 22 deletions
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index e333fd19c1b..f66c8a788b6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -12,25 +12,28 @@ that group is synchronized between GitLab and the identity provider. GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). +## Features + Currently, the following actions are available: -- CREATE -- UPDATE -- DELETE (deprovisioning) +- Create users +- Update users (Azure only) +- Deactivate users The following identity providers are supported: - Azure +- Okta ## Requirements -- [Group SSO](index.md) must be configured. +- [Group Single Sign-On](index.md) must be configured. ## GitLab configuration -Once [Single sign-on](index.md) has been configured, we can: +Once [Group Single Sign-On](index.md) has been configured, we can: -1. Navigate to the group and click **Settings > SAML SSO**. +1. Navigate to the group and click **Administration > SAML SSO**. 1. Click on the **Generate a SCIM token** button. 1. Save the token and URL so they can be used in the next step. @@ -38,9 +41,12 @@ Once [Single sign-on](index.md) has been configured, we can: ## Identity Provider configuration -### Azure +- [Azure](#azure-configuration-steps) +- [Okta](#okta-configuration-steps) + +### Azure configuration steps -The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM. +The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications) now needs to be set up for SCIM. 1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab. @@ -109,6 +115,43 @@ bottom of the **Provisioning** screen, together with a link to the audit logs. CAUTION: **Warning:** Once synchronized, changing the field mapped to `id` and `externalId` will likely cause provisioning errors, duplicate users, and prevent existing users from accessing the GitLab group. +### 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/saml-application-setup/overview/) now needs to be set up for SCIM. +Before proceeding, be sure to complete the [GitLab configuration](#gitlab-configuration) process. + +1. Sign in to Okta. +1. If you see an **Admin** button in the top right, click the button. This will + ensure you are in the Admin area. + + TIP: **Tip:** 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: + +1. In the **Application** tab, click **Add Application**. +1. Search for **GitLab**, find and click on the 'GitLab' application. +1. On the GitLab application overview page, click **Add**. +1. Under **Application Visibility** select both check boxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users. +1. Click **Done** to finish adding the application. +1. In the **Provisioning** tab, click **Configure API integration**. +1. 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 +1. Click 'Test API Credentials' to verify configuration. +1. Click **Save** to apply the settings. +1. After saving the API integration details, new settings tabs will appear on the left. Choose **To App**. +1. Click **Edit**. +1. Check the box to **Enable** for both **Create Users** and **Deactivate Users**. +1. Click **Save**. +1. Assign users in the **Assignments** tab. Assigned users will be created and + managed in your GitLab group. + +#### Okta Known Issues + +The Okta GitLab application currently only supports SCIM. Continue +using the separate Okta [SAML SSO](index.md) configuration along with the new SCIM +application described above. + ## User access and linking setup As long as [Group SAML](index.md) has been configured, prior to turning on sync, existing GitLab.com users can link to their accounts in one of the following ways, before synchronization is active: @@ -135,7 +178,9 @@ Upon the next sync, the user will be deprovisioned, which means that the user wi This section contains possible solutions for problems you might encounter. -### How do I verify my SCIM configuration is correct? +### Azure + +#### How do I verify my SCIM configuration is correct? Review the following: @@ -148,11 +193,11 @@ Review the following SCIM parameters for sensible values: - `displayName` - `emails[type eq "work"].value` -### Testing Azure connection: invalid credentials +#### 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 +#### 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.` @@ -165,14 +210,7 @@ As a workaround, try an alternate mapping: 1. Delete the `name.formatted` target attribute entry. 1. Change the `displayName` source attribute to have `name.formatted` target attribute. -### Message: "SAML authentication failed: Email has already been taken" - -This message may be caused by the following: - -- Existing users have not yet signed into the new app. -- The identity provider attempts to create a new user account in GitLab with an email address that already exists in GitLab.com. - -### How do I diagnose why a user is unable to sign in +#### How do I diagnose why a user is unable to sign in The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users won't be able to sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. @@ -180,7 +218,7 @@ This value is also used by SCIM to match users on the `id`, and is updated by SC 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. @@ -194,7 +232,7 @@ curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex= To see how this 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. @@ -220,7 +258,7 @@ curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP 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. |