diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-10-09 03:06:29 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-10-09 03:06:29 +0000 |
commit | d1002a9e0dfd63273564b060e6ae62ccc0578200 (patch) | |
tree | 2494b73f91c5729918d42ce7917cbaf1c3c45820 /doc | |
parent | 869182cab0867d582e469f329a6f58d13f877683 (diff) | |
download | gitlab-ce-d1002a9e0dfd63273564b060e6ae62ccc0578200.tar.gz |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/user/group/saml_sso/index.md | 45 |
1 files changed, 36 insertions, 9 deletions
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index a2ba616d818..fecf543af5f 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -153,14 +153,41 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | 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. | -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### SAML debugging tools -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +SAML responses are base64 encoded, so we recommend the following browser plugins to decode them on the fly: + +- [SAML tracer for Firefox](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) +- [Chrome SAML Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace?hl=en) + +Specific attention should be paid to: + +- The [NameID](#nameid), which we use to identify which user is signing in. If the user has previously signed in, this [must match the value we have stored](#verifying-nameid). +- The presence of a `X509Certificate`, which we require to verify the response signature. +- The `SubjectConfirmation` and `Conditions`, which can cause errors if misconfigured. + +### Verifying NameID + +In troubleshooting the Group SAML setup, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [https://gitlab.com/api/v4/user](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. + +This can then be compared to the [NameID](#nameid) being sent by the Identity Provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match in order to identify users. + +### Message: "SAML authentication failed: Extern uid has already been taken" + +This error suggests you are signed in as a GitLab user but have already linked your SAML identity to a different GitLab user. Sign out and then try to sign in again using the SSO SAML link, which should log you into GitLab with the linked user account. + +If you do not wish to use that GitLab user with the SAML login, you can [unlink the GitLab account from the group's SAML](#unlinking-accounts). + +### Message: "SAML authentication failed: User has already been taken" + +The user you are signed in with already has SAML linked to a different identity. This might mean you've attempted to link multiple SAML identities to the same user for a given Identity Provider. This could also be a symptom of the Identity Provider returning an inconsistent [NameID](#nameid). + +To change which identity you sign in with, you can [unlink the previous SAML identity](#unlinking-accounts) from this GitLab account. + +### Message: "SAML authentication failed: Extern uid has already been taken, User has already been taken" + +Getting both of these errors at the same time suggests the NameID capitalization provided by the Identity Provider didn't exactly match the previous value for that user. + +This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this will cause group membership and Todos to be lost. |