diff options
Diffstat (limited to 'doc/user/group/saml_sso')
24 files changed, 231 insertions, 10 deletions
diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md new file mode 100644 index 00000000000..97e8f9c54a3 --- /dev/null +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -0,0 +1,211 @@ +--- +stage: Manage +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/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Example group SAML and SCIM configurations **(PREMIUM SAAS)** + +These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team's collected knowledge. + +Please refer to the GitLab [Group SAML](index.md) docs for information on the feature and how to set it up. + +When troubleshooting a SAML configuration, GitLab team members will frequently start with the [SAML troubleshooting section](index.md#troubleshooting). + +They may then set up a test configuration of the desired identity provider. We include example screenshots in this section. + +## SAML and SCIM screenshots + +This section includes relevant screenshots of the following example configurations of [Group SAML](index.md) and [Group SCIM](scim_setup.md): + +- [Azure Active Directory](#azure-active-directory) +- [Google Workspace](#google-workspace) +- [Okta](#okta) +- [OneLogin](#onelogin) + +WARNING: +These screenshots are updated only as needed by GitLab Support. They are **not** official documentation. + +If you are currently having an issue with GitLab, you may want to check your [support options](https://about.gitlab.com/support/). + +## Azure Active Directory + +Basic SAML app configuration: + + + +User claims and attributes: + + + +SCIM mapping: + + + + +Group Sync: + + + +## Google Workspace + +Basic SAML app configuration: + + + +User claims and attributes: + + + +IdP links and certificate: + +NOTE: +Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for configuring SAML, download the certificate and calculate the SHA1 certificate +fingerprint. + + + +## Okta + +Basic SAML app configuration for GitLab.com groups: + + + +Basic SAML app configuration for GitLab self-managed: + + + +User claims and attributes: + + + +Groups attribute: + + + +Advanced SAML app settings (defaults): + + + +IdP Links and Certificate: + + + +Sign on settings: + + + +Setting the username for the newly provisioned users when assigning them the SCIM app: + + + +## OneLogin + +Application details: + + + +Parameters: + + + +Adding a user: + + + +SSO settings: + + + +## SAML response example + +When a user signs in using SAML, GitLab receives a SAML response. The SAML response can be found in `production.log` logs as a base64-encoded message. Locate the response by +searching for `SAMLResponse`. The decoded SAML response is in XML format. For example: + +```xml +<?xml version="1.0" encoding="UTF-8"?> +<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema" Destination="https://gitlabexample/-/saml/callback" ID="id4898983630840142426821432" InResponseTo="_c65e4c88-9425-4472-b42c-37f4186ac0ee" IssueInstant="2022-05-30T21:30:35.696Z" Version="2.0"> + <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk2y6j57o1Pdr2lI8qh7</saml2:Issuer> + <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> + <ds:SignedInfo> + <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> + <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/> + <ds:Reference URI="#id4898983630840142426821432"> + <ds:Transforms> + <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> + <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> + <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/> + </ds:Transform> + </ds:Transforms> + <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> + <ds:DigestValue>neiQvv9d3OgS4GZW8Nptp4JhjpKs3GCefibn+vmRgk4=</ds:DigestValue> + </ds:Reference> + </ds:SignedInfo> + <ds:SignatureValue>dMsQX8ivi...HMuKGhyLRvabGU6CuPrf7==</ds:SignatureValue> + <ds:KeyInfo> + <ds:X509Data> + <ds:X509Certificate>MIIDq...cptGr3vN9TQ==</ds:X509Certificate> + </ds:X509Data> + </ds:KeyInfo> + </ds:Signature> + <saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"> + <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> + </saml2p:Status> + <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="id489" IssueInstant="2022-05-30T21:30:35.696Z" Version="2.0"> + <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk2y6j57o1Pdr2lI8qh7</saml2:Issuer> + <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> + <ds:SignedInfo> + <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> + <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/> + <ds:Reference URI="#id48989836309833801859473359"> + <ds:Transforms> + <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> + <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> + <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/> + </ds:Transform> + </ds:Transforms> + <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> + <ds:DigestValue>MaIsoi8hbT9gsi/mNZsz449mUuAcuEWY0q3bc4asOQs=</ds:DigestValue> + </ds:Reference> + </ds:SignedInfo> + <ds:SignatureValue>dMsQX8ivi...HMuKGhyLRvabGU6CuPrf7==<</ds:SignatureValue> + <ds:KeyInfo> + <ds:X509Data> + <ds:X509Certificate>MIIDq...cptGr3vN9TQ==</ds:X509Certificate> + </ds:X509Data> + </ds:KeyInfo> + </ds:Signature> + <saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> + <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">useremail@domain.com</saml2:NameID> + <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> + <saml2:SubjectConfirmationData InResponseTo="_c65e4c88-9425-4472-b42c-37f4186ac0ee" NotOnOrAfter="2022-05-30T21:35:35.696Z" Recipient="https://gitlab.example.com/-/saml/callback"/> + </saml2:SubjectConfirmation> + </saml2:Subject> + <saml2:Conditions xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" NotBefore="2022-05-30T21:25:35.696Z" NotOnOrAfter="2022-05-30T21:35:35.696Z"> + <saml2:AudienceRestriction> + <saml2:Audience>https://gitlab.example.com/</saml2:Audience> + </saml2:AudienceRestriction> + </saml2:Conditions> + <saml2:AuthnStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" AuthnInstant="2022-05-30T21:30:35.696Z" SessionIndex="_c65e4c88-9425-4472-b42c-37f4186ac0ee"> + <saml2:AuthnContext> + <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef> + </saml2:AuthnContext> + </saml2:AuthnStatement> + <saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> + <saml2:Attribute Name="email" 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">useremail@domain.com</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="firtname" 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">John</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="lastname" 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">Doe</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="Groups" 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">Super-awesome-group</saml2:AttributeValue> + </saml2:Attribute> + </saml2:AttributeStatement> + </saml2:Assertion> +</saml2p:Response> +``` diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index b8b7a16b31b..8bc316f9396 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -28,7 +28,7 @@ To configure SAML Group Sync: 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. Ensure your SAML identity provider sends an attribute statement 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. @@ -44,8 +44,8 @@ The value for `Groups` or `groups` in the SAML response can be either the group Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` are not accepted as a source of groups. -See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) -for examples on configuring the required attribute name in the SAML identity provider's settings. +See [examples](../../../user/group/saml_sso/example_saml_config.md) +for configuring the required attribute name in the SAML identity provider's settings. ## Configure SAML Group Links @@ -161,3 +161,9 @@ graph TB GitLabGroupD --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserD ``` + +### Use the API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. + +You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. diff --git a/doc/user/group/saml_sso/img/AzureAD-basic_SAML.png b/doc/user/group/saml_sso/img/AzureAD-basic_SAML.png Binary files differnew file mode 100644 index 00000000000..7a0d83ab2dd --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-basic_SAML.png diff --git a/doc/user/group/saml_sso/img/AzureAD-claims.png b/doc/user/group/saml_sso/img/AzureAD-claims.png Binary files differnew file mode 100644 index 00000000000..576040be337 --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-claims.png diff --git a/doc/user/group/saml_sso/img/AzureAD-scim_attribute_mapping.png b/doc/user/group/saml_sso/img/AzureAD-scim_attribute_mapping.png Binary files differnew file mode 100644 index 00000000000..5ad82003eed --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-scim_attribute_mapping.png diff --git a/doc/user/group/saml_sso/img/AzureAD-scim_provisioning.png b/doc/user/group/saml_sso/img/AzureAD-scim_provisioning.png Binary files differnew file mode 100644 index 00000000000..b2c385151a6 --- /dev/null +++ b/doc/user/group/saml_sso/img/AzureAD-scim_provisioning.png diff --git a/doc/user/group/saml_sso/img/GoogleWorkspace-basic-SAML_v14_10.png b/doc/user/group/saml_sso/img/GoogleWorkspace-basic-SAML_v14_10.png Binary files differnew file mode 100644 index 00000000000..e002503ddc0 --- /dev/null +++ b/doc/user/group/saml_sso/img/GoogleWorkspace-basic-SAML_v14_10.png diff --git a/doc/user/group/saml_sso/img/GoogleWorkspace-claims_v14_10.png b/doc/user/group/saml_sso/img/GoogleWorkspace-claims_v14_10.png Binary files differnew file mode 100644 index 00000000000..2b827e122a8 --- /dev/null +++ b/doc/user/group/saml_sso/img/GoogleWorkspace-claims_v14_10.png diff --git a/doc/user/group/saml_sso/img/GoogleWorkspace-linkscert_v14_10.png b/doc/user/group/saml_sso/img/GoogleWorkspace-linkscert_v14_10.png Binary files differnew file mode 100644 index 00000000000..8d6c5010670 --- /dev/null +++ b/doc/user/group/saml_sso/img/GoogleWorkspace-linkscert_v14_10.png diff --git a/doc/user/group/saml_sso/img/Okta-GroupAttribute.png b/doc/user/group/saml_sso/img/Okta-GroupAttribute.png Binary files differnew file mode 100644 index 00000000000..54c69053754 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-GroupAttribute.png diff --git a/doc/user/group/saml_sso/img/Okta-GroupSAML.png b/doc/user/group/saml_sso/img/Okta-GroupSAML.png Binary files differnew file mode 100644 index 00000000000..7871e4ff82b --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-GroupSAML.png diff --git a/doc/user/group/saml_sso/img/Okta-SM.png b/doc/user/group/saml_sso/img/Okta-SM.png Binary files differnew file mode 100644 index 00000000000..b335009fed9 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-SM.png diff --git a/doc/user/group/saml_sso/img/Okta-advancedsettings.png b/doc/user/group/saml_sso/img/Okta-advancedsettings.png Binary files differnew file mode 100644 index 00000000000..1478dc58ccd --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-advancedsettings.png diff --git a/doc/user/group/saml_sso/img/Okta-attributes.png b/doc/user/group/saml_sso/img/Okta-attributes.png Binary files differnew file mode 100644 index 00000000000..38af72474d8 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-attributes.png diff --git a/doc/user/group/saml_sso/img/Okta-linkscert.png b/doc/user/group/saml_sso/img/Okta-linkscert.png Binary files differnew file mode 100644 index 00000000000..62db5d2b7e3 --- /dev/null +++ b/doc/user/group/saml_sso/img/Okta-linkscert.png diff --git a/doc/user/group/saml_sso/img/OneLogin-SSOsettings.png b/doc/user/group/saml_sso/img/OneLogin-SSOsettings.png Binary files differnew file mode 100644 index 00000000000..58f936d8567 --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-SSOsettings.png diff --git a/doc/user/group/saml_sso/img/OneLogin-app_details.png b/doc/user/group/saml_sso/img/OneLogin-app_details.png Binary files differnew file mode 100644 index 00000000000..77618960897 --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-app_details.png diff --git a/doc/user/group/saml_sso/img/OneLogin-parameters.png b/doc/user/group/saml_sso/img/OneLogin-parameters.png Binary files differnew file mode 100644 index 00000000000..a2fa734152c --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-parameters.png diff --git a/doc/user/group/saml_sso/img/OneLogin-userAdd.png b/doc/user/group/saml_sso/img/OneLogin-userAdd.png Binary files differnew file mode 100644 index 00000000000..54c1ecd2e68 --- /dev/null +++ b/doc/user/group/saml_sso/img/OneLogin-userAdd.png diff --git a/doc/user/group/saml_sso/img/azure_configure_group_claim.png b/doc/user/group/saml_sso/img/azure_configure_group_claim.png Binary files differnew file mode 100644 index 00000000000..9d8c5348273 --- /dev/null +++ b/doc/user/group/saml_sso/img/azure_configure_group_claim.png diff --git a/doc/user/group/saml_sso/img/okta_saml_settings.png b/doc/user/group/saml_sso/img/okta_saml_settings.png Binary files differnew file mode 100644 index 00000000000..9c774b72d66 --- /dev/null +++ b/doc/user/group/saml_sso/img/okta_saml_settings.png diff --git a/doc/user/group/saml_sso/img/okta_setting_username.png b/doc/user/group/saml_sso/img/okta_setting_username.png Binary files differnew file mode 100644 index 00000000000..5f87d14bb8b --- /dev/null +++ b/doc/user/group/saml_sso/img/okta_setting_username.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 80e7a5903fa..25060f8e749 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -99,7 +99,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. +The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. ### SSO enforcement @@ -131,6 +131,8 @@ SSO has the following effects when enabled: - Git activity originating from CI/CD jobs do not have the SSO check enforced. - Credentials that are not tied to regular users (for example, project and group access tokens, and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). +- When the **Enforce SSO-only authentication for Git and Dependency Proxy activity for this group** option is enabled, any API endpoint that involves Git activity is under SSO + enforcement. For example, creating or deleting a branch, commit, or tag. When SSO is enforced, users are not immediately revoked. If the user: @@ -174,7 +176,7 @@ The recommended attributes and claims settings are: If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. -See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory) for an example configuration. +See our [example configuration page](example_saml_config.md#azure-active-directory). ### Google Workspace setup notes @@ -191,7 +193,7 @@ with the notes below for consideration. NOTE: Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for [configuring SAML](#configure-gitlab), download the certificate and calculate -the SHA1 certificate fingerprint. +the SHA1 certificate fingerprint using this sample command: `openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-domain.com.pem"`. The recommended attributes and claims settings are: @@ -206,7 +208,7 @@ For NameID, the following settings are recommended: When selecting **Verify SAML Configuration** on the GitLab SAML SSO page, disregard the warning recommending setting the NameID format to "persistent". -See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#google-workspace) for an example configuration. +See our [example configuration page](example_saml_config.md#google-workspace). ### Okta setup notes @@ -445,7 +447,7 @@ To generate a SAML Response: ### Verifying configuration -For convenience, we've included some [example resources](../../../administration/troubleshooting/group_saml_scim.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. +For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. ### Verifying NameID diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 04aa99e08af..7962f171166 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -82,7 +82,7 @@ For a list of required attributes, refer to the [SCIM API documentation](../../. | `userPrincipalName` | `emails[type eq "work"].value` | | | `mailNickname` | `userName` | | -For guidance, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). +For guidance, you can view [an example configuration](example_saml_config.md#azure-active-directory). 1. Below the mapping list select **Show advanced options > Edit attribute list for AppName**. 1. Ensure the `id` is the primary and required field, and `externalId` is also required. @@ -106,7 +106,7 @@ Before you start this section: - Check that you are using Okta [Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This product tier is required to use SCIM on Okta. To check which Okta product you are using, check your signed Okta contract, contact your Okta AE, CSM, or Okta support. - Complete the [GitLab configuration](#gitlab-configuration) process. -- Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), as described in the [Okta setup notes](index.md#okta-setup-notes). +- Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/), as described in the [Okta setup notes](index.md#okta-setup-notes). - Check that your Okta SAML setup matches our documentation exactly, especially the NameID configuration. Otherwise, the Okta SCIM app may not work properly. After the above steps are complete: @@ -220,6 +220,8 @@ It is important that this SCIM `id` and SCIM `externalId` are configured to the ### How do I verify user's SAML NameId matches the SCIM externalId +Admins can use the Admin Area to [list SCIM identities for a user](../../admin_area/#user-identities). + Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list-of-scim-provisioned-users) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. |
