How to Configure Gitlab with Keycloak.

share on:
Configure Gitlab with Keycloak.

This post shows how you can use Keycloak with SAML 2.0 as an OmniAuth Provider for GitLab CE and EE versions. To setup Gitlab with existing nginx. please visit this link.
You can visit this link to check Keycloak.


  • Running and working Keycloak instance(s).
  • Running GitLab instance and SSH root access.

Our Keycloak server is :

Our Gitlab server is :

Step 1 – Create SAML Client in Keycloak.

Our realm name is Apps. Yours can be different. So change apps with your own realm name wherever possible.

Configure Gitlab with Keycloak.

NOTE Replace with your actual GitLab hostname, example

Go to the Clients page and click the Create button in the right upper corner.

Configure Gitlab with Keycloak.

Step 2 – Configure newly created SAML Client in Keycloak for Gitlab.

Go to clients -> -> settings tab.

Client setup for Gitlab.
gitlab client setup for keycloak
Keycloak client setup.

Roles Tab.

Gitlab CE users has limited functionality available with keycloak. We will create a group name external in Keycloak for Gitlab.

Configure Gitlab with Keycloak.

Configure Gitlab with Keycloak.

Mappers Tab

Mappers allows you to map user information to parameters in the SAML 2.0 request for GitLab. For example a name mapper will be used to map the Username into the request for GitLab.

We will create few mappers for Gitlab in Keycloak.

Start with Name mapper.

Configure Gitlab with Keycloak.

mappers setup keycloak.

Repeat the same process and create other mappers for email, first_name, last_name and roles as suggested below.

  • Name: name
    • Mapper Type: User Property
    • Property: Username
    • Friendly Name: Username
    • SAML Attribute Name: name
    • SAML Attribute NameFormat: Basic
  • Name: email
    • Mapper Type: User Property
    • Property: Email
    • Friendly Name: Email
    • SAML Attribute Name: email
    • SAML Attribute NameFormat: Basic
  • Name: first_name
    • Mapper Type: User Property
    • Property: FirstName
    • Friendly Name: First Name
    • SAML Attribute Name: first_name
    • SAML Attribute NameFormat: Basic
  • Name: last_name
    • Mapper Type: User Property
    • Property: LastName
    • Friendly Name: Last Name
    • SAML Attribute Name: name
    • SAML Attribute NameFormat: Basic
  • Name: roles
    • Mapper Type: Role list
    • Role attribute name: roles
    • Friendly Name: Roles
    • SAML Attribute NameFormat: Basic
    • Single Role Attribute: On

All of the mappers have “Consent Required” set to Off.

End result should be like this.

Create mappers for gitlab.

Scope Tab.

Set full Scope Allowed to ON.

Configure Gitlab with Keycloak.

Step 3: Copy Certificate from Realm.

Go to Realm -> Keys amd Download the public certificate.

Realm certificate download.

Step 4: Setup Gitlab.

SSH into the gitlab server and take backup of gitlab.rb.

cd /etc/gitlab/

cp -a gitlab.rb{,.bak-working-$(date +%F)}

Now open the gitlab.rb in vim or nano and paste the following lines at the end of file.

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
# gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
gitlab_rails['omniauth_block_auto_created_users'] = false
# gitlab_rails['omniauth_auto_link_ldap_user'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
      name: 'saml',
      args: {
               assertion_consumer_service_url: '',
               idp_cert:  "-----BEGIN CERTIFICATE-----
CSH6IwAilsTlJQZd75Mw/kM==\n-----END CERTIFICATE-----\n",
               idp_sso_target_url: '',
               issuer: '',
               name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
      label: 'Keycloak Login'

Step 5: Reconfigure the Gitlab.

gitlab-ctl reconfigure

After that you can go to your Gitlab server and just below the sing in tab you will have another option of

Sign in with

That’s all. We have properly configure gitlab with Keycloak. Thanks

share on:


Hello there, My name is Rishi Guleria and I work as a Linux system administrator. I have created this blog to share what I have learned so far and to learn new things. Don't forget to leave the feedback. Have a great day. :)

1 Comment

  1. Hi!
    I’ve found very useful your article. Thx so much!
    In step 2 you say ” Gitlab CE users has limited functionality available with keycloak. We will create a group name external in Keycloak for Gitlab.”
    Which are those limitations?

Leave a Response

share on: