Gitlab SAML to Keycloak Setup

Integrating Keycloak with Gitlab SAML makes it easier to manage users in an organization from a central point. You could manage separate accounts on Gitlab, but for us it makes sense to utilize Keycloak as we are already using it for other applications.

The first step is to create a Gitlab SAML client in the Keycloak dashboard. With the correct realm selected, navigate to the Clients configuration page and click the create button to add a new client.

Add client:

 Client ID:        gitlab
 Client Protocol:  saml

Note: Keep track of the client ID as that will need to match in the Gitlab configuration.

Next modify the newly created client and change whats needed:

 Client Signature Required:   OFF
 Force Name ID Format:        ON
 Name ID Format:              email
 Valid Redirect URIs:         https://gitlab.example.com/*
 Base URL:                    https://gitlab.example.com/users/auth/saml/callback

Note: According to the Gitlab Security, it is important to force the name ID format.

Next navigate to the Mappers tab and apply the Assertions described here:

 Name:                      email
 Mapper Type:               User Property
 Property:                  Email
 Friendly Name:             email
 Saml Attribute Name:       email

 Name:                      username
 Mapper Type:               User Property
 Property:                  Username
 Friendly Name:             username
 Saml Attribute Name:       username

 Name:                      first_name
 Mapper Type:               User Property
 Property:                  FirstName
 Friendly Name:             first_name
 Saml Attribute Name:       first_name

 Name:                      last_name
 Mapper Type:               User Property
 Property:                  LastName
 Friendly Name:             last_name
 Saml Attribute Name:       last_name

The next part can be a little tricky. You could add the full certificate to the idp_cert property, but I like to use the fingerprint as this looks nicer. We need the SHA1 hash of the certificate used for the Keycloak realm, but Keycloak's certificate is formatted in a way that makes it a little harder. Under Realm Settings -> Keys locate the Certificate button for the RSA certificate.

You can get the SHA1 hash by pasting this into the terminal:

read -p "Paste Certificate: " CERT;echo -e "-----BEGIN CERTIFICATE-----\n$CERT\n-----END CERTIFICATE-----" | openssl x509 -noout -fingerprint -sha1

Paste the cert displayed from Keycloak into the input of the above script. You should see something like:

SHA1 Fingerprint=8F:F3:20:F7:73:DE:42:85:9B:F9:1E:BF:35:79:46:53:4B:A1:E3:18

Now for the Gitlab part which can be explained in more detail here. There are a couple properties to take note:

• issuer must match the SAML Client ID name in Keycloark as mentioned above
• idp_cert_fingerprint is the SHA1 hash in previous step

On the Gitlab server edit /etc/gitlab/gitlab.rb and ensure the properties exist with the appropriate changes:

gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
{
  name: 'saml',
  args: {
           assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
           idp_cert_fingerprint: '8F:F3:20:F7:73:DE:42:85:9B:F9:1E:BF:35:79:46:53:4B:A1:E3:18',
           idp_sso_target_url: 'https://keycloak.example.com/auth/realms/REALM/protocol/saml',
           issuer: 'gitlab',
           name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
         },
  label: 'Provider name' # optional label for SAML login button, defaults to "Saml"
}]

Don't forget to reconfigure Gitlab:

gitlab-ctl reconfigure

You should now be able to login with Keycloak with the newly added SAML label created above!