GitLab – SAML OmniAuth Setup

How to set-up SAML on a self-managed Omnibus GitLab Instance?

I recently set up a self-managed GitLab instance on my CentOS 7 server and wanted to utilize the feature for Single-Sign-On using SAML 2.0.

I follow the documentation provided by GitLab, however, I found it a bit difficult because I ran into a few errors while following the document.

Since you are on this page, I am pretty sure, you ran into similar errors or the documentation was not clear for you either.

I will walk you through the step-by-step setup of SAML SSO on your self-managed GitLab instance. If you feel that something is missing in the documentation, feel free to comment below and I will update the document soon.

Things to Consider before starting:

1. GitLab is configured as a SAML 2.0 Service Provider (SP).

2. During your GitLab installation, make sure that your instance is configured with HTTPS. If it is not enabled, you can follow this document.

3. If you have an ADFS server, you need idp_cert_fingerprint and idp_sso_target_url of your ADFS Server. Download the metadata.xml file from your AD FS server and extract the signing certificate from the metadata file. Add this file on the decoder website to extract the SHA1 fingerprint.

SAML Configuration in Omnibus GitLab

1. Open your GitLab server and open the configuration File:

# sudo vim /etc/gitlab/gitlab.rb

2. In the gitlab.rb file, either search for OmniAuth Settings or search below line 400. Allow users to sign-up using SAML.

Add the following lines:

gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false

3. In order to link GitLab existing users with SAML user, you can add this line:

gitlab_rails['omniauth_auto_link_saml_user'] = true

Note:
Make sure that the NameID and Email Address of each SAML user is fixed in your ADFS settings.

4. Add the following settings to your file:

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
             assertion_consumer_service_url: 'https://gitlab.yourdomain.com/users/auth/saml/callback',
             idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
             idp_sso_target_url: 'https://adfs.yourdomain.com/adfs/ls',
             issuer: 'https://gitlab.yourdomain.com',
             name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
           },
    label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
  }
]

5. Change assertion_consumer_service_url to match the HTTPS URL of your GitLab instance. At the end of the URL, add users/auth/saml/callback.

6. The idp_cert_fingerprint and idp_sso_target_url are gathered from ADFS server as mentioned earlier.

7. The issuer is the HTTPS URL of your GitLab instance:

https://gitlab.yourdomain.com.

If you don’t have a URL instance, then it must be an IP address of the server where you installed the GitLab instance.

8. Once these settings are updated, save and close the gitlab.rb file. Next, reconfigure the GitLab instance using the following command:

# sudo gitlab-ctl reconfigure

9. If there is no error in the server, you can go to your HTTPs URL and check if SAML option is available of not. Sometimes there is a delay or cache stored in your browser. Try the private mode of your browser. Otherwise, you can restart your GitLab instance:

# sudo gitlab-ctl restart

If everything is done correctly, you should be able to move to the next step. Otherwise, look for common errors.

Setup ADFS – Relying Party Trust

We are going to add a new relying party trust in AD FS Management snap-in using federation metadata.

1. You need Administrator access to the AD FS server in order to complete this step.

2. Open Server Manager, click on Tools, and select AD FS Management.

3. Under Actions, select Add Relying Party Trust

4. On the Welcome page, select Claims aware and click on Start:

5. Select Import data about the relying party published online or on a local network. It will prompt for a Federation metadata URL. This URL is your GitLab Server HTTPs URL + /users/auth/saml/metadata. It should look as follows:

https://gitlab.yourdomain.com/users/auth/saml/metadata

6. On the next page, Specify Display Name and type a description for your reference.

7. On the next page, select Permit all users to access this relying party and click on Next:

Finally, review the settings and click on Next to save your relying party trust information.

You can go to your website URL and you should have SAML option or your label Name:

Common Errors faced during GitLab SAML Configuration

GitLab Rails Cache

1. One of the errors that I faced during the configuration of gitlab.rb file was when I ran the following command:

# sudo gitlab-ctl reconfigure

This error was related to the cache stored in the Gitlab. You can run this command to clear out the cache:

# sudo clear the gitlab-rails cache

Error 502: GitLab is taking too much time to respond

This error appears when either the gitlab.rb configuration is wrong or it is not updated on the server.

In my case, I followed these steps to mitigate the issue:

1. Restart the Server:

# sudo gitlab-ctl restart

2. Check the gitlab.rb file again. I found this issue in my file:

The file had a syntax error. It should look like this:

Once I changed the setting, the error was fixed.

Let me know if you have a different error and we can update our document.

Related posts:

How to Backup and Restore Omnibus GitLab Privacy Policy