ContextQMD
Back to Gitlabhq

Tutorial: Set up SAML SSO for GitLab.com groups

doc/tutorials/auth/saml_saas.md

19.0.017.9 KB
Original Source

This tutorial walks you through setting up SAML single sign-on (SSO) for a GitLab.com group using an Identity Provider (IdP) such as Okta or Microsoft Entra ID. When you finish, members of your group can sign in to GitLab through the IdP.

In this tutorial, you:

  1. Configure SAML through an IdP application.
  2. Configure SAML SSO in your GitLab group.
  3. Test the SAML connection.
  4. Link a user account to verify the setup.

Before you begin

Prerequisites:

  • You must have the Owner role for a GitLab Premium or Ultimate group on GitLab.com.
  • You must have administrator access to your IdP.
  • You must have at least one test user account in your IdP.
  • You should be familiar with single sign-on concepts.

Time to complete: 20-30 minutes

Step 1: Gather GitLab information

Before you can set up anything in your IdP, you must get some connection details from GitLab that tell your IdP how to communicate with your GitLab group.

To gather the GitLab information:

  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > SAML SSO.
  3. Note these values:
    • Identifier
    • Assertion consumer service URL
    • GitLab single sign-on URL

Step 2: Create an IdP application

Now that you have your GitLab details ready, create an application in your IdP. This application maps the GitLab information to the IdP and configures how user information flows between the two systems.

To create an IdP application:

{{< tabs >}}

{{< tab title="Okta" >}}

  1. Sign in to Okta as an administrator.
  2. In the Admin Console, select Applications > Applications.
  3. Select Create App Integration.
  4. In the Sign-in method section, select SAML 2.0.
  5. Select Next.
  6. On the General Settings tab, enter a name for your application. For example, GitLab SAML.
  7. Select Next.
  8. On the Configure SAML tab, complete the fields with the values from Step 1:
    • Single sign-on URL: Enter the Assertion consumer service URL.
    • Select the Use this for Recipient URL and Destination URL checkbox.
    • Audience URI (SP Entity ID): Enter the Identifier.
  9. Configure the name identifier:
    • Application username (NameID): Select Custom and enter user.getInternalProperty("id").
    • Name ID Format: Select Persistent.
  10. In the Attribute Statements (optional) section, add this attribute:
    • Name: email
    • Value: user.email
  11. Scroll down to Application Login Page settings:
    • Login page URL: Enter the GitLab single sign-on URL.
  12. Select Next.
  13. On the Feedback tab, select the appropriate options for your use case.
  14. Select Finish.

The SAML application is created in Okta.

[!note] For more information about SAML attributes and advanced configuration options, see the SAML SSO documentation.

{{< /tab >}}

{{< tab title="Entra ID" >}}

  1. Sign in to the Microsoft Entra admin center.
  2. Select Identity > Applications > Enterprise applications.
  3. Select New application.
  4. Select Create your own application.
  5. In the dialog, complete the fields:
    • Name: Enter a name for your application. For this tutorial, use GitLab SAML.
    • Select Integrate any other application you don't find in the gallery (Non-gallery).
  6. Select Create.

The enterprise application is created in Microsoft Entra ID.

  1. In your enterprise application, select Single sign-on from the left sidebar.
  2. Select SAML as the single sign-on method.
  3. In the Basic SAML Configuration section, select Edit.
  4. Complete the fields with the values from Step 1:
    • Identifier (Entity ID): Enter the Identifier.
    • Reply URL (Assertion Consumer Service URL): Enter the Assertion consumer service URL.
    • Sign on URL: Enter the GitLab single sign-on URL.
  5. Select Save.
  6. In the User Attributes & Claims section, select Edit.
  7. Select Add new claim and complete the fields:
    • Name: Enter email.
    • Source attribute: Select user.mail.
  8. Select Save.
  9. Edit the Unique User Identifier (Name ID) claim:
    • Select the existing Unique User Identifier claim.
    • Source attribute: Select user.objectid.
    • Name identifier format: Select Persistent.
  10. Select Save.

[!note] For more information about SAML attributes and advanced configuration options, see the SAML SSO documentation.

{{< /tab >}}

{{< tab title="Google Workspace" >}}

  1. Sign in to the Google Admin console.
  2. Select Apps > Web and mobile apps.
  3. Select Add App > Add custom SAML app.
  4. In the App Details page, enter a name for your application. For example, GitLab SAML.
  5. Select Continue.
  6. On the Google Identity Provider details page, leave this page open. You need these values in Step 3.
  7. Select Continue.
  8. On the Service provider details page, complete the fields with the values from Step 1:
    • ACS URL: Enter the Assertion consumer service URL.
    • Entity ID: Enter the Identifier.
    • Start URL: Enter the GitLab single sign-on URL.
    • Name ID format: Select EMAIL.
    • Name ID: Select Basic Information > Primary email.
  9. Select Continue.
  10. On the Attribute mapping page, add these attributes:
    • Google Directory attribute: Primary email, App attribute: email
    • Google Directory attribute: First name, App attribute: first_name
    • Google Directory attribute: Last name, App attribute: last_name
  11. Select Finish. The SAML application is created in Google Workspace.
  12. Turn on the application for your users:
    • On the User access section, select ON for everyone.
    • Select Save.

