diff options
Diffstat (limited to 'doc/user/group/saml_sso/index.md')
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 133 |
1 files changed, 112 insertions, 21 deletions
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 94d2c9afb24..62431747911 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Access -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/#designated-technical-writers +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 --- # SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -38,13 +38,15 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: - Must be unique to each user. - Must be a persistent value that will never change, such as a randomly generated unique user ID. - Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. -- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in. +- Should not be an email address or username. We strongly recommend against these as it's hard to + guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are + 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. -CAUTION: **Warning:** -Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group. +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. #### NameID Format @@ -56,11 +58,11 @@ GitLab provides metadata XML that can be used to configure your Identity Provide 1. Navigate to the group and click **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. -1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested. +1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. ## Configuring GitLab -Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: +After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. @@ -71,7 +73,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co  -NOTE: **Note:** +NOTE: Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement @@ -79,18 +81,18 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. -However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired. +However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired. You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). -When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked. +When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked. ## Providers -NOTE: **Note:** +NOTE: GitLab is unable to provide support for IdPs that are not listed here. | Provider | Documentation | @@ -190,31 +192,77 @@ If the information you need isn't listed above you may wish to check our [troubl ## User access and management +> [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. + Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). -When a user tries to sign in with Group SSO, they will need an account that's configured with one of the following: +When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following: -- [SCIM](scim_setup.md). -- [Group-managed accounts](group_managed_accounts.md). -- A GitLab.com account. +- Find an existing user with a matching SAML identity. This would mean the user either had their account created by [SCIM](scim_setup.md) or they have previously signed in with the group's SAML IdP. +- If there is no conflicting user with the same email address, create a new account automatically. +- If there is a conflicting user with the same email address, redirect the user to the sign-in page to: + - Create a new account with another email address. + - Sign-in to their existing account to link the SAML identity. ### Linking SAML to your existing GitLab.com account To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. -1. Locate and visit the **GitLab single sign-on URL** for the group you are signing in to. A group Admin 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. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin 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. Click **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. -1. You will be 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. +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. -On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you will be redirected to sign in through the identity provider. +On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. ### Signing in to GitLab.com with SAML 1. Sign in to your identity provider. 1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider). -1. You will be signed in to GitLab.com and redirected to the group. +1. You are then signed in to GitLab.com and redirected to the group. + +### Configure user settings from SAML response + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. + +GitLab allows setting certain user attributes based on values from the SAML response. +This affects users created on first sign-in via Group SAML. Existing users' +attributes are not affected regardless of the values sent in the SAML response. + +#### Supported user attributes + +- `can_create_group` - 'true' or 'false' to indicate whether the user can create + new groups. Default is `true`. +- `projects_limit` - The total number of personal projects a user can create. + A value of `0` means the user cannot create new projects in their personal + namespace. Default is `10000`. + +#### Example SAML response + +You can find SAML responses in the developer tools or console of your browser, +in base64-encoded format. Use the base64 decoding tool of your choice to +convert the information to XML. An example SAML response is shown here. + +```xml + <saml2:AttributeStatement> + <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue> + </saml2:Attribute> + </saml2:AttributeStatement> +``` ### Role @@ -238,10 +286,53 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - You no longer want a group to be able to sign you in to GitLab.com. - Your SAML NameID has changed and so GitLab can no longer find your user. -For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: +WARNING: +Unlinking an account removes all roles assigned to that user within the group. +If a user relinks their account, roles need to be reassigned. + +For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:  +## 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). + +When the SAML response includes a user and their group memberships from the SAML identity provider, +GitLab uses that information to automatically manage that user's GitLab group memberships. + +Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following: + +```xml +<saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> + </saml:Attribute> +</saml:AttributeStatement> +``` + +When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users +see a new menu item in group **Settings -> SAML Group Links**. Each group (parent or subgroup) can specify +one or more group links to map a SAML identity provider group name to a GitLab access level. + + + +To link the SAML `Freelancers` group in the attribute statement example above: + +1. Enter `Freelancers` in the `SAML Group Name` field. +1. Choose the desired `Access Level`. +1. **Save** the group link. +1. Repeat to add additional group links if desired. + + + +If a user is a member of multiple SAML groups mapped to the same GitLab group, +the user gets the highest access level from the groups. For example, if one group +is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` +access. + ## Glossary | Term | Description | @@ -250,7 +341,7 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | Service Provider | SAML considers GitLab to be a service provider. | | Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | | SSO | Single Sign On. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | |