Add latest changes from gitlab-org/gitlab@13-7-stable-eev13.7.0-rc42

5 files changed, 134 insertions, 34 deletions

diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md
index 50f062bafa9..15dd91bece2 100644
--- a/doc/user/group/saml_sso/group_managed_accounts.md
+++ b/doc/user/group/saml_sso/group_managed_accounts.md
@@ -2,12 +2,12 @@
 type: reference, howto
 stage: Manage
 group: Access
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # Group Managed Accounts **(PREMIUM)**
 
-CAUTION: **Caution:**
+WARNING:
 This [Closed Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature is being re-evaluated in favor of a different
 [identity model](https://gitlab.com/groups/gitlab-org/-/epics/4345) that does not require separate accounts.
 We recommend that group administrators who haven't yet implemented this feature wait for
diff --git a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png
new file mode 100644
index 00000000000..c1980b24a6d
--- /dev/null
+++ b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png
diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png
new file mode 100644
index 00000000000..c78b77b8fcf
--- /dev/null
+++ b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index 94d2c9afb24..62431747911 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -2,7 +2,7 @@
 type: reference, howto
 stage: Manage
 group: Access
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # SAML SSO for GitLab.com groups **(SILVER ONLY)**
@@ -38,13 +38,15 @@ GitLab.com uses the SAML NameID to identify users. The NameID element:
 - Must be unique to each user.
 - Must be a persistent value that will never change, such as a randomly generated unique user ID.
 - Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case.
-- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in.
+- Should not be an email address or username. We strongly recommend against these as it's hard to
+  guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are
+  also case-insensitive, which can result in users being unable to sign in.
 
 The relevant field name and recommended value for supported providers are in the [provider specific notes](#providers).
 appropriate corresponding field.
 
-CAUTION: **Warning:**
-Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group.
+WARNING:
+Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group.
 
 #### NameID Format
 
@@ -56,11 +58,11 @@ GitLab provides metadata XML that can be used to configure your Identity Provide
 
 1. Navigate to the group and click **Settings > SAML SSO**.
 1. Copy the provided **GitLab metadata URL**.
-1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested.
+1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested.
 
 ## Configuring GitLab
 
-Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication:
+After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication:
 
 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.
@@ -71,7 +73,7 @@ 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_v13_3.png)
 
-NOTE: **Note:**
+NOTE:
 Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm.
 
 ### SSO enforcement
@@ -79,18 +81,18 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a
 - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8.
 - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI.
 
-With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL.
+With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL.
 
-However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired.
+However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired.
 You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out).
 
 We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152).
 
-When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked.
+When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked.
 
 ## Providers
 
-NOTE: **Note:**
+NOTE:
 GitLab is unable to provide support for IdPs that are not listed here.
 
 | Provider | Documentation |
@@ -190,31 +192,77 @@ If the information you need isn't listed above you may wish to check our [troubl
 
 ## User access and management
 
+> [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7.
+
 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 will need an account that's configured with one of the following:
+When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following:
 
-- [SCIM](scim_setup.md).
-- [Group-managed accounts](group_managed_accounts.md).
-- A GitLab.com account.
+- Find an existing user with a matching SAML identity. This would mean the user either had their account created by [SCIM](scim_setup.md) or they have previously signed in with the group's SAML IdP.
+- If there is no conflicting user with the same email address, create a new account automatically.
+- If there is a conflicting user with the same email address, redirect the user to the sign-in page to:
+  - Create a new account with another email address.
+  - Sign-in to their existing account to link the SAML identity.
 
 ### Linking SAML to your existing GitLab.com account
 
 To link SAML to your existing GitLab.com account:
 
 1. Sign in to your GitLab.com account.
-1. Locate and visit the **GitLab single sign-on URL** for the group you are signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider.
+1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider.
 1. Click **Authorize**.
 1. Enter your credentials on the Identity Provider if prompted.
-1. You will be redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com.
+1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com.
 
-On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you will be redirected to sign in through the identity provider.
+On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider.
 
 ### Signing in to GitLab.com with SAML
 
 1. Sign in to your identity provider.
 1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider).
