Connect GitLab to Keycloak
Connect self-managed GitLab to Keycloak with OIDC, covering identity mapping, edition boundaries, project permissions and token-aware offboarding tests.
Last updated
In short
- GitLab OIDC sign-in is separate from project authorization.
- Choose a durable external identity before linking existing accounts.
- SSH keys, access tokens and runners need their own offboarding review.
On this page (6)
Integrations · Part of GitLab
Use OIDC for a defined self-managed integration
GitLab can use Keycloak as an OpenID Connect authentication provider. The current GitLab OIDC documentation lists the integration for GitLab Self-Managed across Free, Premium and Ultimate. That does not mean every provisioning, group synchronization or governance feature is included in every tier.
This guide is a reference configuration process and acceptance plan, not a tested deployment. Record the GitLab edition and release, installation method, Keycloak release and the authentication features actually required before selecting the final settings.
Identify existing accounts before enabling new login
GitLab accounts own namespaces, merge requests, approvals and access credentials. An incorrect external identity mapping can create a second account or link the wrong person. Inventory existing account IDs, usernames and email addresses, then define the durable identity Keycloak will assert.
| Item | Required decision | Test case |
|---|---|---|
| OIDC issuer | Exact Keycloak realm HTTPS URL | Reject another realm’s token |
| Client | Dedicated GitLab client | Credential cannot be reused by unrelated applications |
| External user identifier | Stable claim chosen for the deployment | Email or display-name change preserves account |
| Account creation | Allowed, restricted or preprovisioned | Unapproved user cannot create unintended access |
| Account linking | Verified association to existing users | Similar email or username does not mislink |
| Project membership | Separate GitLab authorization process | Authenticated user sees only assigned projects |
The upstream Keycloak example uses a particular UID claim, but copying it is not a substitute for matching the existing identity scheme. If usernames are mutable in your directory, evaluate the consequence before using one as the permanent external key.
Configure a dedicated client and exact callback
Create a client in the intended Keycloak realm, with the authorization-code flow and the supported client-authentication settings. Register GitLab’s exact callback URI from the selected provider configuration. Avoid wildcard redirects and protect the client credential through secret management.
Configure GitLab using the method appropriate to its installation: a Linux package, containerized package or another supported deployment has different configuration and restart mechanics. Use discovery and the expected issuer so endpoint and signing-key information comes from the intended realm. GitLab’s documentation includes a Keycloak-specific section and requires HTTPS for that connection.
Select a supported asymmetric signing algorithm and preserve key-rotation behavior. The client secret and the realm signing key serve different purposes; never extract or share a realm signing private key merely to make a standard client integration easier.
Keep sign-in and repository privileges separate
A person who signs in successfully should not automatically receive membership in every group. Start with a synthetic account that belongs to no projects, then add the smallest intended role to a test project. Verify repository visibility, issue access, merge permissions and protected-branch behavior independently.
If the design uses group synchronization or provisioning, check the exact GitLab tier and protocol documentation for those features. Do not infer SAML group-sync or SCIM availability from the fact that OIDC browser sign-in works. Keycloak’s roles and groups can express identity information, but GitLab must have a supported mechanism to turn it into application permissions.
For privileged GitLab administration, decide whether an additional authentication step is required and supported by the selected version. Keep a controlled recovery administrator available while changing the sign-in configuration.
Test every credential path used by developers
Browser SSO is only one way to use a Git platform. Developers and automation may use SSH keys, personal access tokens, project tokens, deploy keys, registry credentials and runner credentials. Define their lifecycle separately.
| Scenario | Expected evidence |
|---|---|
| New approved employee | Correct account and only intended project access |
| Unapproved realm user | No unintended account or private repository access |
| Existing account links | Original namespace and contribution ownership preserved |
| Email rename | Same account, no duplicate namespace |
| Keycloak account disabled | Browser behavior measured through session expiry and refresh |
| GitLab account disabled | Relevant Git and API operations denied as designed |
| Credential rotation | Automation resumes with new scoped credentials; old ones fail |
Test an already-open browser and an active Git client after disablement. Do not declare offboarding complete based only on a failed fresh browser login. Record which credentials remain valid by design and who must revoke them.
Make the change recoverable
Back up GitLab configuration and its operational state through the supported backup process, preserving the secrets needed to restore encrypted values. Save the prior authentication settings and verify the local recovery path before enabling automatic redirection or removing an old provider.
Pilot the integration with a small set of synthetic and explicitly selected real accounts. If linking or authorization fails, restore the previous login configuration and inspect newly created identities before deleting anything. Account deletion can affect ownership and contribution history; it is not a routine rollback shortcut.
Rehearse Keycloak signing-key rotation and client-secret rotation in a nonproduction environment. After either platform is upgraded, rerun issuer validation, account linking, project access, disabled-user and recovery checks. The integration is accepted when it preserves identity and repository boundaries across those lifecycle events, not merely when the login button works.
Sources and further reading
Use the linked documentation to confirm the version, edition and contract that apply to your project.
