diff options
Diffstat (limited to 'doc/user/group/saml_sso')
| -rw-r--r-- | doc/user/group/saml_sso/img/group_saml_configuration_information.png | bin | 50435 -> 16489 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/group_saml_settings.png | bin | 89399 -> 50300 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/scim_advanced.png | bin | 21568 -> 6920 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/scim_attribute_mapping.png | bin | 95420 -> 34642 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/scim_name_identifier_mapping.png | bin | 0 -> 59409 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/scim_provisioning_status.png | bin | 0 -> 7756 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/scim_token.png | bin | 154318 -> 57095 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/img/unlink_group_saml.png | bin | 27077 -> 9399 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 23 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/scim_setup.md | 120 |
10 files changed, 89 insertions, 54 deletions
diff --git a/doc/user/group/saml_sso/img/group_saml_configuration_information.png b/doc/user/group/saml_sso/img/group_saml_configuration_information.png Binary files differindex 98b83d0cb0f..e03c50ceb01 100644 --- a/doc/user/group/saml_sso/img/group_saml_configuration_information.png +++ b/doc/user/group/saml_sso/img/group_saml_configuration_information.png diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png Binary files differindex d95acb5075f..487be4faeba 100644 --- a/doc/user/group/saml_sso/img/group_saml_settings.png +++ b/doc/user/group/saml_sso/img/group_saml_settings.png diff --git a/doc/user/group/saml_sso/img/scim_advanced.png b/doc/user/group/saml_sso/img/scim_advanced.png Binary files differindex 3b70e3fbe83..c9e095dc89a 100644 --- a/doc/user/group/saml_sso/img/scim_advanced.png +++ b/doc/user/group/saml_sso/img/scim_advanced.png diff --git a/doc/user/group/saml_sso/img/scim_attribute_mapping.png b/doc/user/group/saml_sso/img/scim_attribute_mapping.png Binary files differindex c9f6b71f5b0..933d8fb6f36 100644 --- a/doc/user/group/saml_sso/img/scim_attribute_mapping.png +++ b/doc/user/group/saml_sso/img/scim_attribute_mapping.png diff --git a/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png Binary files differnew file mode 100644 index 00000000000..f9c63970f16 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png diff --git a/doc/user/group/saml_sso/img/scim_provisioning_status.png b/doc/user/group/saml_sso/img/scim_provisioning_status.png Binary files differnew file mode 100644 index 00000000000..41466ec9276 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_provisioning_status.png diff --git a/doc/user/group/saml_sso/img/scim_token.png b/doc/user/group/saml_sso/img/scim_token.png Binary files differindex 7eb52bf6ea2..bf9347716e9 100644 --- a/doc/user/group/saml_sso/img/scim_token.png +++ b/doc/user/group/saml_sso/img/scim_token.png diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png Binary files differindex 0561443b5f4..9d53a9bf407 100644 --- a/doc/user/group/saml_sso/img/unlink_group_saml.png +++ b/doc/user/group/saml_sso/img/unlink_group_saml.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 26893f7e31e..bd50367681e 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -2,7 +2,7 @@ type: reference, howto --- -# SAML SSO for GitLab.com Groups **[SILVER ONLY]** +# SAML SSO for GitLab.com Groups **(SILVER ONLY)** > Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0. @@ -39,6 +39,25 @@ However, users will not be prompted to log via SSO on each visit. GitLab will ch We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab-ee/issues/9152) in the future. +#### Group-managed accounts + +[Introduced in GitLab 12.1](https://gitlab.com/groups/gitlab-org/-/epics/709). + +When SSO is being enforced, groups can enable an additional level of protection by enforcing the creation of dedicated user accounts to access the group. + +Without group-managed accounts, users can link their SAML identity with any existing user on the instance. With group-managed accounts enabled, users are required to create a new, dedicated user linked to the group. The notification email address associated with the user is locked to the email address received from the configured identity provider. + +When this option is enabled: + +- All existing and new users in the group will be required to log in via the SSO URL associated with the group. +- On successfully authenticating, GitLab will prompt the user to create a new, dedicated account using the email address received from the configured identity provider. +- After the group managed account has been created, group activity will require the use of this user account. + +Since use of the group managed account requires the use of SSO, users of group managed accounts will lose access to these accounts when they are no longer able to authenticate with the connected identity provider. In the case of an offboarded employee who has been removed from your identity provider: + +- The user will be unable to access the group (their credentials will no longer work on the identity provider when prompted to SSO). +- Contributions in the group (e.g. issues, merge requests) will remain intact. + ### NameID GitLab.com uses the SAML NameID to identify users. The NameID element: @@ -71,7 +90,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. -1. Check the **Enable SAML authentication for this group** checkbox. +1. Click the **Enable SAML authentication for this group** toggle switch. 1. Click the **Save changes** button.  diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 5aef463d782..5d136ad62da 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -2,7 +2,7 @@ type: howto, reference --- -# SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]** +# SCIM provisioning using SAML SSO for Groups **(SILVER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. @@ -27,25 +27,25 @@ The following identity providers are supported: - [Group SSO](index.md) needs to be configured. - The `scim_group` feature flag must be enabled: - Run the following commands in a Rails console: + Run the following commands in a Rails console: - ```sh - # Omnibus GitLab - gitlab-rails console + ```sh + # Omnibus GitLab + gitlab-rails console - # Installation from source - cd /home/git/gitlab - sudo -u git -H bin/rails console RAILS_ENV=production - ``` + # Installation from source + cd /home/git/gitlab + sudo -u git -H bin/rails console RAILS_ENV=production + ``` - To enable SCIM for a group named `group_name`: + To enable SCIM for a group named `group_name`: - ```ruby - group = Group.find_by_full_path('group_name') - Feature.enable(:group_scim, group) - ``` + ```ruby + group = Group.find_by_full_path('group_name') + Feature.enable(:group_scim, group) + ``` -### GitLab configuration +## GitLab configuration Once [Single sign-on](index.md) has been configured, we can: @@ -55,68 +55,84 @@ Once [Single sign-on](index.md) has been configured, we can:  -## SCIM IdP configuration +## Identity Provider configuration -### Configuration on Azure +### Azure -In the [Single sign-on](index.md) configuration for the group, make sure -that the **Name identifier value** (NameID) points to a unique identifier, such -as the `user.objectid`. This will match the `extern_uid` used on GitLab. +The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM. -The GitLab app in Azure needs to be configured following -[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started). +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. -Note the following: +  + +1. Set up automatic provisioning and administrative credentials by following the + [Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation. + +During this configuration, note the following: - The `Tenant URL` and `secret token` are the ones retrieved in the [previous step](#gitlab-configuration). - Should there be any problems with the availability of GitLab or similar errors, the notification email set will get those. +- It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox. - For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. -You can then test the connection clicking on `Test Connection`. +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). + +#### Configure attribute mapping -### Synchronize Azure Active Directory users +1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure the attribute mapping. +1. Click **Delete** next to the `mail` mapping. +1. Map `userPrincipalName` to `emails[type eq "work"].value` and change it's **Matching precedence** to `2`. +1. Map `mailNickname` to `userName`. +1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, **Target attribute** to `id`, **Match objects using this attribute** to `Yes`, and **Matching precedence** to `1`. +1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, and **Target attribute** to `externalId`. +1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`. -1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure - the attribute mapping. -1. Select the unique identifier (in the example `objectId`) as the `id` and `externalId`, - and enable the `Create`, `Update`, and `Delete` actions. -1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to - `userName`. + Save your changes and you should have the following configuration: - Example configuration: +  -  + NOTE: **Note:** If you used a unique identifier **other than** `objectId`, be sure to map it instead to both `id` and `externalId`. + +1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. -1. Click on **Show advanced options > Edit attribute list for AppName**. 1. Leave the `id` as the primary and only required field. - NOTE: **Note:** - `username` should neither be primary nor required as we don't support - that field on GitLab SCIM yet. + NOTE: **Note:** + `username` should neither be primary nor required as we don't support + that field on GitLab SCIM yet. -  +  1. Save all the screens and, in the **Provisioning** step, set - the `Provisioning Status` to `ON`. + the `Provisioning Status` to `On`. + +  - 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 - the application (`Users and groups`), otherwise it will sync the whole Active Directory. + 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 + the application (`Users and groups`), otherwise, it will sync the whole Active Directory. 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. -<!-- ## Troubleshooting +## Troubleshooting + +### 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. -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +As a workaround, try an alternate mapping: -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +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. |
