How authentik signs users into self-managed GitLab
The platform team wants GitLab accounts to be managed outside GitLab and signed into through one path. In that design, authentik acts as the identity provider through its SAML or OAuth2/OIDC provider types, and the self-managed GitLab instance consumes the trust that authentik establishes. Three decisions shape the work: which protocol to use, which endpoint values GitLab is configured with, and how group claims from authentik are passed to GitLab so that group membership can drive access. The protocol choice follows from what your GitLab edition and version support, your existing authentik setup, and whether you need group-based roles at sign-in. Confirm these details against the current authentik provider documentation and the GitLab authentication documentation for the exact versions you run, since the endpoint values must come from those sources and not from memory or from another topic's example.
Plan the trust in writing before anyone touches configuration. List the authentik application and provider you will create, the GitLab sign-in method you will enable, and the exact claim or attribute that carries group names. Then confirm with your GitLab administrator which groups will be mapped to GitLab access levels and which will be left unmapped, because unmapped users may still be created but receive no project rights. Record who owns the signing certificate or client secret, where it is stored, and when it must be rotated. Authentik's version policy matters here as well: the authentik security policy lists the supported release lines and the project announces security releases at least 24 hours in advance, so the team should know which authentik line it is on before scheduling changes. A tested sign-in on a staging GitLab instance, with a local administrator account kept as a recovery path, should be a gate before production.
What you need before configuring the integration
Five things need to line up before any SAML or OIDC settings are entered: supported release lines on both sides, the GitLab tier that supports the group handling you want, DNS and trusted TLS, a production-grade authentik database, and open network paths. Confirm each one in your own environment first, because a mismatch here usually shows up later as a failed sign-in rather than a clear error.
Supported authentik release line
Confirm which authentik line you run. The authentik security policy lists 2026.5.x and 2026.8.x as the versions receiving security fixes, and the project announces security releases at least 24 hours in advance. The GitHub releases page shows 2026.8.4 as the latest release, published October 14, 2026. Plan your authentik version against the GitLab release you target, and re-check the ACS and issuer settings after any authentik upgrade, since the 2026.5 SAML change affects them.
Supported GitLab release line
Confirm your GitLab instance is on a line that still receives fixes. The GitLab maintenance policy currently maintains 19.5, 19.4 and 19.3. Bug fixes go only to the current stable release, while security fixes are also backported to the previous two monthly releases, so an older GitLab line may stop receiving the patches that matter for authentication. Check upgrade stops before you move versions, because the sign-in configuration may need to change during the same window.
GitLab tier for group handling
Decide which group behavior you need before choosing a tier. Group sync and SAML group links depend on the GitLab edition and tier, so confirm the exact features for your target version in the GitLab authentication and authorization documentation rather than assuming them from the pricing page. Ask your GitLab account contact whether your self-managed tier includes the group features your access model requires, and record the answer in the scope document.
DNS names and trusted TLS
Assign stable DNS names to both the authentik and GitLab endpoints before you start, because the issuer, redirect and ACS values embed them. Both systems must trust the certificate chain they present to each other, including any internal certificate authority. Check that the browser, GitLab and authentik all resolve the names identically. Changing a hostname later means updating every provider and application setting, so treat the names as part of the design.
PostgreSQL-backed authentik deployment
Run authentik on a deployment that stores its data in PostgreSQL. The architecture documentation describes a server container, a worker container and PostgreSQL, which holds all configuration and data except uploaded files. Since the 2025.10 release, authentik no longer uses Redis, so there is no separate cache service to provision. The Docker Compose guide suits test and small production setups, while the Kubernetes guide recommends a separately managed PostgreSQL for production. Confirm your backup and restore process covers that database before you connect GitLab.
Network paths between the three parties
Map the traffic before configuration. The user's browser must reach both GitLab and authentik, and GitLab must reach the authentik endpoints it uses to validate tokens or metadata. Self-managed GitLab instances in restricted networks may need the authentik endpoints allowed through egress rules, and air-gapped sites need the metadata and certificates delivered by hand. Test each path with the same hostname and port your users will use, and check that any reverse proxy passes the headers and redirects sign-in depends on.
Choosing SAML or OIDC for GitLab sign-in
SAML sends a signed XML assertion from authentik to GitLab after a user signs in. GitLab trusts that assertion because both systems exchange certificates and agree on endpoints and identifiers. Teams that already run SAML for other enterprise applications often find it a familiar model, and attributes and group values travel in a single signed message.
- Assertion consumer service (ACS): GitLab provides the ACS URL for your instance. Enter it in the authentik SAML provider exactly, including scheme and host, because a mismatch causes assertions to be rejected.
- Certificate exchange: authentik signs assertions with a certificate you select. GitLab must trust that certificate, so record its expiry date and plan the replacement before it lapses.
- NameID choice: Select the identifier GitLab matches accounts on, such as a stable user ID or an email address. Changing the NameID later can detach existing GitLab accounts from their identities.
- Ongoing maintenance: Your team tracks certificate expiry, metadata changes on either side and the attribute names GitLab expects in the assertion.
Confirm the ACS, issuer and NameID settings against the authentik SAML provider documentation and the GitLab authentication page for your version.
OpenID Connect runs as an OAuth 2.0 flow in which GitLab redirects users to authentik, receives an ID token and reads the user's claims. There is no XML document to parse and no signing certificate to exchange. This model gives you a narrower set of values to manage and makes claim-based mapping explicit, which helps when you need to control exactly which profile data GitLab receives.
- Redirect URI: Register the callback address GitLab shows for its OpenID Connect configuration in the authentik provider. A mismatch stops sign-in before any user data is exchanged.
- Client credentials: authentik generates a client ID and client secret. Keep the secret in your secrets manager, limit who can read it and set a rotation schedule that your team will follow.
- Scopes: Request only the scopes GitLab needs to read the profile and email values. Adding scopes changes what authentik releases to GitLab, so review each addition.
- Claims: Map the claims GitLab uses for username and email. Missing, duplicate or unverified email claims are a common cause of account matching problems.
Check the redirect URI, scope names and claim names against the authentik provider documentation and the GitLab authentication page before you register the application.
Before you pick a protocol, confirm which sign-in methods your self-managed GitLab tier supports and which group features each tier includes. GitLab's pricing page lists Free, Premium and Ultimate as available for self-managed installations, but the sign-in and group capabilities attached to each tier are the detail that determines your design.
- Tier fit: Compare the SAML and OIDC options, and any group sync features, against the tier you run or plan to buy. Record the result before you choose a protocol.
- Upgrade path: If the instance will move to a later version, plan the required upgrade stops. Sign-in settings should be retested after each stop.
- Field names: Both products rename settings between releases. Check current field names in the authentik and GitLab documentation sets for the versions you deploy.
- Test account: Verify sign-in with a non-administrator account before you require SSO for all users.
- Fallback access: Decide whether a local administrator sign-in remains available if authentik is unreachable, and document who can use it and how it is audited.
Record the chosen protocol, tier and fallback decision in your design document so reviewers can trace why the instance signs users in the way it does.
Configuring authentik and GitLab in sequence
This sequence connects authentik to a self-managed GitLab instance so users sign in with their authentik accounts and only members of an approved group can get in. It produces a working provider and application in authentik, a matching sign-in configuration in GitLab, and a tested path that shows both a successful sign-in and a refused one.
Read the 2026.5 SAML change first
Before you copy any ACS, audience, redirect or issuer value, read the authentik 2026.5 release notes on the goauthentik releases page on GitHub. Confirm whether the change affects the protocol you plan to use, and check the GitLab documentation for the release you run. The platform engineer with authentik administrator rights owns this step. It is done when you have a written record of the exact values, the authentik release you tested against, and the GitLab version in use.
Create the authentik provider and application
Create an OAuth2/OIDC or SAML provider in authentik for GitLab, depending on the protocol your GitLab release documents for that method. Enter the redirect URI or ACS URL and the issuer exactly as confirmed in the previous step, then create an application that uses this provider and points its launch URL to your GitLab address. Verify that the provider shows the correct values, that the application is linked to it, and that the client credentials are stored only where administrators need them.
Bind the application to allowed groups
Attach a policy or group binding to the application so that only the users and groups you approve can launch GitLab through authentik. Decide in advance whether GitLab administrator rights will come from an authentik group, a GitLab setting or both, because this choice shapes the group mapping in later steps. The step is complete when a test user in the allowed group is authorized and a test user outside it is not, as shown in the authentik policy preview or test tool.
Configure the GitLab omniauth provider
Add the authentik provider to the omniauth settings of your GitLab instance, using the client identifier, secret, issuer or SAML values from authentik and the attribute or claim names your GitLab release expects. Apply the change with the procedure for your installation method, such as the Linux package reconfigure step, and restrict read access to the configuration file because it holds the client secret. Confirm that GitLab's sign-in page shows the authentik button and that the GitLab log has no configuration errors after the change.
Test sign-in with a non-administrator account
Sign in to GitLab through authentik with a standard user account, not an administrator, and confirm that GitLab creates or links the account as you intended. Review the token or SAML assertion contents in authentik's preview or event tools and compare the email, username and group values with what GitLab maps. The step is done when the username, email and any group-based access appear as expected in the GitLab user profile.
Confirm refusal for users outside the group
Sign in through authentik with a test user who is not in the allowed group and confirm that authentik denies the request before GitLab receives an assertion. Check the authentik event log for the recorded denial and confirm that GitLab did not create a new account for this user. Keep this test in your change record, and repeat it after each authentik or GitLab upgrade, since either can change how claims or assertions are issued.
Mapping authentik attributes to GitLab user fields
This table lists the account fields GitLab needs for a sign-in from authentik, the authentik source or mapping that supplies each one, and whether it must be unique. Rows marked for verification depend on your GitLab version and sign-in method, so confirm them in the GitLab authentication documentation before you configure production. The main takeaway is that the external identity link decides whether a returning user maps to the same GitLab account, so changes to it need the most planning.
| GitLab field | authentik source or mapping | Must be unique | When it changes |
|---|---|---|---|
| Username | Username claim or SAML attribute mapped in the authentik provider | Yes, unique per GitLab instance | Verify username change rules in the GitLab docs for your version |
| User email attribute mapped to the email claim or SAML attribute | Yes for account matching, verify | Verify whether GitLab updates email on each sign-in | |
| Full name | User name attribute mapped to the name claim or SAML attribute | No | Updates on sign-in if the mapping sends a value |
| External identity (extern_uid) | OIDC subject (sub) or SAML NameID from the authentik provider | Yes, unique per provider | Changing the NameID format or subject can break linking and lock users out |
| Group membership | Groups claim or SAML attribute built from authentik group membership | No | Applies at the next sign-in, verify group sync support for your tier |
How group membership reaches GitLab
Group handling depends on two things that must agree: what authentik sends in the OIDC token or SAML assertion, and what the GitLab instance accepts for the edition and tier in use. authentik can include group names or identifiers for the user, but GitLab only acts on a group claim if its SSO configuration names that claim and the instance supports the group feature you want. Confirm the exact claim name, the attribute format and the GitLab setting that consumes it against the GitLab authentication and authorization documentation for the version you run, and test with a non-administrator account before you rely on it.
Decide early whether memberships in GitLab will be driven automatically by authentik groups or managed by hand. Automatic mapping keeps access aligned with the directory and removes the need for a second record of who belongs where, but every authentik group that appears in the claim becomes a potential GitLab grant, so group names need a clear naming convention. Manual management is simpler to start with but drifts over time. Removing a user from an authentik group only changes GitLab access if the mapping is applied on the next sign-in, so plan for stale sessions and for accounts that rarely sign in. Test the removal path as deliberately as the grant path.
Keep administrator rights out of broad group claims. A group that gives every engineer access to the instance should never also grant admin area access, and administrator status should be assigned from a small, separately named authentik group with a named owner and a periodic review. Check the GitLab admin settings for any setting that changes administrator status from SSO and confirm whether your version applies it on sign-in or only at account creation. Record which authentik group maps to which GitLab role, because that mapping is the first thing an auditor or incident responder will ask for.
Hardening the sign-in path
Federated sign-in moves trust to authentik, so the controls that protect GitLab now sit partly outside it. The cards below cover the authentik-side gates, the secrets that establish trust between the two systems, the GitLab settings that decide whether a local password can bypass SSO, and the emergency path you need when the identity provider is down.
Enforce MFA in the authentik flow
Require a second factor in the authentication flow bound to the GitLab application, not only in a global default that other applications may override. On a self-managed instance, a single stolen password becomes an administrator session if no second factor is checked. Confirm which authenticator stages your flow uses, test the flow with a user who has no enrolled factor, and confirm that enrollment policy does not let users skip MFA setup. Check the flow's bindings after every change.
Restrict access to named groups
Bind the GitLab application to an explicit group or policy so that only the people who need GitLab can start a sign-in. Without this, any active authentik user may be able to create a GitLab account through the provider, depending on how GitLab's group and sign-up settings are configured. Decide who may create groups, and confirm that removing a user from the authentik group stops new sign-ins and that existing GitLab sessions end at the expected time.
Store and rotate client secrets
The OIDC client secret or the SAML signing material is the trust anchor between authentik and GitLab. Keep it in a managed secrets store, not in a shared configuration file or a chat thread, and record a rotation date when you create it. Rotation requires a change in both authentik and the GitLab configuration, so schedule it with the GitLab maintenance window. Ask who holds access to the secret store and how a leaked secret would be revoked.
Limit local password sign-in
Where policy requires SSO only, turn off direct password sign-in for GitLab users so that authentik enforces every login. Check the GitLab authentication settings for how password authentication and sign-up interact with your identity provider, and confirm the setting against your GitLab version before you change it. Test with a standard user, because a setting that blocks passwords can also block the emergency path described below.
Review the GitLab hardening guidance
Work through the GitLab hardening recommendations as a checklist against your instance, rather than assuming the SSO setup covers them. Items such as access to the admin area, token scopes, runner registration and outbound network rules sit outside the identity provider and still decide how far a compromised account can reach. Record which recommendations you accept, which you defer and who owns each decision.
Keep a tested emergency administrator
Keep a local GitLab administrator account that does not depend on authentik, with a password stored offline and a named custodian. Test that it still signs in after your password settings change, and rehearse the steps for turning SSO back on. Without this path, an authentik outage or a misconfigured provider can lock every administrator out of the instance. Record the test date and the result, and repeat the test after each GitLab upgrade.
Common failures when signing in to GitLab through authentik
This table lists the sign-in failures most often seen when GitLab and authentik are connected, with the likely cause and first fix for each. Read each row as a checklist to run against your own logs and provider settings. Confirm every fix against the GitLab and authentik documentation for the versions you run, because callback and issuer behavior changes between releases.
| Symptom | Likely cause | Fix to confirm |
|---|---|---|
| Redirect or ACS error page after a GitLab or authentik upgrade | The callback URL (SAML ACS or OIDC redirect URI) on the authentik provider no longer matches what GitLab sends after the upgrade, often because the SAML change in authentik 2026.5 altered how the ACS value is handled. | Compare the ACS or redirect URI in the GitLab configuration with the value on the authentik provider, correct whichever side differs, and check the release notes for the version you are moving to. |
| Login loop or 'invalid issuer' error | The issuer or endpoint URLs in GitLab point to a different application slug, hostname or scheme than the one authentik publishes, such as http versus https or a missing application slug segment. | Copy the issuer and endpoint values from the authentik provider page, paste them into GitLab exactly, and confirm the external URL in GitLab matches the hostname users browse to. |
| Sign-in fails with a certificate or signature error | A SAML signing certificate or OIDC client secret has expired, been rotated in authentik, or was pasted with extra whitespace. | Check certificate validity dates on the authentik side, re-exchange the certificate or secret with GitLab, and restart GitLab services so the new value loads. |
| Sign-in succeeds but a new GitLab account is created or sign-in is refused for an existing user | The NameID or email attribute sent by authentik does not match the email or username already stored on the GitLab account, so GitLab treats the login as a new identity. | Decide which attribute will be the stable identifier, map it in authentik to match the existing GitLab user, and test with one account before migrating others. |
| Users sign in but group-based access is missing | Groups are not included in the token or assertion, the group attribute name in GitLab does not match the claim name sent by authentik, or the scope or property mapping that adds groups is not attached to the provider. | Add the group mapping to the provider in authentik, confirm the claim name in a test token or assertion, and align the group setting in GitLab with that exact name. |
| Specific users are refused with an access denied message from authentik | A policy bound to the application or flow (for example group, GeoIP, reputation or MFA stage conditions) rejects the user, and the rejection is not visible to GitLab. | Review the application's bindings and policy results in the authentik event log, adjust the binding for the affected group, and confirm with a test user before changing policies for everyone. |
| Admin accounts cannot sign in after SSO is enabled | Password or local sign-in was disabled in GitLab before the SSO path was verified, leaving no working administrator path. | Keep a local administrator with a tested password or recovery path until SSO is verified, and confirm the current sign-in options in the GitLab authentication documentation. |
Questions teams ask before hiring help with GitLab SSO
What drives the effort of a GitLab SSO integration with authentik?
The effort is driven mostly by the protocol choice, the number of groups that must map to GitLab access, how many local GitLab accounts already exist, and how often your team plans to upgrade both systems. SAML needs the Assertion Consumer Service URL, the issuer and a certificate exchange configured to match exactly on both sides. OIDC needs a client ID, a secret and a redirect URI, and usually involves fewer moving parts. Group mapping grows with each group you need to carry across, and existing local accounts need a decision about whether they are linked to the SSO identity or left alone. Each of these adds test cases. Ask any provider for a written scope that lists the protocol, the group count and the account migration approach, then compare the quote against that list.
Can a team set up GitLab SSO with authentik without outside help?
Yes, a team with an authentik administrator and a GitLab administrator can complete a basic integration in an internal test environment, provided both have time to read the configuration references and test sign-in carefully. The harder parts are usually not the first login. They are the group and role mapping, the handling of existing accounts, the change control around a production GitLab instance, and the verification that sign-in still works after the next authentik or GitLab upgrade. Outside help is most useful when the team lacks a second pair of eyes on the SAML settings or when the rollout must be documented for an auditor. Decide early which of those gaps you have.
What does our team need to provide for a GitLab SSO project?
Plan for four named roles before the work starts. You need an authentik administrator who can create the provider, application and group bindings, and a GitLab administrator who can edit the omniauth or SAML settings on the instance. You also need owners for DNS and TLS certificates, because the GitLab and authentik hostnames must resolve correctly and the certificates must be trusted by both sides. Finally, provide a test group of users, ideally with a mix of roles, and a non-production GitLab instance or a maintenance window for the production change. Confirm these owners and the access they need in your own environment before the kickoff, since the exact permissions depend on how your organization runs its administration.
How do authentik and GitLab upgrades change an existing SSO setup?
Upgrades can change endpoints, certificates, field names and defaults, so an SSO setup that worked last year should be retested after every planned change. On the GitLab side, the maintenance policy ships a major release each year, a minor release on the third Thursday of each month and patch releases twice a month, and GitLab requires upgrades to pass through required upgrade stops, which fall at versions x.2, x.5, x.8 and x.11 since GitLab 17.5. On the authentik side, the security policy lists 2026.5.x and 2026.8.x as the supported versions receiving security fixes, and the 2026.5 release changed the SAML settings you need to check. Keep a runbook that records the current ACS URL, issuer and certificate expiry, and test sign-in in staging before each upgrade.
What work continues after GitLab SSO goes live?
Ongoing work includes certificate renewal, monitoring of sign-in failures, periodic review of group mappings as teams change, and retesting after each GitLab and authentik upgrade. Someone must also own the process for onboarding and offboarding users, since removing a user in authentik does not automatically change every GitLab setting you may have configured. Track these tasks in your operations calendar with named owners. If you want a partner to carry them, ask for the recurring support scope in writing, including the systems covered, response expectations and upgrade testing. DeployOpen offers ongoing support and upgrades as retainers, and the retainer scope is agreed in writing.
How does the authentik edition choice affect GitLab SSO work?
The authentik edition determines which features are available, and it affects the integration only where a feature you need is enterprise-only. The authentik pricing page lists an Open Source edition at no cost, an Enterprise edition billed per user and per external user, and an Enterprise Plus edition starting at a stated annual amount. Core SAML and OIDC provider functions used for GitLab sign-in are part of the project, but features such as enhanced audit logging and dedicated support sit in the paid editions. Confirm with the vendor which features your compliance or support requirements need, because the license terms for code in the enterprise directory differ from the MIT license covering most of the repository. Ask your provider to state the edition assumed in the quote.
How DeployOpen scopes and delivers GitLab SSO with authentik
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, so the authentik and GitLab SSO work runs in your environment. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm the GitLab edition, version and installation method, including whether it is the Linux package, Helm chart or Operator.
- Record whether sign-in uses SAML or OIDC, and which ACS URL, issuer and redirect values your instance needs.
- Agree in writing how groups map to GitLab roles, and whether self-managed users are provisioned or only signed in.
How we build
- Configure the authentik provider and application, then set the matching GitLab settings in a staging instance first.
- Test sign-in, first-time account creation, group claims and failed-login behavior with named test users before any cutover.
- Confirm the authentik and GitLab upgrade sequence, including GitLab required upgrade stops, before changing either side.
How we hand over
- Deliver the configuration record, certificate and key locations, claim mappings and group mapping table as written documentation.
- Walk your platform and identity teams through the sign-in flow, recovery steps and the local administrator fallback.
- Document the test cases used, so your team can rerun them after future authentik or GitLab upgrades.
How we support
- Ongoing support, upgrades and continuous testing for the integration are available as a retainer, scoped in writing.
- Retainer scope can cover reviewing authentik security releases and planning the matching GitLab maintenance window.
- Ask any partner to state in writing who performs upgrades, who holds administrator access and how incidents are escalated.
