1 files changed, 23 insertions, 4 deletions
diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md
index 7dafd2c5075..f8075e62ecc 100644
--- a/doc/user/group/saml_sso/troubleshooting.md
+++ b/doc/user/group/saml_sso/troubleshooting.md
@@ -52,7 +52,7 @@ You can use one of the following to troubleshoot SAML:
 - A [quick start guide to start a Docker container](../../../administration/troubleshooting/test_environments.md#saml)
   with a plug and play SAML 2.0 identity provider if you only require a SAML provider.
 - A local environment by
-  [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#configuring-group-saml-on-a-self-managed-gitlab-instance).
+  [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#group-saml-on-a-self-managed-gitlab-instance).
 
 ## Verify configuration
 
@@ -96,7 +96,14 @@ In these cases, use one of the [SAML debugging tools](#saml-debugging-tools), or
 a group owner can get a copy of the SAML response from when they select
 the "Verify SAML Configuration" button on the group SSO Settings page.
 
-Use a base64 decoder to see a human-readable version of the SAML response.
+Use a base64 decoder to see a human-readable version of the SAML response. To avoid pasting the SAML response online to decode it, you can use your
+browser's console in the developers tools:
+
+```javascript
+atob(decodeURI("<paste_SAML_response_here>"))
+```
+
+You should get the SAML response in XML format as output.
 
 ## Configuration errors
 
@@ -138,7 +145,7 @@ Make sure this information is provided.
 Another issue that can result in this error is when the correct information is being sent by
 the identity provider, but the attributes don't match the names in the OmniAuth `info` hash. In this case,
 you must set `attribute_statements` in the SAML configuration to
-[map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](../../../integration/saml.md#attribute_statements).
+[map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](../../../integration/saml.md#map-saml-response-attribute-names).
 
 ## User sign in banner error messages
 
@@ -221,7 +228,7 @@ If all users are receiving a `404` when attempting to sign in using SAML, confir
 [there is an active subscription](../../../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) being used in this SAML SSO namespace.
 
 If you receive a `404` during setup when using "verify configuration", make sure you have used the correct
-[SHA-1 generated fingerprint](../../../integration/saml.md#notes-on-configuring-your-identity-provider).
+[SHA-1 generated fingerprint](../../../integration/saml.md#configure-saml-on-your-idp).
 
 If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#configure-your-identity-provider), they may see a 404.
 As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users.
@@ -262,3 +269,15 @@ Pay particular attention to the following 403 errors:
 
 - `app_not_configured`
 - `app_not_configured_for_user`
+
+## SAML Name ID and email address do not match your user account **(PREMIUM SAAS)**
+
+If users encounter the error `SAML Name ID and email address do not match your user account. Contact an administrator.`
+this means:
+
+- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value.
+- Either the SAML response did not include an email address or the email address did not match the user's GitLab email address.
+
+A GitLab group Owner can use the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`.
+The `extern_uid` value must match the Name ID value sent by the SAML identity provider (IdP). Depending on the IdP configuration
+this may be a generated unique ID, an email address, or other value.