Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/doc/user/group/saml_sso/index.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/group/saml_sso/index.md')
-rw-r--r--doc/user/group/saml_sso/index.md158
1 files changed, 123 insertions, 35 deletions
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index a627f04fa46..8f6b3e7244a 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -57,6 +57,7 @@ Once users have signed into GitLab using the SSO SAML setup, changing the `NameI
#### NameID Format
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
@@ -120,6 +121,14 @@ SSO has the following effects when enabled:
- 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:
+
+- Is signed out, they cannot access the group after being removed from the identity provider.
+- Has an active session, they can continue accessing the group for up to 24 hours until the identity
+ provider session times out.
+
+When SCIM updates, the user's access is immediately revoked.
+
## Providers
The SAML standard means that a wide range of identity providers will work with GitLab. Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab.
@@ -140,13 +149,13 @@ Follow the Azure documentation on [configuring single sign-on to applications](h
For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). The video is outdated in regard to
objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps).
-| GitLab Setting | Azure Field |
-|--------------|----------------|
-| Identifier | Identifier (Entity ID) |
-| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) |
-| GitLab single sign-on URL | Sign on URL |
-| Identity provider single sign-on URL | Login URL |
-| Certificate fingerprint | Thumbprint |
+| GitLab Setting | Azure Field |
+| ------------------------------------ | ------------------------------------------ |
+| Identifier | Identifier (Entity ID) |
+| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) |
+| GitLab single sign-on URL | Sign on URL |
+| Identity provider single sign-on URL | Login URL |
+| Certificate fingerprint | Thumbprint |
We recommend:
@@ -164,12 +173,12 @@ Please follow the Okta documentation on [setting up a SAML application in Okta](
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ).
-| GitLab Setting | Okta Field |
-|--------------|----------------|
-| Identifier | Audience URI |
-| Assertion consumer service URL | Single sign-on URL |
-| GitLab single sign-on URL | Login page URL (under **Application Login Page** settings) |
-| Identity provider single sign-on URL | Identity Provider Single Sign-On URL |
+| GitLab Setting | Okta Field |
+| ------------------------------------ | ---------------------------------------------------------- |
+| Identifier | Audience URI |
+| Assertion consumer service URL | Single sign-on URL |
+| GitLab single sign-on URL | Login page URL (under **Application Login Page** settings) |
+| Identity provider single sign-on URL | Identity Provider Single Sign-On URL |
Under Okta's **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**.
@@ -186,14 +195,14 @@ application.
If you decide to use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934),
we recommend the ["Use the OneLogin SAML Test Connector" documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) with the following settings:
-| GitLab Setting | OneLogin Field |
-|--------------|----------------|
-| Identifier | Audience |
-| Assertion consumer service URL | Recipient |
-| Assertion consumer service URL | ACS (Consumer) URL |
+| GitLab Setting | OneLogin Field |
+| ------------------------------------------------ | ---------------------------- |
+| Identifier | Audience |
+| Assertion consumer service URL | Recipient |
+| Assertion consumer service URL | ACS (Consumer) URL |
| Assertion consumer service URL (escaped version) | ACS (Consumer) URL Validator |
-| GitLab single sign-on URL | Login URL |
-| Identity provider single sign-on URL | SAML 2.0 Endpoint |
+| GitLab single sign-on URL | Login URL |
+| Identity provider single sign-on URL | SAML 2.0 Endpoint |
Recommended `NameID` value: `OneLogin ID`.
@@ -281,10 +290,7 @@ If a user is already a member of the group, linking the SAML identity does not c
### Blocking access
-To rescind access to the group, perform the following steps, in order:
-
-1. Remove the user from the user data store on the identity provider or the list of users on the specific app.
-1. Remove the user from the GitLab.com group.
+Please refer to [Blocking access via SCIM](scim_setup.md#blocking-access).
### Unlinking accounts
@@ -305,7 +311,7 @@ For example, to unlink the `MyOrg` account:
1. In the top-right corner, select your avatar.
1. Select **Edit profile**.
-1. In the left sidebar, select **Account**.
+1. On the left sidebar, select **Account**.
1. In the **Social sign-in** section, select **Disconnect** next to the connected account.
![Unlink Group SAML](img/unlink_group_saml.png)
@@ -331,7 +337,7 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o
NOTE:
To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools).
-Also note that the value for `Groups` or `groups` in the SAML reponse can be either the group name or
+Also note that the value for `Groups` or `groups` in the SAML response can be either the group name or
the group ID depending what the IdP sends to GitLab.
When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users
@@ -352,10 +358,88 @@ the user gets the highest access level from the groups. For example, if one grou
is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer`
access.
-Users who are not members of any mapped SAML groups are removed from the GitLab group.
+### Automatic member removal
+
+After a group sync, users who are not members of a mapped SAML group are removed from
+the GitLab group.
+
+For example, in the following diagram:
-You can prevent accidental member removal. For example, if you have a SAML group link for `Owner` level access
-in a top-level group, you should also set up a group link for all other members.
+- Alex Garcia signs into GitLab and is removed from GitLab Group C because they don't belong
+ to SAML Group C.
+- Sidney Jones belongs to SAML Group C, but is not added to GitLab Group C because they have
+ not yet signed in.
+
+```mermaid
+graph TB
+ subgraph SAML users
+ SAMLUserA[Sidney Jones]
+ SAMLUserB[Zhang Wei]
+ SAMLUserC[Alex Garcia]
+ SAMLUserD[Charlie Smith]
+ end
+
+ subgraph SAML groups
+ SAMLGroupA["Group A"] --> SAMLGroupB["Group B"]
+ SAMLGroupA --> SAMLGroupC["Group C"]
+ SAMLGroupA --> SAMLGroupD["Group D"]
+ end
+
+ SAMLGroupB --> |Member|SAMLUserA
+ SAMLGroupB --> |Member|SAMLUserB
+
+ SAMLGroupC --> |Member|SAMLUserA
+ SAMLGroupC --> |Member|SAMLUserB
+
+ SAMLGroupD --> |Member|SAMLUserD
+ SAMLGroupD --> |Member|SAMLUserC
+```
+
+```mermaid
+graph TB
+ subgraph GitLab users
+ GitLabUserA[Sidney Jones]
+ GitLabUserB[Zhang Wei]
+ GitLabUserC[Alex Garcia]
+ GitLabUserD[Charlie Smith]
+ end
+
+ subgraph GitLab groups
+ GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"]
+ GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"]
+ GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"]
+ end
+
+ GitLabGroupB --> |Member|GitLabUserA
+
+ GitLabGroupC --> |Member|GitLabUserB
+ GitLabGroupC --> |Member|GitLabUserC
+
+ GitLabGroupD --> |Member|GitLabUserC
+ GitLabGroupD --> |Member|GitLabUserD
+```
+
+```mermaid
+graph TB
+ subgraph GitLab users
+ GitLabUserA[Sidney Jones]
+ GitLabUserB[Zhang Wei]
+ GitLabUserC[Alex Garcia]
+ GitLabUserD[Charlie Smith]
+ end
+
+ subgraph GitLab groups after Alex Garcia signs in
+ GitLabGroupA[Group A]
+ GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"]
+ GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"]
+ GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"]
+ end
+
+ GitLabGroupB --> |Member|GitLabUserA
+ GitLabGroupC --> |Member|GitLabUserB
+ GitLabGroupD --> |Member|GitLabUserC
+ GitLabGroupD --> |Member|GitLabUserD
+```
## Passwords for users created via SAML SSO for Groups
@@ -392,6 +476,9 @@ This can then be compared to the [NameID](#nameid) being sent by the identity pr
### Users receive a 404
+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.
As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users.
@@ -403,17 +490,18 @@ If you do not wish to use that GitLab user with the SAML login, you can [unlink
### Message: "SAML authentication failed: User has already been taken"
-The user that you're signed in with already has SAML linked to a different identity.
+The user that you're signed in with already has SAML linked to a different identity, or the NameID value has changed.
Here are possible causes and solutions:
-| Cause | Solution |
-|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Cause | Solution |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](#unlinking-accounts) from this GitLab account before attempting to sign in again. |
+| The NameID changes everytime the user requests SSO identification | Check the NameID is not set with `Transient` format, or the NameID is not changing on subsequent requests.|
### Message: "SAML authentication failed: Email has already been taken"
| Cause | Solution |
-|------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). |
### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken"
@@ -439,8 +527,8 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun
### The NameID has changed
-| Cause | Solution |
-|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Cause | Solution |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. |
### I need to change my SAML app
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-12 10:49:07 +0300