• Activate SAML with Switchboard
• Activate SAML with a Support Request
• Request signing
• SAML groups
• Group sync

SAML single sign-on for GitLab Dedicated

You can configure SAML single sign-on (SSO) for your GitLab Dedicated instance. Optionally, you can configure more than one SAML identity provider (IdP).

The following SAML SSO options are available:

• Request signing
• SAML SSO for groups
• Group sync

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.

Activate SAML with Switchboard

To activate SAML for your GitLab Dedicated instance:

1. Sign in to Switchboard.
2. At the top of the page, select Configuration.
3. Expand SAML Config.
4. Turn on the Enable toggle.
5. Complete the required fields:
   • SAML label
   • IdP cert fingerprint
   • IdP SSO target URL
   • Name identifier format
6. To configure users based on SAML group membership or use group sync, complete the following fields:
   • SAML group attribute
   • Admin groups
   • Auditor groups
   • External groups
   • Required groups
7. To configure SAML request signing, complete the following fields:
   • Issuer
   • Attribute statements
   • Security
8. Select Save.
9. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window.
10. To use group sync, configure the SAML group links.
11. To verify the SAML configuration is successful:
    • Check that the SSO button description is displayed on your instance’s sign-in page.
    • Go to the metadata URL of your instance (https://INSTANCE-URL/users/auth/saml/metadata). This page can be used to simplify much of the configuration of the identity provider, and manually validate the settings.

Activate SAML with a Support Request

If you are unable to use Switchboard to activate or update SAML for your GitLab Dedicated instance, or if you need to configure more than one SAML IdP, 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).

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.