SAML single sign-on for GitLab Dedicated

• Tier: Ultimate
• Offering: GitLab Dedicated

You can configure SAML single sign-on (SSO) for your GitLab Dedicated instance for up to ten identity providers (IdPs).

The following SAML SSO options are available:

• Request signing
• SAML SSO for groups
• Group sync

These instructions apply only to SSO for your GitLab Dedicated instance. For Switchboard, see configure single sign-on for Switchboard.

Prerequisites

• You must set up the identity provider before you can configure SAML for GitLab Dedicated.
• To configure GitLab to sign SAML authentication requests, you must create a private key and public certificate pair for your GitLab Dedicated instance.

Add a SAML provider with Switchboard

To add a SAML provider for your GitLab Dedicated instance:

1. Sign in to Switchboard.
2. At the top of the page, select Configuration.
3. Expand SAML providers.
4. Select Add SAML provider.
5. In the SAML label text box, enter a name to identify this provider in Switchboard.
6. Optional. To configure users based on SAML group membership or use group sync, complete these fields:
   • SAML group attribute
   • Admin groups
   • Auditor groups
   • External groups
   • Required groups
7. In the IdP cert fingerprint text box, enter your IdP certificate fingerprint. This value is a SHA1 checksum of your IdP's X.509 certificate fingerprint.
8. In the IdP SSO target URL text box, enter the URL endpoint on your IdP where GitLab Dedicated redirects users to authenticate with this provider.
9. From the Name identifier format dropdown list, select the format of the NameID that this provider sends to GitLab.
10. Optional. To configure request signing, complete these fields:
    • Issuer
    • Attribute statements
    • Security
11. To start using this provider, select the Enable this provider checkbox.
12. Select Save.
13. To add another SAML provider, select Add SAML provider again and follow the steps above. You can add up to ten providers.
14. Scroll up to the top of the page. The Initiated changes banner explains that your SAML configuration changes are applied during the next maintenance window. To apply the changes immediately, select Apply changes now.

After the changes are applied, you can sign in to your GitLab Dedicated instance using this SAML provider. To use group sync, configure the SAML group links.

Verify your SAML configuration

To verify that your SAML configuration is successful:

1. Sign out and go to your GitLab Dedicated instance's sign-in page.
2. Check that the SSO button for your SAML provider appears on the sign-in page.
3. Go to the metadata URL of your instance (https://INSTANCE-URL/users/auth/saml/metadata). The metadata URL shows information that can simplify configuration of your identity provider and helps validate your SAML settings.
4. Try signing in through the SAML provider to ensure the authentication flow works correctly.

If troubleshooting information, see troubleshooting SAML.

Add a SAML provider with a Support Request

If you are unable to use Switchboard to add or update SAML for your GitLab Dedicated instance, then you can open a support ticket:

1. To make the necessary changes, include the desired SAML configuration block for your GitLab application in your support ticket. At a minimum, GitLab needs the following information to enable SAML for your instance:

   • IDP SSO Target URL
   • Certificate fingerprint or certificate
   • NameID format
   • SSO login button description

   "saml": {
     "attribute_statements": {
         //optional
     },
     "enabled": true,
     "groups_attribute": "",
     "admin_groups": [
       // optional
     ],
     "idp_cert_fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
     "idp_sso_target_url": "https://login.example.com/idp",
     "label": "IDP Name",
     "name_identifier_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
     "security": {
       // optional
     },
     "auditor_groups": [
       // optional
     ],
     "external_groups": [
       // optional
     ],
     "required_groups": [
       // optional
     ],
   }

2. After GitLab deploys the SAML configuration to your instance, you are notified on your support ticket.

3. To verify the SAML configuration is successful:

   • Check that the SSO login button description is displayed on your instance's login page.
   • Go to the metadata URL of your instance, which is provided by GitLab in the support ticket. This page can be used to simplify much of the configuration of the identity provider, as well as manually validate the settings.

Request signing

If SAML request signing is desired, a certificate must be obtained. This certificate can be self-signed which has the advantage of not having to prove ownership of an arbitrary Common Name (CN) to a public Certificate Authority (CA).

Because SAML request signing requires certificate signing, you must complete these steps to use SAML with this feature enabled.

To enable SAML request signing:

1. Open a support ticket and indicate that you want request signing enabled.
2. GitLab will work with you on sending the Certificate Signing Request (CSR) for you to sign. Alternatively, the CSR can be signed with a public CA.
3. After the certificate is signed, you can then use the certificate and its associated private key to complete the security section of the SAML configuration in Switchboard.

Authentication requests from GitLab to your identity provider can now be signed.

SAML groups

With SAML groups you can configure GitLab users based on SAML group membership.

To enable SAML groups, add the required elements to your SAML configuration in Switchboard or to the SAML block you provide in a support ticket.

Group sync

With group sync, you can sync users across identity provider groups to mapped groups in GitLab.

To enable group sync:

1. Add the required elements to your SAML configuration in Switchboard or to the SAML configuration block you provide in a support ticket.
2. Configure the Group Links.