Table of Contents#

1. Prerequisites
2. Create a Realm in Keycloak
3. Create a Client for GitLab
4. Retrieve the Client Secret
5. Verify the Realm Signature Algorithm
6. Configure GitLab (gitlab.rb)
7. Auto-Link Existing Accounts by Email
8. Reconfigure & Test Login
9. Troubleshooting

1. Prerequisites#

• Keycloak is up and running, accessible over HTTPS (e.g., https://sso.example.com). GitLab requires OIDC Identity Providers to be accessed over HTTPS — plain HTTP is not supported.
• GitLab Omnibus (Self-Managed) is installed and accessible over HTTPS (e.g., https://gitlab.example.com).
• Admin access to the Keycloak Admin Console.
• Root/sudo access to the GitLab server for editing /etc/gitlab/gitlab.rb.

2. Create a Realm in Keycloak#

Production application clients should not be placed in the master realm — that realm is recommended only for Keycloak’s own superadmin accounts.

1. Log in to https://sso.example.com/admin/.
2. Click the realm dropdown in the top-left corner → Create realm.
3. Enter a Realm name, for example YOUR_REALM.
4. Click Create.

All subsequent steps are performed inside this realm.

NOTE

If you already have a realm set up from a previous integration (e.g., ArgoCD), you can reuse it. There is no need to create a new realm for each application — just create a new client within the existing realm.

3. Create a Client for GitLab#

1. Inside your realm, navigate to Clients → Create client.
2. General Settings
   • Client type: OpenID Connect
   • Client ID: gitlab
   • Click Next.
3. Capability config
   • Client authentication: On (this makes the client confidential, generating a client secret)
   • Authentication flow: check Standard flow only. Leave Direct access grants, Implicit flow, and other options unchecked — Standard flow (Authorization Code) is sufficient and the most secure choice for this use case.
   • Click Next, then Save.
4. On the Settings page of the newly created client:
   • Valid redirect URIs: https://gitlab.example.com/users/auth/openid_connect/callback
   • Valid post logout redirect URIs: https://gitlab.example.com/*
   • Web origins: https://gitlab.example.com
5. Click Save.

4. Retrieve the Client Secret#

1. Still on the gitlab client, open the Credentials tab.
2. Copy the Client secret value — this will be used in the gitlab.rb configuration.

5. Verify the Realm Signature Algorithm#

GitLab recommends tokens to be signed with a public-key algorithm (RS256) rather than a symmetric key (HS256), as it is more secure and easier to configure.

1. Navigate to Realm settings → Tokens tab.
2. Check the Default signature algorithm — ensure it is set to RS256 (this is Keycloak’s default and typically does not need to be changed).

6. Configure GitLab (gitlab.rb)#

Edit the GitLab configuration file:

1
sudo nano /etc/gitlab/gitlab.rb

Add the following block (replace identifier and secret with the Client ID and Client Secret from steps 3–4):

1
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
2
gitlab_rails['omniauth_block_auto_created_users'] = false
3

4
gitlab_rails['omniauth_providers'] = [
5
  {
6
    name: "openid_connect", # do not change — this is the internal provider name
7
    label: "Keycloak",      # the label displayed on the login button
8
    args: {
9
      name: "openid_connect",
10
      scope: ["openid", "profile", "email"],
11
      response_type: "code",
12
      issuer: "https://sso.example.com/realms/YOUR_REALM",
13
      client_auth_method: "query",
14
      discovery: true,
15
      uid_field: "preferred_username",
16
      pkce: true,
17
      client_options: {
18
        identifier: "gitlab",
19
        secret: "YOUR_CLIENT_SECRET",
20
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
21
      }
22
    }
23
  }
24
]

Key options explained:

• omniauth_allow_single_sign_on — enables automatic creation of new GitLab accounts (Just-In-Time provisioning) when a user logs in through Keycloak for the first time.
• omniauth_block_auto_created_users — when false, automatically created accounts are immediately active without requiring admin approval. Set to true if you want a GitLab admin to manually approve every new SSO account.
• discovery: true — GitLab automatically fetches all OIDC endpoints (authorization, token, userinfo, jwks) from https://sso.example.com/realms/YOUR_REALM/.well-known/openid-configuration, so there is no need to define them individually.
• pkce: true — enables PKCE (Proof Key for Code Exchange) as an additional security layer on the Authorization Code flow.
• uid_field: "preferred_username" — the field from the Keycloak token that GitLab uses as the unique user identifier.

7. Auto-Link Existing Accounts by Email#

If there are existing GitLab users whose email addresses match those that will be used for Keycloak login, add the following line so that GitLab links to the existing account instead of creating a new one:

1
gitlab_rails['omniauth_auto_link_user'] = ["openid_connect"]

Auto-linking matches based on email addresses that are verified on both sides. Without this line, a user with a matching email will still receive a separate, brand-new GitLab account.

8. Reconfigure & Test Login#

Apply the configuration changes:

1
sudo gitlab-ctl reconfigure

Once complete, open the GitLab login page:

1
https://gitlab.example.com/users/sign_in

A login button labeled Keycloak will appear below the standard login form. Click it to be redirected to the Keycloak login page, and after successful authentication, you will be redirected back to GitLab in a logged-in state.

WARNING

After SSO is enabled, every sign-in attempt is redirected to the OmniAuth provider, which means the standard local GitLab login will no longer be directly available from the main page. Make sure at least one OmniAuth user has administrator privileges before enabling this in production. Local login can still be accessed manually via https://gitlab.example.com/users/sign_in?auto_sign_in=false as an emergency fallback.

9. Troubleshooting#

Summary of the flow: create a dedicated realm in Keycloak (or reuse an existing one) → register a gitlab client with Standard Flow only → copy the client secret → add the configuration to gitlab.rb with the matching issuer, identifier, and secret → run gitlab-ctl reconfigure → test login via the Keycloak button on the GitLab sign-in page.