For more information about SAML attributes and advanced configuration options, see the SAML SSO documentation.

{{< /tab >}}

{{< tab title="OneLogin" >}}

  1. Sign in to OneLogin as an administrator.
  2. Select Administration > Applications.
  3. Select Add App.
  4. Search for SAML Test Connector (Advanced) and select it.
  5. In the Display Name field, enter a name for your application. For example, GitLab SAML.
  6. Select Save.
  7. Select the Configuration tab.
  8. Complete the fields with the values from Step 1:
    • Audience (EntityID): Enter the Identifier.
    • Recipient: Enter the Assertion consumer service URL.
    • ACS (Consumer) URL Validator: Enter the Assertion consumer service URL as a regex. For example, https://gitlab\.com/groups/your-group/-/saml/callback.
    • ACS (Consumer) URL: Enter the Assertion consumer service URL.
    • Login URL: Enter the GitLab single sign-on URL.
  9. Select Save.
  10. Select the Parameters tab.
  11. Add the required attribute by selecting Add parameter:
    • Field name: email, Value: Email
  12. For NameID, select OneLogin ID in the value field.
  13. Select Save.
  14. Select the Access tab to assign users or roles to the application.

The SAML application is created in OneLogin.

For more information about SAML attributes and advanced configuration options, see the SAML SSO documentation.

{{< /tab >}}

{{< tab title="Keycloak" >}}

  1. Sign in to Keycloak as an administrator.
  2. Go to Clients and select Create client.
  3. In the General Settings page, select SAML as the Client type.
  4. Complete the fields with the values from Step 1:
    • Client ID: Enter the Identifier.
    • Valid redirect URIs: Enter the Assertion consumer service URL.
    • Assertion Consumer Service POST Binding URL: Enter the Assertion consumer service URL.
    • Home URL: Enter the GitLab single sign-on URL.
  5. Select Save.
  6. On the Settings tab, in the SAML capabilities section:
    • Name ID format: Select persistent.
    • Turn on the Force name ID format toggle.
    • Turn on the Force POST binding toggle.
    • Turn on the Include AuthnStatement toggle.
  7. In the Signature and Encryption section, turn on the Sign documents toggle.
  8. On the Keys tab, make sure all sections are disabled.
  9. On the Client scopes tab:
    • Select the client scope for GitLab.
    • Select Configure a new mapper, and select User Attribute in the window that opens.
    • On the Add mapper page, set the Name, User Attribute, and SAML Attribute Name fields to email.
    • Select Save.

The SAML client is created in Keycloak.

[!note] For more information about SAML attributes and advanced configuration options, see the SAML SSO documentation.

{{< /tab >}}

{{< tab title="AWS IAM Identity Center" >}}

  1. Sign in to the AWS IAM Identity Center console.

  2. Select Applications, then select Add application.

  3. Select I have an application I want to set up.

  4. Select SAML 2.0 as the application type.

  5. Select Next.

  6. On the Configure application page, enter a display name for your application. For example, GitLab SAML.

  7. Complete the fields with the values from Step 1:

    • Application ACS URL: Enter the Assertion consumer service URL.
    • Application SAML audience: Enter the Identifier.
    • Application start URL: Enter the GitLab single sign-on URL.

  8. Under Attribute mappings, configure these attributes:

    • Subject: ${user:email}, Format: unspecified
    • email: ${user:email}, Format: unspecified
    • first_name: ${user:givenName}, Format: unspecified
    • last_name: ${user:familyName}, Format: unspecified

    [!warning] To avoid authentication errors for existing GitLab users, do not set the format to persistent or transient.

  9. Select Submit. The SAML application is created in AWS IAM Identity Center.

  10. Assign users to the GitLab application.

For more information about SAML attributes and advanced configuration options, see the SAML SSO documentation.

[!note] AWS IAM Identity Center defaults to IdP-initiated login. To link existing GitLab accounts, users must sign in from the GitLab single sign-on URL or the Application start URL.

{{< /tab >}}

{{< /tabs >}}

Step 3: Gather the connection details

Now retrieve the information that GitLab needs to send authentication requests to the IdP.

To gather the connection details:

{{< tabs >}}

{{< tab title="Okta" >}}

  1. In your Okta SAML app, select the Sign On tab.

  2. On the right side, select View SAML setup instructions.

  3. Note the Identity Provider Single Sign-On URL.

  4. Generate a certificate fingerprint:

    1. In the X.509 Certificate field, copy the text and save it locally.
    2. Open a terminal and go to the directory where you saved the certificate file.
    3. Run this command to generate the certificate fingerprint:
    shell
       # Replace `<certificate_filename>` with the actual filename of your downloaded certificate.
   # You might need to install OpenSSL or use an alternative method to generate the fingerprint.
    openssl x509 -noout -fingerprint -sha256 -in <certificate_filename>.crt

  5. Copy the fingerprint value after SHA256 Fingerprint=. The fingerprint looks like A1:B2:C3:D4:E5:F6:....

{{< /tab >}}

