Edit SAML for GitLab.com groups content

doc/user/group/saml_sso/index.md

@@ -2,19 +2,23 @@
 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.
 
-NOTE: **Note:**
-This topic is for SAML on GitLab.com Silver tier and above. For SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md).
-
 SAML on GitLab.com allows users to be automatically added to a group, and then allows those users to sign into GitLab.com. Users should already have an account on the GitLab instance, or can create one when logging in for the first time.
 
 User synchronization for GitLab.com is partially supported using [SCIM](scim_setup.md).
 
-NOTE: **Note:**
-SAML SSO for GitLab.com groups does not sync users between providers without using SCIM. If a group is not using SCIM, group Owners will still need to manage user accounts (for example, removing users when necessary).
+## Important notes
+
+Note the following:
+
+- This topic is for SAML on GitLab.com Silver tier and above. For SAML on self-managed GitLab
+  instances, see [SAML OmniAuth Provider](../../../integration/saml.md).
+- SAML SSO for GitLab.com groups requires SCIM to sync users between providers. If a
+  group is not using SCIM, group Owners will still need to manage user accounts (for example,
+  removing users when necessary).
 
 ## Configuring your Identity Provider
 
@@ -68,16 +72,17 @@ 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.
+- 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:
+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.
 
 #### Assertions
 
-When using Group Manged Accounts, the following user details need to be passed to GitLab as SAML Assertions in order for us to be able to create a user:
+When using group-managed accounts, the following user details need to be passed to GitLab as SAML
+assertions to be able to create a user.
 
 | Field           | Supported keys |
 |-----------------|----------------|
@@ -91,7 +96,7 @@ When using Group Manged Accounts, the following user details need to be passed t
 GitLab provides metadata XML that can be used to configure your Identity Provider.
 
 1. Navigate to the group and click **Settings > SAML SSO**.
-1. Copy the provided **GitLab metadata URL**
+1. Copy the provided **GitLab metadata URL**.
 1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested.
 
 ## Configuring GitLab
@@ -212,6 +217,8 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button
 
 ## Troubleshooting
 
+This section contains possible solutions for problems you might encounter.
+
 ### SAML debugging tools
 
 SAML responses are base64 encoded, so we recommend the following browser plugins to decode them on the fly:

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 GitLab.com groups **(SILVER ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10.
 
@@ -24,7 +24,7 @@ The following identity providers are supported:
 
 ## Requirements
 
-- [Group SSO](index.md) needs to be configured.
+- [Group SSO](index.md) must be configured.
 
 ## GitLab configuration
 
@@ -64,15 +64,25 @@ You can then test the connection by clicking on **Test Connection**. If the conn
 
 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 `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.
 
     - 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.
 
-1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to the unique identifier determined above, **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 the unique identifier determined above, and **Target attribute** to `externalId`.
+1. Create a new mapping:
+   1. Click **Add New Mapping**.
+   1. Set:
+      - **Source attribute** to the unique identifier determined above.
+      - **Target attribute** to `id`.
+      - **Match objects using this attribute** to `Yes`.
+      - **Matching precedence** to `1`.
+1. Create another new mapping:
+   1. Click **Add New Mapping**.
+   1. Set:
+      - **Source attribute** to the unique identifier determined above.
+      - **Target attribute** to `externalId`.
 1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`.
 
    Save your changes and you should have the following configuration:
@@ -109,6 +119,8 @@ Once synchronized, changing the field mapped to `id` and `externalId` will likel
 
 ## Troubleshooting
 
+This section contains possible solutions for problems you might encounter.
+
 ### 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.