Guide: Configuring Keycloak OpenID Authentication with GitLab Helm Chart

This guide is for GitLab provided GitLab Helm chart and using Keyloack for OIDC Provider. But you can use any OpenID provider on small changes.

Keycloak Client Configuration

Before integrating GitLab with Keycloak via OpenID, ensure the following Keycloak client configuration is in place:

• Client scopes: Include the following scopes to support identity and group mapping: openid, profile, email, and groups
• Valid Redirect URI: Example: https://gitlab.example.local/users/auth/openid_connect/callback
• Web Origin: Example: https://gitlab.example.local

Ensure the redirect URI and web origin match your GitLab instance’s external URL. Misalignment will cause login failures or blocked requests due to CORS restrictions.

GitLab Environment Preparation

Add DNS records pointing to your GitLab ingress controller or load balancer:

• gitlab.example.local → resolves to GitLab web service
• registry.gitlab.example.local → resolves to GitLab container registry
• minio.gitlab.example.local (if using MinIO for object storage)
• pages.gitlab.example.local (if GitLab Pages is enabled)

1. Create a Kubernetes namespace for GitLab

kubectl create ns gitlab

2. Generate the OIDC configuration as a Kubernetes secret

Replace placeholders with actual values from your Keycloak client configuration.

kubectl create secret generic gitlab-keycloak \
-n gitlab \
--from-literal=provider='
name: "openid_connect"
label: "Keycloak"
args:
  name: "openid_connect"
  scope: ["openid", "profile", "email"]
  response_type: "code"
  issuer: "https://keycloak.example.local/realms/example-realm"
  discovery: true
  client_auth_method: "query"
  uid_field: "preferred_username"
  pkce: true
  client_options:
    identifier: "<CLIENT ID>"
    secret: "<CLIENT SECRET>"
    redirect_uri: "https://gitlab.example.local/users/auth/openid_connect/callback" 
  gitlab:
    groups_attribute: "groups"
    admin_groups: ["<ADMIN GROUP>"]
'

Gitlab OpenID configurations

These values demonstrate how to integrate OpenID with GitLab. Adjust them to match your environment.

Deploy GitLab with OpenID enabled

helm install gitlab gitlab/gitlab \
...
<ADD ENVIRONMENT VALUES>
...
--set global.appConfig.omniauth.enabled=true
--set global.appConfig.omniauth.autoSignInWithProvider=openid_connect
--set global.appConfig.omniauth.allowSingleSignOn[0]=openid_connect
--set global.appConfig.omniauth.blockAutoCreatedUsers=false
--set global.appConfig.omniauth.providers[0].secret=gitlab-keycloak
--set global.appConfig.omniauth.autoLinkUser=['openid_connect']
-n gitlab

Or Upgrade an existing GitLab deployment with OpenID

helm upgrade gitlab gitlab/gitlab \
...
<ADD ENVIRONMENT VALUES>
...
--set global.appConfig.omniauth.enabled=true
--set global.appConfig.omniauth.autoSignInWithProvider=openid_connect
--set global.appConfig.omniauth.allowSingleSignOn[0]=openid_connect
--set global.appConfig.omniauth.blockAutoCreatedUsers=false
--set global.appConfig.omniauth.providers[0].secret=gitlab-keycloak
--set global.appConfig.omniauth.autoLinkUser=['openid_connect']
-n gitlab

Important Note

When autoSignInWithProvider=openid_connect is defined, GitLab automatically redirects all login attempts to the configured OpenID provider. As a result, the default root account becomes inaccessible via the standard login page.

To retain access to the local root account, either omit the autoSignInWithProvider parameter or ensure that administrative users are properly mapped via the admin_groups setting in your OpenID configuration.