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

Docs: Group SAML Add change ID warnings

Closes #33706

See merge request gitlab-org/gitlab!18831

doc/user/group/saml_sso/index.md

@@ -26,6 +26,23 @@ SAML SSO for GitLab.com groups does not sync users between providers without usi
 
 ![Issuer and callback for configuring SAML identity provider with GitLab.com](img/group_saml_configuration_information.png)
 
+### NameID
+
+GitLab.com uses the SAML NameID to identify users. The NameID element:
+
+- Is a required field in the SAML response.
+- 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.
+
+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.
+
+#### NameID Format
+
+We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format.
+
 ### SSO enforcement
 
 SSO enforcement was:
@@ -58,21 +75,12 @@ Since use of the group managed account requires the use of SSO, users of group m
 - 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.
 
-### NameID
-
-GitLab.com uses the SAML NameID to identify users. The NameID element:
-
-- Is a required field in the SAML response.
-- 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.
-
-We strongly recommend against using Email as the NameID as it is hard to guarantee it will never change, for example when a person's name changes. Similarly usernames should be avoided if possible.
+#### Assertions
 
-### 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:
 
 | Field           | Supported keys |
-|-------|----------------|
+|-----------------|----------------|
 | Email (required)| `email`, `mail` |
 | Full Name       | `name` |
 | First Name      | `first_name`, `firstname`, `firstName` |

doc/user/group/saml_sso/scim_setup.md

@@ -66,8 +66,13 @@ 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 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. 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. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`.
 
    Save your changes and you should have the following configuration:
@@ -99,6 +104,9 @@ You can then test the connection by clicking on **Test Connection**. If the conn
 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.
 
+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.
+
 ## Troubleshooting
 
 ### Testing Azure connection: invalid credentials