Gitlab SAML to Keycloak Setup

Introduction

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.

Setting up Keycloak

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:                      display_name
 Mapper Type:               User Property
 Property:                  username
 Friendly Name:             Display Name
 Saml Attribute Name:       display_name

 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

These will show up in the SAML assertion as attributes and will be mapped to GitLab user attributes via attribute statements (see below). If you don’t define these attributes auto-creation of users that log in using Keycloak will fail.

Getting the realm’s certificate SHA1 fingerprint

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

Configuring GitLab to use Keycloak SAML authentication

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_auto_link_saml_user'] = true
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_providers'] = [
  { "args" =>
    { "assertion_consumer_service_url" => 
        "https://gitlab.example.org/users/auth/saml/callback",
      "attribute_statements" =>
        { "email"      => ["email"],
          "first_name" => ["first_name"],
          "last_name"  => ["last_name"],
          "name"       => ["display_name"],
          "nickname"   => ["display_name"]
        },
      "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.org/auth/realms/EXAMPLE.ORG/protocol/saml",
      "issuer" => "gitlab",
      "name_identifier_format" =>
        "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    },
    "label" =>"Keycloak",
    "name" =>"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!