diff options
Diffstat (limited to 'doc/user/group/saml_sso/group_sync.md')
-rw-r--r-- | doc/user/group/saml_sso/group_sync.md | 34 |
1 files changed, 23 insertions, 11 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). |