diff --git a/doc/user/group/saml_sso/img/group_saml_configuration_information.png b/doc/user/group/saml_sso/img/group_saml_configuration_information.png new file mode 100644 index 0000000000000000000000000000000000000000..98b83d0cb0f710a77015adeab13ad25fbe32e6c8 Binary files /dev/null and b/doc/user/group/saml_sso/img/group_saml_configuration_information.png differ diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png new file mode 100644 index 0000000000000000000000000000000000000000..d95acb5075f98122d9d0781aee34e96cf6d42aa4 Binary files /dev/null and b/doc/user/group/saml_sso/img/group_saml_settings.png differ diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png new file mode 100644 index 0000000000000000000000000000000000000000..0561443b5f4da7e29ded8dcf9512e697bb15d29b Binary files /dev/null and b/doc/user/group/saml_sso/img/unlink_group_saml.png differ diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index fce0f645cbb35bb12ed45fec49183fa7fb2a33cf..c46776a19b050af4fd28e8e561a93b0054f2b6c9 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -8,16 +8,17 @@ Currently SAML on GitLab.com can be used to automatically add users to a group, NOTE: **Note:** SAML SSO for groups is used only as a convenient way to add users and does not sync users between providers. Group owners will still need to manage user accounts, such as removing users when necessary. -## How to configure +## Configuring your Identity Provider 1. Navigate to the group and click Settings -> SAML SSO. 1. Configure your SAML server using the **Assertion consumer service URL** and **Issuer**. See [your identity provider's documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. -1. Configure required assertions using the table below. -1. Find the SSO URL from your Identity Provider and enter it on GitLab. -1. Find and enter the fingerprint for the SAML token signing certificate. +1. Configure required assertions using the [table below](#assertions). +1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab). -## NameID +![Issuer and callback for configuring SAML identity provider with GitLab.com](img/group_saml_configuration_information.png) + +### NameID GitLab.com uses the SAML NameID to identify users. The NameID element: @@ -25,7 +26,7 @@ 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 unique ID or username. Email could also be used as the NameID, but only if it can be guaranteed to never change. -## Assertions +### Assertions | Field | Supported keys | Notes | |-|----------------|-------------| @@ -34,6 +35,18 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: | First Name | `first_name`, `firstname`, `firstName` | | | Last Name | `last_name`, `lastname`, `lastName` | | +## 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: + +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. +1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. +1. Check the **Enable SAML authentication for this group** checkbox. +1. Click the **Save changes** button. + +![Group SAML Settings for GitLab.com](img/group_saml_settings.png) + ## Providers | Provider | Documentation | @@ -47,6 +60,17 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: | OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | | Ping Identity | [Add and configure a new SAML application](https://docs.pingidentity.com/bundle/p1_enterpriseConfigSsoSaml_cas/page/enableAppWithoutURL.html) | +## Unlinking accounts + +Users can unlink SAML for a group from their profile page. This can be helpful if: + +- 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**: + +![Unlink Group SAML](img/unlink_group_saml.png) + ## Glossary | Term | Description |