debian-mirror-gitlab/doc/user/group/saml_sso/scim_setup.md

228 lines
12 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
type: howto, reference
---
2020-01-01 13:55:28 +05:30
# SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)**
2019-07-31 22:56:46 +05:30
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10.
2019-07-31 22:56:46 +05:30
2019-09-04 21:01:54 +05:30
System for Cross-domain Identity Management (SCIM), is an open standard that enables the
automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of
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).
2019-07-31 22:56:46 +05:30
Currently, the following actions are available:
- CREATE
- UPDATE
- DELETE (deprovisioning)
The following identity providers are supported:
- Azure
## Requirements
2020-01-01 13:55:28 +05:30
- [Group SSO](index.md) must be configured.
2019-09-30 21:07:59 +05:30
2019-10-12 21:52:04 +05:30
## GitLab configuration
2019-07-31 22:56:46 +05:30
Once [Single sign-on](index.md) has been configured, we can:
1. Navigate to the group and click **Settings > 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.
2019-09-30 21:07:59 +05:30
![SCIM token configuration](img/scim_token.png)
2019-07-31 22:56:46 +05:30
2019-10-12 21:52:04 +05:30
## Identity Provider configuration
2019-07-31 22:56:46 +05:30
2019-10-12 21:52:04 +05:30
### Azure
2019-07-31 22:56:46 +05:30
2019-10-12 21:52:04 +05:30
The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM.
2019-07-31 22:56:46 +05:30
2019-10-12 21:52:04 +05:30
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.
2019-07-31 22:56:46 +05:30
2019-10-12 21:52:04 +05:30
![Name identifier value mapping](img/scim_name_identifier_mapping.png)
1. Set up automatic provisioning and administrative credentials by following the
2020-04-22 19:07:51 +05:30
[Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation.
2019-10-12 21:52:04 +05:30
During this configuration, note the following:
2019-07-31 22:56:46 +05:30
- The `Tenant URL` and `secret token` are the ones retrieved in the
2019-09-30 21:07:59 +05:30
[previous step](#gitlab-configuration).
2019-07-31 22:56:46 +05:30
- Should there be any problems with the availability of GitLab or similar
2019-09-30 21:07:59 +05:30
errors, the notification email set will get those.
2019-10-12 21:52:04 +05:30
- It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox.
2019-07-31 22:56:46 +05:30
- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled.
2019-10-12 21:52:04 +05:30
You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting).
2019-07-31 22:56:46 +05:30
2019-10-12 21:52:04 +05:30
#### Configure attribute mapping
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
1. Click on `Synchronize Azure Active Directory Users to AppName` to configure the attribute mapping.
2019-10-12 21:52:04 +05:30
1. Click **Delete** next to the `mail` mapping.
2020-01-01 13:55:28 +05:30
1. Map `userPrincipalName` to `emails[type eq "work"].value` and change its **Matching precedence** to `2`.
2019-10-12 21:52:04 +05:30
1. Map `mailNickname` to `userName`.
2019-12-26 22:10:19 +05:30
1. Determine how GitLab will uniquely identify users.
- Use `objectId` unless users already have SAML linked for your group.
- If you already have users with SAML linked then use the `Name ID` value from the [SAML configuration](#azure). Using a different value will likely cause duplicate users and prevent users from accessing the GitLab group.
2020-01-01 13:55:28 +05:30
1. Create a new mapping:
1. Click **Add New Mapping**.
1. Set:
2020-04-22 19:07:51 +05:30
- **Source attribute** to the unique identifier determined above, typically `objectId`.
- **Target attribute** to `externalId`.
2020-01-01 13:55:28 +05:30
- **Match objects using this attribute** to `Yes`.
- **Matching precedence** to `1`.
2019-09-30 21:07:59 +05:30
2020-04-22 19:07:51 +05:30
1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`.
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
1. Save your changes. For reference, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory).
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
NOTE: **Note:** If you used a unique identifier **other than** `objectId`, be sure to map it to `externalId`.
2019-10-12 21:52:04 +05:30
1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**.
2020-04-22 19:07:51 +05:30
1. Ensure the `id` is the primary and required field, and `externalId` is also required.
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
NOTE: **Note:**
`username` should neither be primary nor required as we don't support
that field on GitLab SCIM yet.
2019-07-31 22:56:46 +05:30
1. Save all the screens and, in the **Provisioning** step, set
2019-10-12 21:52:04 +05:30
the `Provisioning Status` to `On`.
![Provisioning status toggle switch](img/scim_provisioning_status.png)
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
NOTE: **Note:**
You can control what is actually synced by selecting the `Scope`. For example,
`Sync only assigned users and groups` will only sync the users assigned to
2019-10-12 21:52:04 +05:30
the application (`Users and groups`), otherwise, it will sync the whole Active Directory.
2019-07-31 22:56:46 +05:30
Once enabled, the synchronization details and any errors will appear on the
bottom of the **Provisioning** screen, together with a link to the audit logs.
2019-09-04 21:01:54 +05:30
2019-12-26 22:10:19 +05:30
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.
2020-03-13 15:44:24 +05:30
## 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:
- By updating their *primary* email address in their GitLab.com user account to match their identity provider's user profile email address.
- By following these steps:
1. Sign in to GitLab.com if needed.
1. Click on the GitLab app in the identity provider's dashboard or visit the **GitLab single sign on URL**.
1. Click on the **Authorize** button.
New users and existing users on subsequent visits can access the group through the identify provider's dashboard or by visiting links directly.
For role information, please see the [Group SAML page](index.md#user-access-and-management)
### Blocking access
To rescind access to the group, we recommend removing the user from the identity
provider or users list for the specific app.
Upon the next sync, the user will be deprovisioned, which means that the user will be removed from the group. The user account will not be deleted unless using [group managed accounts](index.md#group-managed-accounts).
2019-10-12 21:52:04 +05:30
## Troubleshooting
2020-01-01 13:55:28 +05:30
This section contains possible solutions for problems you might encounter.
2020-03-13 15:44:24 +05:30
### 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`
2019-10-12 21:52:04 +05:30
### 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.
2019-09-04 21:01:54 +05:30
2019-10-12 21:52:04 +05:30
As a workaround, try an alternate mapping:
2019-09-04 21:01:54 +05:30
2019-10-12 21:52:04 +05:30
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.
2020-03-13 15:44:24 +05:30
2020-04-22 19:07:51 +05:30
### 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.
2020-03-13 15:44:24 +05:30
### 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.
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).
### 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.
Alternatively, the [SCIM API](../../../api/scim.md#get-a-list-of-saml-users) can be used to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`.
For example:
```shell
curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"
```
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).
2020-04-22 19:07:51 +05:30
### 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.
2020-03-13 15:44:24 +05:30
If GitLab's `externalId` doesn't match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be 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.
2020-04-22 19:07:51 +05:30
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,
that provider may create duplicate users.
2020-03-13 15:44:24 +05:30
2020-04-22 19:07:51 +05:30
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:
2020-03-13 15:44:24 +05:30
2020-04-22 19:07:51 +05:30
- 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.
- You can 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`.
2020-03-13 15:44:24 +05:30
It is then possible to issue a manual SCIM#update request, for example:
```shell
curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP/Users/OLD_EXTERNAL_UID' --data '{ "Operations": [{"op":"Replace","path":"externalId","value":"NEW_EXTERNAL_UID"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"
```
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.
2020-04-22 19:07:51 +05:30
### 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.
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).