diff options
Diffstat (limited to 'doc/user/group/saml_sso')
| -rw-r--r-- | doc/user/group/saml_sso/group_sync.md | 34 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 24 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/troubleshooting.md | 27 |
3 files changed, 65 insertions, 20 deletions
diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 001c73b6979..80d145fc6bb 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -10,9 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363084) for self-managed instances in GitLab 15.1. WARNING: -Changing Group Sync configuration can remove users from the mapped GitLab group. +Adding or changing Group Sync configuration can remove users from the mapped 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 +Before making changes, 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. @@ -21,17 +21,29 @@ For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu. ## Configure SAML Group Sync +NOTE: +You must include the SAML configuration block on all Sidekiq nodes in addition to Rails application nodes if you: + +- Use SAML Group Sync. +- Have multiple GitLab nodes, for example in a distributed or highly available architecture. + +WARNING: +To prevent users being accidentally removed from the GitLab group, follow these instructions closely before +enabling Group Sync in GitLab. + To configure SAML Group Sync: -- For GitLab self-managed: - 1. Configure the [SAML OmniAuth Provider](../../../integration/saml.md). - 1. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the `groups_attribute` setting. -- For GitLab.com: - 1. See [SAML SSO for GitLab.com groups](index.md). - 1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. +1. Configure the identity Provider: + - For self-managed GitLab, see the [SAML OmniAuth Provider documentation](../../../integration/saml.md). + - For GitLab.com, see the [SAML SSO for GitLab.com groups documentation](index.md). + +1. Capture [a SAML response](troubleshooting.md#saml-debugging-tools) during the sign-in process to confirm your SAML identity provider sends an attribute statement: + - For self-managed GitLab, with the same name as the value of the `groups_attribute` setting. + - For GitLab.com, named `Groups` or `groups`. NOTE: -The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. +The value for `Groups` or `groups` in the SAML response may be either the group name or an ID. +For example, Azure AD sends the Azure Group Object ID instead of the name. Use the ID value when configuring [SAML Group Links](#configure-saml-group-links). ```xml <saml:AttributeStatement> @@ -55,7 +67,7 @@ a SAML identity provider group name to a GitLab role. This can be done for a top To link the SAML groups: -1. In **SAML Group Name**, enter the value of the relevant `saml:AttributeValue`. +1. In **SAML Group Name**, enter the value of the relevant `saml:AttributeValue`. The value entered here must exactly match the value sent in the SAML response. For some IdPs, this may be a group ID or object ID (Azure AD) instead of a friendly group name. 1. Choose the role in **Access Level**. 1. Select **Save**. 1. Repeat to add additional group links if required. @@ -177,4 +189,4 @@ Because of a [known issue with Azure AD](https://support.esri.com/en/technical-a in the user's SAML assertion. To work around this issue, allow more than 150 group IDs to be sent in SAML token using configuration steps in the -[Azure AD documentation](https://support.esri.com/en/technical-article/000022190). +[Azure AD documentation](https://support.esri.com/en/technical-article/000022190). diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 1c5e7ff0115..bd10560e138 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -53,7 +53,6 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: also case-insensitive, which can result in users being unable to sign in. The relevant field name and recommended value for supported providers are in the [provider specific notes](#providers). -appropriate corresponding field. WARNING: Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group. @@ -72,7 +71,7 @@ must be specified as an attribute named `email` or `mail`. You can configure the following attributes with GitLab.com Group SAML: - `username` or `nickname`. We recommend you configure only one of these. -- The [attributes available](../../../integration/saml.md#assertions) to self-managed GitLab instances. +- The [attributes available](../../../integration/saml.md#configure-assertions) to self-managed GitLab instances. ### Metadata configuration @@ -98,7 +97,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. +The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. ### Additional configuration information @@ -124,7 +123,7 @@ It can also help to compare the XML response from your provider with our [exampl > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com. FLAG: -On self-managed GitLab, transparent SSO enforcement is unavailable. On GitLab.com, transparent SSO enforcement is unavailable and can be configured by GitLab.com administrators only. +On self-managed GitLab, transparent SSO enforcement is unavailable. On GitLab.com, see the [Transparent SSO rollout](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) issue for the current status. SSO is enforced when users access groups and projects in the organization's group hierarchy. Users can view other groups and projects without SSO sign in. @@ -178,13 +177,24 @@ When SSO is enforced, users are not immediately revoked. If the user: - Has an active session, they can continue accessing the group for up to 24 hours until the identity provider session times out. +### Selectively enable and disable transparent SSO enforcement + +There are two feature flags associated with this feature to allow precise control. If a customer has a problem with transparent SSO on GitLab.com, GitLab can help troubleshoot and override the feature flag as necessary. + +**`transparent_sso_enforcement`:** This feature flag should only be enabled or disabled by the Authentication and Authorization group +or in the case of a serious and widespread issue affecting many groups or users. See [issue 375788](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) for the current GitLab.com rollout status. + +**`transparent_sso_enforcement_override`:** When the `transparent_sso_enforcement` feature flag is enabled, support or production teams can +turn off transparent SSO by enabling this feature flag for a specific customer group. **Enabling** this feature flag +disables transparent SSO enforcement. + ## Providers 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](#configure-your-identity-provider), 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 providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#configure-saml-on-your-idp) for additional guidance on information your identity provider may require. GitLab provides the following information for guidance only. @@ -338,10 +348,14 @@ When a user tries to sign in with Group SSO, GitLab attempts to find or create a ### Linking SAML to your existing GitLab.com account +> **Remember me** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121569) in GitLab 15.7. + To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. [Reset your password](https://gitlab.com/users/password/new) if necessary. 1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the identity provider. +1. Optional. Select the **Remember me** checkbox to stay signed in to GitLab for 2 weeks. You may still be asked to re-authenticate with your SAML provider + more frequently. 1. Select **Authorize**. 1. Enter your credentials on the identity provider if prompted. 1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. 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. |