diff options
Diffstat (limited to 'doc/user/group/saml_sso/index.md')
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 47 |
1 files changed, 38 insertions, 9 deletions
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 0ce92eac1a3..10344c60e7e 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# SAML SSO for GitLab.com groups **(SILVER ONLY)** +# SAML SSO for GitLab.com groups **(PREMIUM SAAS)** > Introduced in GitLab 11.0. @@ -26,6 +26,7 @@ SAML SSO is not supported at the subgroup level. 1. Configure your SAML server using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. 1. Configure [required assertions](group_managed_accounts.md#assertions) if using [Group Managed Accounts](group_managed_accounts.md). +1. While the default is enabled for most SAML providers, please ensure the app is set to have [Service Provider](#glossary) initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).  @@ -110,7 +111,8 @@ When [configuring your identify provider](#configuring-your-identity-provider), ### Azure setup notes <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regards to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). +For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regard to +objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). | GitLab Setting | Azure Field | |--------------|----------------| @@ -280,7 +282,7 @@ If a user is already a member of the group, linking the SAML identity does not c To rescind access to the group, perform the following steps, in order: -1. Remove the user from the user datastore on the identity provider or the list of users on the specific app. +1. Remove the user from the user data store on the identity provider or the list of users on the specific app. 1. Remove the user from the GitLab.com group. ### Unlinking accounts @@ -292,7 +294,7 @@ Users can unlink SAML for a group from their profile page. This can be helpful i WARNING: Unlinking an account removes all roles assigned to that user within the group. -If a user relinks their account, roles need to be reassigned. +If a user re-links their account, roles need to be reassigned. For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**: @@ -341,9 +343,9 @@ access. | Term | Description | |------|-------------| -| Identity Provider | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. | +| Identity Provider | The service which manages your user identities such as ADFS, Okta, OneLogin, or Ping Identity. | | Service Provider | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | SSO | Single Sign On. | | Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | @@ -376,7 +378,7 @@ For convenience, we've included some [example resources](../../../administration ### 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. +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. Similarly, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. @@ -387,7 +389,7 @@ This can then be compared to the [NameID](#nameid) being sent by the Identity Pr If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users. -### Message: "SAML authentication failed: Extern uid has already been taken" +### 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. @@ -408,7 +410,7 @@ Here are possible causes and solutions: |------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). | -### Message: "SAML authentication failed: Extern uid has already been taken, User has already been taken" +### 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. @@ -418,6 +420,11 @@ This can be prevented by configuring the [NameID](#nameid) to return a consisten Ensure that the user who is trying to link their GitLab account has been added as a user within the identity provider's SAML app. +Alternatively, the SAML response may be missing the `InResponseTo` attribute in the +`samlp:Response` tag, which is [expected by the SAML gem](https://github.com/onelogin/ruby-saml/blob/9f710c5028b069bfab4b9e2b66891e0549765af5/lib/onelogin/ruby-saml/response.rb#L307-L316). +The [Identity Provider](#glossary) administrator should ensure that the login is +initiated by the Service Provider (typically GitLab) and not the Identity Provider. + ### Stuck in a login "loop" Ensure that the **GitLab single sign-on URL** has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. @@ -446,3 +453,25 @@ However, self-managed GitLab instances use a configuration file that supports mo Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/spec/fixtures/saml/response.xml). + +### Searching Rails log + +With access to the rails log or `production_json.log` (available only to GitLab team members for GitLab.com), +you should be able to find the base64 encoded SAML response by searching with the following filters: + +- `json.meta.caller_id`: `Groups::OmniauthCallbacksController#group_saml` +- `json.meta.user` or `json.username`: `username` +- `json.method`: `POST` +- `json.path`: `/groups/GROUP-PATH/-/saml/callback` + +In a relevant log entry, the `json.params` should provide a valid response with: + +- `"key": "SAMLResponse"` and the `"value": (full SAML response)`, +- `"key": "RelayState"` with `"value": "/group-path"`, and +- `"key": "group_id"` with `"value": "group-path"`. + +In some cases, if the SAML response is lengthy, you may receive a `"key": "truncated"` with `"value":"..."`. +In these cases, please ask a group owner for 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. |