diff options
Diffstat (limited to 'doc/user/group/saml_sso/index.md')
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 59 |
1 files changed, 46 insertions, 13 deletions
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 402007b85b2..7443be250bb 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -14,6 +14,10 @@ This page describes SAML for groups. For instance-wide SAML on self-managed GitL SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. +INFO: +Use your own SAML authentication to log in to [GitLab.com](http://gitlab.com/). +[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-saml-sso-docs). + User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group automatically. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. @@ -29,14 +33,16 @@ If required, you can find [a glossary of common terms](../../../integration/saml 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](#assertions) at minimum containing - the user's email address. +1. Configure the required [user attributes](#user-attributes), ensuring you include the user's email address. 1. While the default is enabled for most SAML providers, please ensure the app is set to have service provider initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).  +If your account is the only owner in the group after SAML is set up, you can't unlink the account. To [unlink the account](#unlinking-accounts), +set up another user as a group owner. + ### NameID GitLab.com uses the SAML NameID to identify users. The NameID element: @@ -60,15 +66,16 @@ Once users have signed into GitLab using the SSO SAML setup, changing the `NameI We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. Most NameID formats can be used, except `Transient` due to the temporary nature of this format. -### Assertions +### User attributes + +To create users with the correct information for improved [user access and management](#user-access-and-management), +the user's details must be passed to GitLab as attributes in the SAML assertion. At a minimum, the user's email address +must be specified as an attribute named `email` or `mail`. -For users to be created with the right information with the improved [user access and management](#user-access-and-management), -the user details need to be passed to GitLab as SAML assertions. +GitLab.com supports the following attributes: -At a minimum, the user's email address *must* be specified as an assertion named `email` or `mail`. -See [the assertions list](../../../integration/saml.md#assertions) for other available claims. -In addition to the attributes in the linked assertions list, GitLab.com supports `username` -and `nickname` attributes. +- `username` or `nickname`. We recommend you configure only one of these. +- The [attributes also available](../../../integration/saml.md#assertions) to self-managed GitLab instances. ### Metadata configuration @@ -104,7 +111,7 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. -With this option enabled, users (except owners) must go through your group's GitLab single sign-on URL if they wish to access group resources through the UI. Users can't be manually added as members. +With this option enabled, users (except users with the Owner role) must access GitLab using your group GitLab single sign-on URL to access group resources. Users added manually as members can't access group resources. SSO enforcement does not affect sign in or access to any resources outside of the group. Users can view which groups and projects they are a member of without SSO sign in. @@ -119,7 +126,7 @@ SSO has the following effects when enabled: - For groups, users can't share a project in the group outside the top-level group, even if the project is forked. - For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or - pull from a GitLab repository. + pull from a GitLab repository. - Credentials that are not tied to regular users (for example, access tokens and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> @@ -342,6 +349,11 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` +Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` +are not accepted as a source of groups. +See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) +for examples on configuring the required attribute name in the SAML identity provider's settings. + NOTE: The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). @@ -362,7 +374,7 @@ To link the SAML groups from the `saml:AttributeStatement` example above: If a user is a member of multiple SAML groups mapped to the same GitLab group, the user gets the highest access level from the groups. For example, if one group is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` -access. +access. Users granted: @@ -374,7 +386,10 @@ Users granted: ### Automatic member removal After a group sync, users who are not members of a mapped SAML group are removed from -the GitLab group. +the GitLab group. Even if SSO authentication is successful, if an existing user is not a member of any of the configured groups: + +- They get an "unauthorized" message if they try to view the group. +- All of their permissions to subgroups and projects are also removed. For example, in the following diagram: @@ -475,6 +490,24 @@ Specific attention should be paid to: - The presence of a `X509Certificate`, which we require to verify the response signature. - The `SubjectConfirmation` and `Conditions`, which can cause errors if misconfigured. +#### Generate a SAML Response + +SAML Responses can be used to preview the attribute names and values sent in the assertions list while attempting to sign in using an IdP. + +To generate a SAML Response: + +1. Install either: + - [SAML Chrome Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) for Chrome. + - [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. +1. Open a new browser tab. +1. Open the SAML tracer console: + - Chrome: Right click on the page, select **Inspect**, then click on the SAML tab in the opened developer console. + - Firefox: Select the SAML-tracer icon located on the browser toolbar. +1. Go to the GitLab single sign-on URL for the group in the same browser tab with the SAML tracer open. +1. Select **Authorize** or attempt to log in. A SAML response is displayed in the tracer console that resembles this + [example SAML response](#example-saml-response). +1. Within the SAML tracer, select the **Export** icon to save the response in JSON format. + ### Verifying configuration For convenience, we've included some [example resources](../../../administration/troubleshooting/group_saml_scim.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. |