Merge branch 'patch-250' into 'master'

Changes to SCIM identity documentation

See merge request gitlab-org/gitlab!44493

doc/user/group/saml_sso/scim_setup.md

@@ -17,7 +17,7 @@ GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protoc
 
 ## Features
 
-Currently, the following actions are available:
+The following actions are available:
 
 - Create users
 - Update users (Azure only)
@@ -51,7 +51,7 @@ Once [Group Single Sign-On](index.md) has been configured, we can:
 
 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/view-applications-portal) 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.
+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 matches the `extern_uid` used on GitLab.
 
    ![Name identifier value mapping](img/scim_name_identifier_mapping.png)
 
@@ -63,7 +63,7 @@ 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.
+  errors, the notification email set gets 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.
 
@@ -75,10 +75,10 @@ You can then test the connection by clicking on **Test Connection**. If the conn
 1. Click **Delete** next to the `mail` mapping.
 1. Map `userPrincipalName` to `emails[type eq "work"].value` and change its **Matching precedence** to `2`.
 1. Map `mailNickname` to `userName`.
-1. Determine how GitLab will uniquely identify users.
+1. Determine how GitLab uniquely identifies 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.
+    - If you already have users with SAML linked then use the `Name ID` value from the [SAML configuration](#azure). Using a different value may cause duplicate users and prevent users from accessing the GitLab group.
 
 1. Create a new mapping:
    1. Click **Add New Mapping**.
@@ -110,14 +110,14 @@ You can then test the connection by clicking on **Test Connection**. If the conn
 
    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.
+   `Sync only assigned users and groups` only syncs the users assigned to
+   the application (`Users and groups`), otherwise, it syncs the whole Active Directory.
 
-Once enabled, the synchronization details and any errors will appear on the
+Once enabled, the synchronization details and any errors appears on the
 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.
+Once synchronized, changing the field mapped to `id` and `externalId` may cause a number of errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group.
 
 ### Okta configuration steps