Merge branch 'alvin-master-patch-33889' into 'master'

Add user auth flow to LDAP docs

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103146



Merged-by: Evan Read <eread@gitlab.com>
Co-authored-by: Alvin Gounder <agounder@gitlab.com>

doc/administration/auth/ldap/index.md

@@ -507,6 +507,18 @@ If initially your LDAP configuration looked like:
 
 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
+## Updating LDAP DN and email
+
+When an LDAP user is created in GitLab, their LDAP distinguished name (DN) is linked to their GitLab account as an identifier.
+
+When a user tries to sign in with LDAP, GitLab tries to find the user using the DN saved on that user's account.
+
+- If GitLab finds the user by the DN, and the user's email matches the GitLab account's email, GitLab does not take any further action.
+- If GitLab finds the user by the DN and the user's email has changed, GitLab updates its record of the user's email to match the one in LDAP.
+- If GitLab cannot find a user by their DN, it tries to find the user by their email. If GitLab finds the user by their email, GitLab updates the DN stored in the user's GitLab account. Both values now match the information stored in LDAP.
+
+If both the DN **and** the email address have changed, see the [user DN and email have changed](ldap-troubleshooting.md#user-dn-and-email-have-changed) section of our documentation.
+
 ## Disable anonymous LDAP authentication
 
 GitLab doesn't support TLS client authentication. Complete these steps on your LDAP server.
@@ -543,7 +555,7 @@ Updating user email addresses must be done on the LDAP server that manages the u
 
 The updated user's previous email address becomes the secondary email address to preserve that user's commit history.
 
-You can find more details on the expected behavior of user updates in our [LDAP troubleshooting section](ldap-troubleshooting.md#user-dn-orand-email-have-changed).
+You can find more details on the expected behavior of user updates in our [LDAP troubleshooting section](ldap-troubleshooting.md#user-dn-and-email-have-changed).
 
 ## Google Secure LDAP
 

doc/administration/auth/ldap/ldap-troubleshooting.md

@@ -541,7 +541,7 @@ Usually this is not a cause for concern.
 
 If you think a particular user should already exist in GitLab, but you're seeing
 this entry, it could be due to a mismatched DN stored in GitLab. See
-[User DN and/or email have changed](#user-dn-orand-email-have-changed) to update the user's LDAP identity.
+[User DN and email have changed](#user-dn-and-email-have-changed) to update the user's LDAP identity.
 
 ```shell
 User with DN `uid=john0,ou=people,dc=example,dc=com` should have access
@@ -624,23 +624,13 @@ does not do this:
 1. Wait until LDAP group synchronization has finished running.
 1. Remove the user from the LDAP group.
 
-### User DN or/and email have changed
+### User DN and email have changed
 
-When an LDAP user is created in GitLab, their LDAP DN is stored for later reference.
-
-If GitLab cannot find a user by their DN, it falls back
-to finding the user by their email. If the lookup is successful, GitLab
-updates the stored DN to the new value so both values now match what's in
-LDAP.
-
-If the email has changed and the DN has not, GitLab finds the user with
-the DN and updates its own record of the user's email to match the one in LDAP.
-
-However, if the primary email _and_ the DN change in LDAP, then GitLab
-has no way of identifying the correct LDAP record of the user and, as a
-result, the user is blocked. To rectify this, the user's existing
-profile must be updated with at least one of the new values (primary
-email or DN) so the LDAP record can be found.
+If both the primary email **and** the DN change in LDAP, GitLab has
+no way of identifying the correct LDAP record of a user and, as a
+result, blocks that user. To fix this, update the user's existing
+GitLab profile with at least one of the new primary email or DN values
+so GitLab can find the LDAP record.
 
 The following script updates the emails for all provided users so they
 aren't blocked or unable to access their accounts.