diff options
Diffstat (limited to 'doc/user/group/saml_sso')
| -rw-r--r-- | doc/user/group/saml_sso/example_saml_config.md | 2 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/group_sync.md | 11 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 14 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/scim_setup.md | 29 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/troubleshooting.md | 64 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/troubleshooting_scim.md | 15 |
6 files changed, 96 insertions, 39 deletions
diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index c5f84510c57..70e01e1d9a9 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern 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/product/ux/technical-writing/#assignments type: reference diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index c3edc01fe74..335c989c85f 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Manage +stage: Govern 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/product/ux/technical-writing/#assignments --- @@ -155,10 +155,11 @@ To integrate Microsoft Azure AD, you: To configure for a GitLab.com group: -1. Configure [SAML SSO for the group](../../../user/group/saml_sso/index.md). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. On the left sidebar, select **Search or go to** and find your top-level group. 1. Select **Settings > SAML SSO**. +1. Configure [SAML SSO for the group](../../../user/group/saml_sso/index.md). 1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. + This section will only be visible if SAML SSO is configured and enabled for the group. 1. Enter the **Tenant ID**, **Client ID**, and **Client secret** obtained earlier when configuring Azure Active Directory in the Azure Portal. 1. Optional. If using Azure AD for US Government or Azure AD China, enter the appropriate **Login API endpoint** and **Graph API endpoint**. The default values work for most organizations. 1. Select **Save changes**. @@ -166,7 +167,7 @@ To configure for a GitLab.com group: To configure for self-managed: 1. Configure [SAML SSO for the instance](../../../integration/saml.md). -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. @@ -197,7 +198,7 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure SAML](../../../integration/saml.md) for your self-managed GitLab instance. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 41c2090f4bc..734679cf331 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern 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/product/ux/technical-writing/#assignments --- @@ -38,7 +38,7 @@ If you are having issues setting up your identity provider, see the To set up SSO with Azure as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Go to Azure and [follow the instructions for configuring SSO for an application](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso). The following GitLab settings correspond to the Azure fields. @@ -71,7 +71,7 @@ For more information, see an [example configuration page](example_saml_config.md To set up Google Workspace as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Follow the instructions for [setting up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). The following GitLab settings correspond to the Google Workspace fields. @@ -115,7 +115,7 @@ View a demo of [how to configure SAML with Google Workspaces and set up Group Sy To set up SSO with Okta as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Follow the instructions for [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). @@ -152,7 +152,7 @@ OneLogin supports its own [GitLab (SaaS) application](https://onelogin.service-n To set up OneLogin as your identity provider: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. If you use the OneLogin generic @@ -179,7 +179,7 @@ To set up OneLogin as your identity provider: To configure some identity providers, you need a GitLab metadata URL. To find this URL: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. @@ -217,7 +217,7 @@ If the **NameID** is configured with the email address, [change the **NameID** f After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Complete the fields: - In the **Identity provider single sign-on URL** field, enter the SSO URL from your identity provider. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 9096824cc2c..a9b9bf26444 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern 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/product/ux/technical-writing/#assignments --- @@ -10,12 +10,14 @@ You can use the open standard System for Cross-domain Identity Management (SCIM) - Create users. - Remove users (deactivate SCIM identity). +- Re-add users (reactivate SCIM identity). GitLab SAML SSO SCIM doesn't support updating users. When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider. The [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). +Identity providers can use the [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) to develop a SCIM app. ## Configure GitLab @@ -25,7 +27,7 @@ Prerequisites: To configure GitLab SAML SSO SCIM: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > SAML SSO**. 1. Select **Generate a SCIM token**. 1. For configuration of your identity provider, save the: @@ -40,7 +42,7 @@ You can configure one of the following as an identity provider: - [Okta](#configure-okta). NOTE: -Other providers can work with GitLab but they have not been tested and are not supported. +Other providers can work with GitLab but they have not been tested and are not supported. You should contact the provider for support. GitLab support can assist by reviewing related log entries. ### Configure Azure Active Directory @@ -165,7 +167,8 @@ To configure Okta for SCIM: During the synchronization process, all new users: - Receive GitLab accounts. -- Are welcomed to their groups with an invitation email. You may want to warn your employees to expect this email. +- Are welcomed to their groups with an invitation email. + You can [bypass email confirmation with a verified domain](index.md#bypass-user-email-confirmation-with-verified-domains). The following diagram describes what happens when you add users to your SCIM app: @@ -216,10 +219,11 @@ Remove or deactivate a user on the identity provider to remove their access to: - The top-level group. - All subgroups and projects. -After the identity provider performs a sync based on its configured schedule, the user's membership is revoked and they -lose access. +After the identity provider performs a sync based on its configured schedule, +the user's membership is revoked and they lose access. -When you enable SCIM, this does not automatically remove existing users who do not have a SAML identity. +When you enable SCIM, this does not automatically remove existing users who do +not have a SAML identity. NOTE: Deprovisioning does not delete the GitLab user account. @@ -230,3 +234,14 @@ graph TD B -->|No| C[Nothing to do] B -->|Yes| D[GitLab removes user from GitLab group] ``` + +### Reactivate access + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379149) in GitLab 16.0 [with a flag](../../feature_flags.md) named `skip_saml_identity_destroy_during_scim_deprovision`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121226) in GitLab 16.4. Feature flag `skip_saml_identity_destroy_during_scim_deprovision` removed. + +After a user is removed or deactivated through SCIM, you can reactivate that user by +adding them to the SCIM identity provider. + +After the identity provider performs a sync based on its configured schedule, +the user's SCIM identity is reactivated and their group memberships are restored. diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 82703893834..cf9b9f5d4eb 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -1,6 +1,6 @@ --- type: reference -stage: Manage +stage: Govern 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/product/ux/technical-writing/#assignments --- @@ -217,6 +217,18 @@ to [reset their password](https://gitlab.com/users/password/new) if both: - The account was provisioned by SCIM. - They are signing in with username and password for the first time. +### Message: "SAML Name ID and email address do not match your user account" **(PREMIUM SAAS)** + +Users might get an error that states "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. + +The workaround is that a GitLab group Owner uses 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. + ## Other user sign in issues ### Verify `NameID` @@ -254,12 +266,24 @@ If all users are receiving a `404` after signing in to the identity provider (Id - In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). - As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. -- Verify if the `404` is related to [the user having too many groups assigned to them in their Azure IdP](group_sync.md#user-that-belongs-to-many-saml-groups-automatically-removed-from-gitlab-group) by checking: +- Verify if the `404` is related to [the user having too many groups assigned to them in their Azure IdP](group_sync.md#user-that-belongs-to-many-saml-groups-automatically-removed-from-gitlab-group). + +If a subset of users are receiving a `404` after signing in to the IdP, first verify audit events if the user gets added to the group and then immediately removed. Alternatively, if the user can successfully sign in, but they do not show as [a member of the top-level group](../index.md#search-a-group): - - If the user has group links configured. - - Audit events if the user gets added to the group and then immediately removed. +- Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management), and [SCIM](scim_setup.md) if configured. +- Ensure the user's SCIM identity's `active` attribute is `true` using the [SCIM API](../../../api/scim.md). + If the `active` attribute is `false`, you can do one of the following to possibly resolve the issue: -For configuration examples for some of the common providers, see the [example group SAML and SCIM configurations](example_saml_config.md). + - Trigger a sync for the user in the SCIM identity provider. For example, Azure has a "Provision on demand" option. + - Remove and re-add the user in the SCIM identity provider. + - Have the user [unlink their account](index.md#unlink-accounts) if possible, then [link their account](index.md#link-saml-to-your-existing-gitlabcom-account). + - Use the [internal SCIM API](../../../development/internal_api/index.md#update-a-single-scim-provisioned-user) to update the user's SCIM identity using your group's SCIM token. + If you do not know your group's SCIM token, reset the token and update the SCIM identity provider app with the new token. + Example request: + + ```plaintext + curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }' + ``` ### 500 error after login **(FREE SELF)** @@ -283,6 +307,21 @@ Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/call If the ACS URL is correct, and you still have errors, review the other Troubleshooting sections. +#### 422 error with non-allowed email + +You might get an 422 error that states "Email is not allowed for sign-up. Please use your regular email address." + +This message might indicate that you must add or remove a domain from your domain allowlist or denylist settings. + +To implement this workaround: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. Select **Settings** > **General**. +1. Expand **Sign-up restrictions**. +1. Add or remove a domain as appropriate to **Allowed domains for sign-ups** and **Denied domains for sign-ups**. +1. Select **Save changes**. + ### User is blocked when signing in through SAML **(FREE SELF)** The following are the most likely reasons that a user is blocked when signing in through SAML: @@ -298,18 +337,6 @@ 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. - ## Message: "The member's email address is not linked to a SAML account" **(PREMIUM SAAS)** This error appears when you try to invite a user to a GitLab.com group (or subgroup or project within a group) that has [SAML SSO enforcement](index.md#sso-enforcement) enabled. @@ -318,3 +345,6 @@ If you see this message after trying to invite a user to a group: 1. Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management). 1. Ask the user to [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account), if they have one. Otherwise, ask the user to create a GitLab.com account by [accessing GitLab.com through the identity provider's dashboard](index.md#user-access-and-management), or by [signing up manually](https://gitlab.com/users/sign_up) and linking SAML to their new account. +1. Ensure the user is a [member of the top-level group](../index.md#search-a-group). + +Additionally, see [troubleshooting users receiving a 404 after sign in](#users-receive-a-404). diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 7d2aa8faa99..63d10f3e932 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern 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/product/ux/technical-writing/#assignments --- @@ -13,7 +13,18 @@ This section contains possible solutions for problems you might encounter. When you remove a user, they are removed from the group but their account is not deleted (see [remove access](scim_setup.md#remove-access)). -When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists. +When the user is added back to the SCIM app, GitLab does not create a new user because the user already exists. + +From August 11, 2023, the `skip_saml_identity_destroy_during_scim_deprovision` feature flag is enabled. + +For a user de-provisioned by SCIM from that date, their SAML identity is not removed. + +When that user is added back to the SCIM app: + +- Their SCIM identity `active` attribute is set to `true`. +- They can sign in using SSO. + +For users de-provisioned by SCIM before that date, their SAML identity is destroyed. To solve this problem: |