Merge branch 'master' of gitlab_gitlab:gitlab-org/gitlab-cerunner-metrics-extractor

1 files changed, 67 insertions, 51 deletions

diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md
index 2d408766db8..5d136ad62da 100644
--- a/doc/user/group/saml_sso/scim_setup.md
+++ b/doc/user/group/saml_sso/scim_setup.md
@@ -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 token configuration](img/scim_token.png)
 
-## 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:
+   ![Name identifier value mapping](img/scim_name_identifier_mapping.png)
+
+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:
+   ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
 
-    ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
+   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.
 
-    ![Azure's attribute advanced configuration](img/scim_advanced.png)
+   ![Azure's attribute advanced configuration](img/scim_advanced.png)
 
 1. Save all the screens and, in the **Provisioning** step, set
-   the `Provisioning Status` to `ON`.
+   the `Provisioning Status` to `On`.
+
+   ![Provisioning status toggle switch](img/scim_provisioning_status.png)
 
-    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.