{{< tab title="Entra ID" >}}

  1. In your Entra ID enterprise application, select Single sign-on.
  2. In the Set up GitLab SAML section, note the Login URL. The name of this section is based on the name of your enterprise application.
  3. In the SAML Signing Certificate section, note the Thumbprint value. The thumbprint looks like A1B2C3D4E5F6....

{{< /tab >}}

{{< tab title="Google Workspace" >}}

  1. In your Google Workspace SAML app, go to the app details page.
  2. Note the SSO URL value.
  3. Note the SHA-256 fingerprint value displayed for the certificate. The fingerprint looks like A1:B2:C3:D4:E5:F6:....

{{< /tab >}}

{{< tab title="OneLogin" >}}

  1. In your OneLogin SAML app, select the SSO tab.
  2. Note the SAML 2.0 Endpoint (HTTP) URL.
  3. In the X.509 Certificate section, select View Details.
  4. Note the SHA-256 Fingerprint value. The fingerprint looks like A1:B2:C3:D4:E5:F6:....

{{< /tab >}}

{{< tab title="Keycloak" >}}

  1. In your Keycloak SAML client, in the Action dropdown list, select Download adapter config.
  2. In the Download adapter config dialog, select mod-auth-mellon from the dropdown list.
  3. Select Download.
  4. Extract the downloaded archive and open idp-metadata.xml.
  5. Locate the <md:SingleSignOnService> tag and note the value of the Location attribute.
  6. Generate a certificate fingerprint:
    1. Locate the <ds:X509Certificate> tag and copy the value to a separate file.
    2. Convert the value to PEM format. Add -----BEGIN CERTIFICATE----- at the beginning of the file and -----END CERTIFICATE----- at the end of the file as new lines.

{{< /tab >}}

{{< tab title="AWS IAM Identity Center" >}}

  1. In your AWS IAM Identity Center SAML app, select the application you created.

  2. In the IAM Identity Center SAML metadata section, note the IAM Identity Center sign-in URL.

  3. Download the certificate.

  4. Generate a certificate fingerprint:

    1. Open a terminal and go to the directory where you saved the certificate file.
    2. Run this command to generate the certificate fingerprint:
    shell
    # Replace `<certificate_filename>` with the actual filename of your downloaded certificate.
# You might need to install OpenSSL or use an alternative method to generate the fingerprint.
openssl x509 -noout -fingerprint -sha256 -in <certificate_filename>.pem

  5. Copy the fingerprint value after SHA1 Fingerprint=. The fingerprint looks like A1:B2:C3:D4:E5:F6:....

[!note] AWS IAM Identity Center requires a SHA1 fingerprint. For more information, see the SAML SSO documentation.

{{< /tab >}}

{{< /tabs >}}

Step 4: Configure SAML SSO in GitLab

You have everything you need to complete the connection. Return to GitLab and enter the connection details to turn on SAML authentication for your group.

To configure SAML:

  1. Return to your GitLab group.
  2. Select Settings > SAML SSO.
  3. In the Configuration section, complete the fields:
    • Identity provider single sign-on URL: Enter the URL from Step 3.
    • Certificate fingerprint: Enter the fingerprint from Step 3.
  4. Select the Enable SAML authentication for this group checkbox.
  5. From the Default membership role dropdown list, select Minimal Access.
  6. Select Save changes.

The basic SAML connection is now configured.

[!note] You can set the default membership role to any role. All new users are assigned this role when they first sign in through SAML. Setting the default to Minimal Access and promoting users later reduces the risk of users having too much access.

Step 5: Test the SAML configuration

Before you invite your team, verify that the connection works correctly.

To test the SAML configuration:

  1. On the Settings > SAML SSO page, select Verify SAML Configuration. GitLab redirects you to the IdP.
  2. Sign in with your IdP credentials.
  3. Confirm that the IdP redirects you back to GitLab.

If you see errors, see the troubleshooting guide.

The configuration looks good. Now test the experience from a user's perspective by linking a test account like your team members do when they first connect to GitLab through the IdP.

To test user account linking:

  1. Sign out of GitLab.
  2. In a different browser or incognito window, sign in to your test GitLab account.
  3. Go to the GitLab single sign-on URL you noted in Step 1.
  4. Select Authorize.
  5. When prompted, sign in with your IdP credentials.
  6. Verify you are redirected to the GitLab group.

Congratulations! You have successfully linked a SAML identity to a GitLab account.

Step 7: Optional: Turn on SSO enforcement

You have a working SAML setup. As an optional final step, you can turn on SSO enforcement. SSO enforcement requires all group members to authenticate through the IdP, which strengthens security. However, it prevents access through other authentication methods.

To turn on SSO enforcement:

  1. In the top bar, select Search or go to and find your group.
  2. In the left sidebar, select Settings > SAML SSO.
  3. Select Enforce SSO-only authentication for web activity for this group.
  4. Select Save changes.

After you enable enforcement, all group members must sign in through the IdP before they can access group resources.

Next steps

You've successfully set up SAML SSO for your GitLab group! Here are some things you might want to do next:

Troubleshooting

If you encounter issues during this tutorial, see the following resources: