diff options
Diffstat (limited to 'doc/user/group/saml_sso/index.md')
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 36 |
1 files changed, 22 insertions, 14 deletions
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 20ff4a201f5..14c4447c5c6 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -21,7 +21,7 @@ SAML SSO is only configurable at the top-level group. If required, you can find [a glossary of common terms](../../../integration/saml.md#glossary-of-common-terms). -## Configuring your identity provider +## Configure your identity provider 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. @@ -32,7 +32,7 @@ If required, you can find [a glossary of common terms](../../../integration/saml 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). +1. Once the identity provider is set up, move on to [configuring GitLab](#configure-gitlab).  @@ -82,7 +82,7 @@ GitLab provides metadata XML that can be used to configure your identity provide 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. -## Configuring GitLab +## Configure GitLab After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: @@ -108,7 +108,9 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [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. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. -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. +With this option enabled, users must access GitLab using your group GitLab single sign-on URL to access group resources. +Users can't be added as new members manually. +Users with the Owner role can use the standard sign in process to make necessary changes to top-level group settings. 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. @@ -116,7 +118,7 @@ However, users are not prompted to sign in through SSO on each visit. GitLab che has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab prompts the user to sign in again through SSO. -We intend to add a similar SSO requirement for [API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/297389). +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. SSO has the following effects when enabled: @@ -127,7 +129,6 @@ SSO has the following effects when enabled: - Git activity originating from CI/CD jobs do not have the SSO check enforced. - 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 --> When SSO is enforced, users are not immediately revoked. If the user: @@ -139,7 +140,7 @@ When SSO is enforced, users are not immediately revoked. If the user: The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. -When [configuring your identity provider](#configuring-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. +When [configuring your identity provider](#configure-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. For providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#notes-on-configuring-your-identity-provider) for additional guidance on information your identity provider may require. @@ -293,12 +294,16 @@ convert the information to XML. An example SAML response is shown here. ### Role -Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a 'Default membership role' other than 'Guest'. To do so, [configure the SAML SSO for the group](#configuring-gitlab). That role becomes the starting access level of all users added to the group. +Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a +"Default membership role" other than Guest. To do so, [configure the SAML SSO for the group](#configure-gitlab). +That role becomes the starting access level of all users added to the group. Existing members with appropriate privileges can promote or demote users, as needed. If a user is already a member of the group, linking the SAML identity does not change their role. +Users given a "minimal access" role have [specific restrictions](../../permissions.md#users-with-minimal-access). + ### Blocking access To rescind a user's access to the group when only SAML SSO is configured, either: @@ -336,6 +341,13 @@ For example, to unlink the `MyOrg` account: ## Group Sync +WARNING: +Changing Group Sync configuration can remove users from the relevant GitLab group. +Removal happens if there is any mismatch between the group names and the list of `groups` in the SAML response. +If changes must be made, ensure either the SAML response includes the `groups` attribute +and the `AttributeValue` value matches the **SAML Group Name** in GitLab, +or that all groups are removed from GitLab to disable Group Sync. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). @@ -353,10 +365,6 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` -WARNING: -Setting up Group Sync can disconnect users from SAML IDP if there is any mismatch in the configuration. Ensure the -`Groups` attribute is included in the SAML response, and the **SAML Group Name** matches the `AttributeValue` attribute. - 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) @@ -533,7 +541,7 @@ This can then be compared to the [NameID](#nameid) being sent by the identity pr 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). -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. +If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configure-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 needs to provide the URL to users. ### Message: "SAML authentication failed: Extern UID has already been taken" |