Merge branch 'docs-saml-userflow' into 'master'

Docs: Add and clarify user access management

See merge request gitlab-org/gitlab!22256

doc/user/group/saml_sso/index.md

@@ -6,7 +6,9 @@ type: reference, howto
 
 > Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0.
 
-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.
+SAML on GitLab.com allows users to be added to a group. Those users can then sign in to GitLab.com. If such users don't already have an account on the GitLab instance, they can create one when signing in for the first time.
+
+If you follow our guidance to automate user provisioning using [SCIM](scim_setup.md) or [group managed accounts](#group-managed-accounts), you do not need to create such accounts manually.
 
 User synchronization for GitLab.com is partially supported using [SCIM](scim_setup.md).
 
@@ -91,7 +93,7 @@ assertions to be able to create a user.
 | First Name      | `first_name`, `firstname`, `firstName` |
 | Last Name       | `last_name`, `lastname`, `lastName` |
 
-## Metadata configuration
+### Metadata configuration
 
 GitLab provides metadata XML that can be used to configure your Identity Provider.
 
@@ -111,6 +113,37 @@ Once you've set up your identity provider to work with GitLab, you'll need to co
 
 ![Group SAML Settings for GitLab.com](img/group_saml_settings.png)
 
+## User access and management
+
+Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup).
+
+When a user tries to sign in with Group SSO, they'll need an account that's configured with one of the following:
+
+- [SCIM](scim_setup.md).
+- [Group-managed accounts](#group-managed-accounts).
+- A GitLab.com account.
+
+1. Click on the GitLab app in the identity provider's dashboard, or visit the Group's GitLab SSO URL.
+1. Sign in to GitLab.com. The next time you connect on the same browser, you won't have to sign in again provided the active session has not expired.
+1. Click on the **Authorize** button.
+
+On subsequent visits, users can access the group through the identify provider's dashboard or by visiting links directly. With the **enforce SSO** option turned on, users will be redirected to log in through the identity provider as required.
+
+### Role
+
+Upon first sign in, a new user is added to the parent group with the Guest role. Existing members with an appropriate role will have to elevate users to a higher role where relevant.
+
+If a user is already a member of the group, linking the SAML identity does not change their role.
+
+### Blocking access
+
+To rescind access to the group:
+
+1. Remove the user from the identity provider or users list for the specific app.
+1. Remove the user from the GitLab.com group.
+
+Even when **enforce SSO** is active, we recommend removing the user from the group. Otherwise, the user can sign in through the identity provider if they do not have an active session.
+
 ## Providers
 
 NOTE: **Note:** GitLab is unable to provide support for IdPs that are not listed here.

doc/user/group/saml_sso/scim_setup.md

@@ -117,6 +117,28 @@ 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.
 
+## 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).
+
 ## Troubleshooting
 
 This section contains possible solutions for problems you might encounter.