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!