-1. You will be signed in to GitLab.com and redirected to the group.
+1. You are then signed in to GitLab.com and redirected to the group.
+
+### Configure user settings from SAML response
+
+[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7.
+
+GitLab allows setting certain user attributes based on values from the SAML response.
+This affects users created on first sign-in via Group SAML. Existing users'
+attributes are not affected regardless of the values sent in the SAML response.
+
+#### Supported user attributes
+
+- `can_create_group` - 'true' or 'false' to indicate whether the user can create
+  new groups. Default is `true`.
+- `projects_limit` - The total number of personal projects a user can create.
+  A value of `0` means the user cannot create new projects in their personal
+  namespace. Default is `10000`.
+
+#### Example SAML response
+
+You can find SAML responses in the developer tools or console of your browser,
+in base64-encoded format. Use the base64 decoding tool of your choice to
+convert the information to XML. An example SAML response is shown here.
+
+```xml
+   <saml2:AttributeStatement>
+      <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
+         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue>
+      </saml2:Attribute>
+      <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
+         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue>
+      </saml2:Attribute>
+      <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
+         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue>
+      </saml2:Attribute>
+      <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
+         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue>
+      </saml2:Attribute>
+      <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
+         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue>
+      </saml2:Attribute>
+   </saml2:AttributeStatement>
+```
 
 ### Role
 
@@ -238,10 +286,53 @@ Users can unlink SAML for a group from their profile page. This can be helpful i
 - You no longer want a group to be able to sign you in to GitLab.com.
 - Your SAML NameID has changed and so GitLab can no longer find your user.
 
-For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**:
+WARNING:
+Unlinking an account removes all roles assigned to that user within the group.
+If a user relinks their account, roles need to be reassigned.
+
+For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:
 
 ![Unlink Group SAML](img/unlink_group_saml.png)
 
+## Group Sync
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg).
+
+When the SAML response includes a user and their group memberships from the SAML identity provider,
+GitLab uses that information to automatically manage that user's GitLab group memberships.
+
+Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following:
+
+```xml
+<saml:AttributeStatement>
+  <saml:Attribute Name="Groups">
+    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
+    <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue>
+  </saml:Attribute>
+</saml:AttributeStatement>
+```
+
+When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users
+see a new menu item in group **Settings -> SAML Group Links**. Each group (parent or subgroup) can specify
+one or more group links to map a SAML identity provider group name to a GitLab access level.
+
+![SAML Group Links navigation](img/saml_group_links_nav_v13_6.png)
+
+To link the SAML `Freelancers` group in the attribute statement example above:
+
+1. Enter `Freelancers` in the `SAML Group Name` field.
+1. Choose the desired `Access Level`.
+1. **Save** the group link.
+1. Repeat to add additional group links if desired.
+
+![SAML Group Links](img/saml_group_links_v13_6.png)
+
+If a user is a member of multiple SAML groups mapped to the same GitLab group,
+the user gets the highest access level from the groups. For example, if one group
+is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer`
+access.
+
 ## Glossary
 
 | Term | Description |
@@ -250,7 +341,7 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button
 | Service Provider | SAML considers GitLab to be a service provider. |
 | Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. |
 | SSO | Single Sign On. |
-| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. |
+| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. |
 | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". |
 | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. |
 
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md
index 7c089a289c6..40c036e1fc0 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
 stage: Manage
 group: Access
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)**
@@ -13,7 +13,7 @@ System for Cross-domain Identity Management (SCIM), is an open standard that ena
 automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of
 that group is synchronized between GitLab and the identity provider.
 
-GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644).
+The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644).
 
 ## Features
 
@@ -92,14 +92,14 @@ You can then test the connection by clicking on **Test Connection**. If the conn
 
 1. Save your changes. For reference, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory).
 
-   NOTE: **Note:**
+   NOTE:
    If you used a unique identifier **other than** `objectId`, be sure to map it to `externalId`.
 
 1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**.
 
 1. Ensure the `id` is the primary and required field, and `externalId` is also required.
 
-   NOTE: **Note:**
+   NOTE:
    `username` should neither be primary nor required as we don't support
    that field on GitLab SCIM yet.
 
@@ -108,15 +108,15 @@ You can then test the connection by clicking on **Test Connection**. If the conn
 
    ![Provisioning status toggle switch](img/scim_provisioning_status.png)
 
-   NOTE: **Note:**
+   NOTE:
    You can control what is actually synced by selecting the `Scope`. For example,
    `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 appears on the
-bottom of the **Provisioning** screen, together with a link to the audit logs.
+bottom of the **Provisioning** screen, together with a link to the audit events.
 
-CAUTION: **Warning:**
+WARNING:
 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
@@ -132,7 +132,7 @@ configuration. Otherwise, the Okta SCIM app may not work properly.
 1. If you see an **Admin** button in the top right, click the button. This will
    ensure you are in the Admin area.
 
-   TIP: **Tip:**
+   NOTE:
    If you're using the Developer Console, click **Developer Console** in the top
    bar and select **Classic UI**. Otherwise, you may not see the buttons described
    in the following steps:
@@ -194,7 +194,7 @@ provider or users list for the specific app.
 
 Upon the next sync, the user is deprovisioned, which means that the user is removed from the group.
 
-NOTE: **Note:**
+NOTE:
 Deprovisioning does not delete the user account.
 
 ```mermaid
@@ -240,7 +240,7 @@ To see how the `external_uid` compares to the value returned as the SAML NameId,
 
 Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field.
 
-If GitLab's `externalId` doesn't match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change.
+If the GitLab `externalId` doesn't match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change.
 
 Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`.
 We use these IDs to look up users. If the identity provider does not know the current values for these fields,
@@ -262,6 +262,15 @@ Individual users can follow the instructions in the ["SAML authentication failed
 
 Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup).
 
+### The SCIM app is throwing `"User has already been taken","status":409` error message
+
+Changing the SAML or SCIM configuration or provider can cause the following problems:
+
+| Problem                                                                      | Solution           |
+|------------------------------------------------------------------------------|--------------------|
+| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). |
+| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-saml-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-saml-user) to update the SCIM `id` for the user on GitLab.com. |
+
 ### Azure
 
 #### How do I verify my SCIM configuration is correct?
@@ -283,7 +292,7 @@ When testing the connection, you may encounter an error: **You appear to have en
 
 #### (Field) can't be blank sync error
 
-When checking the Audit Logs for the Provisioning, you can sometimes see the
+When checking the Audit Events 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.