Merge branch 'omniauth-security-documentation' into 'master'

Add a security section to the SAML documentation

Closes #198437

See merge request gitlab-org/gitlab!25276

doc/integration/saml.md

@@ -67,6 +67,8 @@ in your SAML IdP:
    auto_link_saml_user: true
    ```
 
+1. Ensure that the SAML [`NameID`](../user/group/saml_sso/index.md#nameid) and email address are fixed for each user, as described in the section on [Security](#security). Otherwise, your users will be able to sign in as other authorized users.
+
 1. Add the provider configuration:
 
    For Omnibus package:
@@ -430,6 +432,8 @@ args: {
 }
 ```
 
+Make sure you read the [Security](#security) section before changing this value.
+
 ## Response signature validation (required)
 
 We require Identity Providers to sign SAML responses to ensure that the assertions are
@@ -544,6 +548,17 @@ args: {
 
 GitLab will sign the request with the provided private key. GitLab will include the configured public x500 certificate in the metadata for your Identity Provider to validate the signature of the received request with. For more information on this option, see the [Ruby SAML gem documentation](https://github.com/onelogin/ruby-saml/tree/v1.7.0). The Ruby SAML gem is used by the [OmniAuth SAML gem](https://github.com/omniauth/omniauth-saml) to implement the client side of the SAML authentication.
 
+## Security
+
+Avoid user control of the following attributes:
+
+- [`*NameID*`](../user/group/saml_sso/index.md#nameid)
+- *Email* when used with `omniauth_auto_link_saml_user`
+
+These attributes define the SAML user. If users can change these attributes, they can impersonate others.
+
+Refer to the documentation for your [SAML Identity Provider](../user/group/saml_sso/index.md#providers) for information on how to fix these attributes.
+
 ## Troubleshooting
 
 ### GitLab+SAML Testing Environments