When GitLab Kerberos and smart card sign-in fit a regulated network
Choose Kerberos or smart card sign-in when your users already authenticate to Windows with integrated sign-in, to a Kerberos realm, or with CAC or PIV cards, and when a policy requires that credential to be the one used for GitLab. GitLab Self-Managed supports Kerberos, smart card authentication, LDAP, SAML, generic OAuth 2.0 and OmniAuth providers, JWT, and SCIM user provisioning, according to the GitLab authentication documentation. These methods do not replace one another. Kerberos and smart card sign-in establish who the user is at the browser or workstation, while LDAP typically supplies group membership and account state. Teams that rely on an identity provider for everything else may find SAML sufficient, so the decision turns on what your network already trusts.
Compare the options against the constraints your environment actually imposes. If your identity provider cannot issue SAML assertions to GitLab, or if your users sign in through a directory that is only reachable on the internal network, Kerberos or smart card login may be the only passwordless path available. If your organization already runs SAML for other applications, adding Kerberos or smart card sign-in alongside it adds a second configuration to maintain, so the reason for it should be written down. Ask your identity team which realm, certificate authority and card issuer apply to each user population, and whether any group that signs in with a card must also be mapped to a GitLab role. Confirm these details against the current GitLab authentication documentation before you commit to a design.
Plan for the cases where one user reaches GitLab through more than one method. A person may hold a smart card credential, a Windows session and a directory account at the same time, and the identity you map to a GitLab account must be unambiguous. Decide which source is authoritative for the account, how a changed name or a revoked card is handled, and who can disable access when a credential is lost. Test these cases in a staging instance with accounts that mirror your production directory before rollout. Ongoing ownership is also a cost: certificate renewal, directory changes and GitLab upgrades all touch this configuration, so assign an owner before go-live.
How Kerberos and smart card login differ from password and LDAP sign-in
Kerberos, smart cards and LDAP each answer a different question: who is this user, how did they prove it, and what groups and attributes do they hold. GitLab can use more than one of these at the same time, so the decisions below determine which method signs a person in and which one decides their access.
Kerberos ticket-based sign-in
Kerberos proves identity with tickets issued by a central key distribution center after a user logs on to the domain. The user's workstation presents a ticket to GitLab, so the password is not typed into GitLab and is not sent across the network. Check that your GitLab host can reach the domain controllers, that clocks are synchronized across both sides, and that the service principal and keytab are created and rotated under a named owner. Browser configuration on client machines is a common cause of failed sign-in and should be tested with real accounts before rollout.
Smart card certificate login
A smart card holds a private key that never leaves the card, and the user unlocks it with a PIN. GitLab then matches the certificate presented at sign-in against trusted certificate authorities and an identifier in the certificate, such as a user principal name or email. The design work sits in the certificate chain, revocation checking and the attribute GitLab maps to an account. Confirm with your PKI team which certificate issuers are trusted, how revoked or expired cards are handled, and whether card holders also need a second factor.
LDAP as the directory of record
LDAP does not prove identity at sign-in on its own in most setups. It holds the user record, group membership and attributes such as department, email or account status that GitLab reads to create accounts and assign roles. Kerberos and smart card methods answer who the user is, while LDAP answers what the user belongs to. Confirm which attribute uniquely identifies each person in the directory, and which groups must be read for administrator, auditor or external status, before choosing the sign-in method.
Keeping group roles tied to the directory
Group sync and role mapping are configured through LDAP even when a user signs in with Kerberos or a smart card. This means a person removed from a directory group can keep a session until it expires, and an account blocked after a directory outage may not sign in by any method. Plan the sync interval, the behavior when the directory is unreachable, and how an administrator unblocks an account. Test each removal path with a disposable account.
One person, several sign-in identities
A single employee can hold a Kerberos principal, a smart card certificate, a directory entry and a password fallback, and GitLab can link these to one account only if the identifiers agree. Mismatched usernames, duplicate emails or a renamed account often create a second user rather than merging the two. Decide the canonical identifier, document which methods are allowed for each population such as staff, contractors and service accounts, and check for duplicate accounts after the first pilot group signs in.
Fallback and lockout planning
Passwordless methods fail in predictable ways: expired tickets, unreadable cards, a lapsed certificate or a broken time source. Each failure needs a documented path back in, such as a password method for named users or a break-glass administrator account held outside the directory. Ask your team which fallback is permitted under your access policy, who approves its use and how its use is logged and reviewed afterward.
Which sign-in method fits which user population
This table compares Kerberos, smart card, LDAP and SAML against the users they serve, the client setup each needs, how groups and provisioning work, and what happens when a method fails. Read each row as a question to answer for your own user base, then confirm the edition and version requirements for each method before you commit to a design.
| Method | Best fit population | Client requirement | Group mapping and provisioning |
|---|---|---|---|
| Kerberos | Domain-joined staff on a Windows or Active Directory network who should sign in without typing a password | Browser and workstation must be configured for Kerberos (SPNEGO) against the domain; confirm supported clients for your version | Identity comes from the directory; confirm how group roles are mapped and whether provisioning is handled separately |
| Smart card certificate login | Users who must present a government or enterprise card and PIN, such as staff under a public key infrastructure policy | Card reader, middleware and a certificate chain trusted by GitLab; confirm the certificate and CRL setup for your environment | Typically paired with a directory for group data; confirm which attributes GitLab reads from the certificate and directory |
| LDAP | Broad directory-backed populations, including contractors and users off the domain network, where password sign-in is still accepted | Standard web or Git client; no special workstation setup beyond the normal sign-in path | Directory group sync to GitLab group roles is documented; confirm which group features require Premium in your version |
| SAML | Organizations running a central identity provider such as Entra ID, Okta or Google for all applications | Browser sign-in through the identity provider; Git access depends on tokens or SSH keys as configured | SAML group attributes and SCIM provisioning are documented; confirm tier requirements for SCIM and group claims |
| Fallback behavior | Users who cannot authenticate through the primary method, such as a lost card or an unjoined laptop | Confirm whether a local GitLab password or another provider remains available for each user type | Confirm which method a user can use when the directory is unreachable, and whether blocked directory users need manual unblocking |
How to configure Kerberos and smart card login in GitLab
This sequence takes a self-managed GitLab instance from confirmed directory and certificate trust to passwordless sign-in for a pilot group, with LDAP still working for the same users. Each step ends with a check you can record before moving on. Exact setting names come from the current GitLab authentication documentation, so confirm them against that version before you edit any file.
Confirm directory and certificate trust chain
The identity team confirms the Kerberos realm, the key distribution center, DNS records, and time synchronization between the GitLab host and the directory. For smart card login, the same team confirms the issuing certificate authority chain, the intermediate certificates, and that the revocation endpoints are reachable from the GitLab host. Done means a domain-joined test client obtains a ticket, and the GitLab host can validate a test user's certificate chain end to end.
Prepare service principal and keytab
The directory administrator creates a service principal for the GitLab hostname and exports a keytab for it. The platform engineer copies the keytab to the GitLab host, sets ownership so only the service account can read it, and places the CA bundle in a path the configuration will reference. Done means running a Kerberos initialization against the keytab on the GitLab host succeeds, and the keytab permissions are recorded in the change ticket.
Decide how users map across identity sources
Before editing configuration, the team writes down which attribute identifies each person in Kerberos, in the smart card certificate, and in LDAP, and confirms those values match for every pilot user. Mismatched usernames or email addresses create duplicate GitLab accounts, which are hard to clean up later. Done means a short mapping table exists for the pilot group, and each pilot user's identifiers have been checked against the directory.
Set Kerberos and smart card values in gitlab.rb
On a Linux package installation, the administrator backs up
/etc/gitlab/gitlab.rb, then adds the Kerberos and smart card settings described in the GitLab authentication guide at GitLab authentication and authorization. The settings should point to the keytab, the CA bundle, and the identifier field agreed in the previous step, and the LDAP block should remain enabled for fallback. Done means the file parses without errors and the backup copy is stored with the change record.Reconfigure and restart GitLab services
The administrator runs
gitlab-ctl reconfigureand thengitlab-ctl restarton the GitLab host, and watches the reconfigure output for errors about the new authentication settings. After the restart,gitlab-ctl statusshould show all services running, and the instance should answer its health check from a client on the same network. Done means the reconfigure completes without errors and services are healthy. If the install method is not the Linux package, the team confirms the equivalent procedure in the installation documentation first.Test each sign-in path with a pilot group
A small pilot group signs in with Kerberos from a domain-joined browser, with a smart card and PIN, and with LDAP credentials as a fallback. The team also confirms that a user outside the pilot group is refused, and that a user with a revoked certificate cannot sign in. Done means each path has a recorded result, the GitLab authentication logs show the expected entries, and the team has agreed in writing which group moves to the next phase.
How Kerberos, smart card and LDAP coexist for the same users
The core decision is how one person is matched across every sign-in path. A user who reaches GitLab through Kerberos, a smart card certificate or LDAP must land on the same GitLab account every time, otherwise the same employee ends up with two accounts, split repositories, and group memberships that disagree. Before any gitlab.rb setting is changed, decide which attribute is the stable key for each method. For Kerberos that is usually the principal name, for smart cards it is the certificate subject or a chosen certificate field, and for LDAP it is the directory identifier that GitLab reads. Write this mapping down as a single table and have the identity team sign off on it. The username mapping must agree with the identity linking that GitLab stores for each user, so a rename in the directory does not quietly create a new account on the next sign-in.
Duplicate accounts are the main risk in this design, and they usually appear after a change rather than at go-live. Examples include a user whose directory username was changed, a contractor who receives a certificate under a different naming convention, or a second identity provider added later for a different group. Plan one check for duplicates, run it after each pilot wave, and make the owner of that check explicit. LDAP group sync and administrator roles should also be designed once for all paths. If Kerberos users, smart card users and LDAP users receive their group roles through different rules, a person can gain administrator rights through one path and lose them through another. Confirm with your GitLab edition and the GitLab authentication and authorization documentation which group settings apply to each method in your version, because support and behavior differ between them.
Test fallback before users depend on it. Ask what happens when the Kerberos ticket is unavailable, when a smart card reader or certificate revocation check fails, and when the directory is unreachable, then record which methods still allow sign-in and which lock users out. Test each failure with a pilot group that includes an administrator and a break-glass account kept under a separate, documented procedure. Confirm how GitLab handles users who are blocked after a directory outage, since a fallback that restores sign-in but leaves blocked accounts behind will still generate support tickets. Ask your vendor or integrator to show the test results for each path, and keep those results with your change records.
What teams ask before rolling out Kerberos or smart card sign-in
What drives the cost of Kerberos or smart card sign-in for GitLab?
The cost depends mostly on how ready your directory and public key infrastructure already are, not on GitLab itself. The main components are directory and PKI readiness, configuration of the GitLab instance and its identity settings, client endpoint configuration across browsers and workstations, pilot testing with real users, and handover of the keytab and certificate lifecycle to your team. Costs rise when Active Directory service accounts, SPNs or certificate templates need to be created or corrected, when many operating systems or browsers are in use, or when the pilot must cover several user populations. Ask any partner for a written quote that lists each component separately, states who performs each task, and identifies which items are one-time and which recur, such as certificate renewal and keytab rotation.
How long does a Kerberos or smart card rollout usually take?
No researched duration is available for this work, so treat any timeline as something to confirm in writing. The schedule is shaped by the same factors as cost: how quickly your directory team can produce service accounts and keytabs, how long your PKI team takes to issue or validate certificates, how many endpoint profiles need testing, and how long the pilot runs before wider rollout. Ask for milestones tied to named deliverables, such as a tested sign-in on a reference workstation, a documented fallback path and a signed-off pilot group. Also ask which steps depend on your change windows or security review cycles, because those often set the critical path more than the technical build does.
What does the client team need to provide before work starts?
Your team needs to supply access and decisions that only you can make. Typical inputs include:
- Directory access, including the domain structure, the service account naming approach and permission to create SPNs and keytab files.
- PKI access, including the certificate authority hierarchy, the templates for user and server certificates, and the revocation method you use.
- Endpoint inventory, covering browsers, operating systems, smart card middleware and the workstations that will be in the pilot.
- A test GitLab environment that mirrors production identity settings, plus named owners for DNS, TLS and reverse proxy changes.
- Decisions on whether LDAP stays as the fallback and which users keep password sign-in.
Agree these inputs in the written scope, because missing items are a common reason pilots slip.
Who owns the keytab and certificate lifecycle after go-live?
Your organization should own the keytab and certificate lifecycle, and the rollout should document who does what before go-live. Keytabs hold long-lived secrets for the GitLab service principal, so someone must control their creation, storage, rotation and revocation. Certificates for smart card users need issuance, renewal, revocation and checks against the authority your PKI team operates. Ask the implementation partner to hand over runbooks, a renewal calendar and the exact commands or configuration keys used, so your staff can rotate credentials without outside help. Decide in advance who receives expiry alerts and who approves an emergency revocation.
Can an internal team implement Kerberos or smart card sign-in alone?
An internal team can build this alone if it already has working Active Directory, PKI and GitLab administration skills and time for a full pilot. The work touches three specialties at once: directory administration, certificate management and GitLab configuration, and mistakes in any one can lock users out. Teams without recent experience with Kerberos delegation, certificate chain validation or endpoint configuration often benefit from an outside review of the design and the pilot results. Compare the two options using the same written scope, listing the skills each task requires and the people who are available for the full duration of the pilot.
How does Kerberos or smart card sign-in work next to LDAP for the same users?
Kerberos and smart card authentication are alternative ways to prove identity at sign-in, while LDAP remains the source of user and group data. GitLab Self-Managed supports LDAP, Kerberos and smart card authentication, so a user can sign in through one method and still receive group membership from the directory. Plan which method applies to which user population, whether LDAP password sign-in stays available as a fallback, and how a user who authenticates by certificate maps to the same GitLab account. Confirm these mappings in a test instance before production, because the account matching rules determine whether duplicate accounts appear.
What should a pilot test before rolling sign-in out to everyone?
A pilot should test the paths that fail most often in production, not just a successful sign-in on one machine. Include a range of workstations, browsers and smart card readers; users who are members of different directory groups; an expired or revoked certificate; a locked or disabled account; and a sign-in when the directory or certificate authority is unreachable. Record which fallback works in each case and how long support staff need to resolve a lockout. Ask for a written test plan with pass criteria, a named list of pilot users and a sign-off step owned by your team before expansion.
What support and operations work continues after the rollout?
Ongoing work includes certificate renewal, keytab rotation, directory changes, endpoint middleware updates and GitLab upgrades that may affect authentication settings. GitLab publishes upgrade stops and a maintenance policy, so authentication configuration should be retested whenever you move to a new required stop. Plan monitoring for failed sign-ins and blocked accounts, and decide who responds to them. Ask any partner whether post-rollout support is included, what it covers and how it is priced, and whether a separate retainer is needed for upgrades and certificate work.
Security and operational risks to plan for
Kerberos and smart card sign-in move trust into a few high-value places: service keys, certificate revocation, time synchronization and fallback sign-in paths. Each card below names one of those places, what can go wrong there and what to verify before go-live.
Keytab and service account protection
The keytab file holds the long-term key for the GitLab service principal, so anyone who reads it can impersonate that service. Restrict file ownership to the account GitLab runs under, keep it off shared mounts and backups that lack equivalent controls, and record who can read it. Confirm that the service account has no interactive logon rights and that its password policy and rotation match your Kerberos realm policy. Rotate keys after staff changes and after any suspected exposure, and check that rotation does not silently break sign-in for other services using the same principal.
Certificate revocation checking
Smart card login relies on the certificate chain and on revocation status. If revocation checks are not configured or fail open when the responder is unreachable, a revoked badge or card can keep signing in. Decide which revocation method your PKI publishes, confirm that GitLab hosts can reach those endpoints from the network segments where users sign in, and test a revoked certificate against a non-production instance. Ask your PKI team who owns revocation timing for lost or departed staff.
Clock skew and ticket lifetime
Kerberos rejects tickets when clocks between clients, the key distribution center and GitLab drift beyond the allowed skew. Failures often look like random sign-in errors for some users or after a host reboot. Confirm that every GitLab node and domain controller syncs to the same trusted time source, and set ticket lifetimes and renewal windows with your Kerberos administrators rather than leaving them at defaults. Include time drift in your monitoring so a single misconfigured host is found quickly.
Fallback paths that weaken enforcement
Password sign-in, LDAP bind and two-factor exceptions often remain enabled after Kerberos or smart card is introduced, so users can avoid the stronger method. Inventory every sign-in method on the instance, decide which accounts may use a fallback, and document who approves each exception. Verify that disabling password sign-in for the target group actually blocks the fallback in your GitLab version, and review the list of accounts with exceptions on a fixed schedule.
Monitoring for failed sign-ins
Failed Kerberos negotiations, rejected certificates and LDAP lookup errors can point to attacks, misconfiguration or a directory outage, and the symptoms overlap. Forward GitLab authentication logs and the domain controller or identity logs to your central logging platform, define alert thresholds for spikes by user and source host, and assign an owner for each alert. Test the alerts with a deliberate failed sign-in before go-live so you know they fire.
Control mapping and evidence
Access control evidence for these methods should map to the control families in NIST SP 800-53, including identification and authentication, audit and accountability, and configuration management. Use the GitLab hardening guidance as a starting checklist, roll it out gradually and record which settings you adopted and why. Keep configuration in version-controlled gitlab.rb changes so reviewers can see the reasons behind each authentication setting. DeployOpen prepares this evidence, but independent assessors decide whether it meets your requirements.
How upgrades and disaster recovery affect these sign-in methods
Kerberos and smart card settings are part of the instance, not a one-time setup, so they have to survive every upgrade stop and every restore. Before you schedule an upgrade, check the GitLab upgrade paths documentation for the required stops that apply to your current version, and plan a test run on a staging instance that has the same authentication configuration. Confirm in that test that the gitlab.rb keys for Kerberos and smart card login (including the keytab location, the realm and the certificate authority file) still load, that the Kerberos service principal still resolves, and that a user can sign in with a Kerberos ticket and with a smart card after the upgrade. Treat each required stop as a separate test point, not a single final check.
Backup planning has to cover more than the database. The keytab for the GitLab service principal is a credential, so store it in your secrets process with its own rotation record, and confirm how your backup tooling handles the file. The certificate authority bundle used to validate smart card certificates, and any certificate revocation list fetch settings, must be recoverable as well. Review the GitLab backup and restore documentation to see what the application backup includes and what it leaves out, then document the gap. Ask your identity team how a restored instance will obtain a fresh keytab if the old one is lost, and who approves that step.
If you run a Geo secondary site, it needs the same Kerberos and smart card configuration as the primary, including its own host name in the service principal and access to the same trust chain. Geo replicates instance data, but the host-level files that hold keytabs and certificate trust are not part of that replication, so you must deploy them to the secondary yourself. Test a failover in a non-production environment and confirm that users can still sign in through both methods after the switch. Keep LDAP working on the secondary too, since it is the fallback for users whose Kerberos ticket or certificate cannot be validated during an incident.
How DeployOpen scopes and delivers GitLab Kerberos and smart card sign-in
DeployOpen plans, implements, tests, documents and supports self-hosted GitLab inside your own infrastructure, so Kerberos and smart card sign-in are designed around your domain controllers, certificate authority and network. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- Inventory the directory, Kerberos realm, certificate authorities and the GitLab version and install method in use.
- Record which users sign in by Kerberos, smart card, LDAP or both, and which fallback paths must stay open.
- Agree in writing which gitlab.rb settings, test cases, runbooks and handover documents are included.
How we build
- Configure Kerberos and smart card settings in a staging instance first, then validate them against a test account set.
- Confirm certificate chain, revocation checking and user-to-identity mapping with your PKI team before production changes.
- Test LDAP group sync and existing sign-in paths alongside the new methods so no user loses access unexpectedly.
How we hand over
- Deliver tested configuration, a documented sign-in matrix and a rollback procedure for each authentication method.
- Walk your administrators through troubleshooting steps, log locations and the process for resyncing or unblocking users.
- Document open items, dependencies on your identity and PKI teams, and the checks to repeat after each GitLab upgrade.
How we support
- Ongoing support, upgrades and testing are available as retainers, scoped separately from the original engagement.
- Retainers can cover re-testing sign-in paths after GitLab upgrade stops and changes to certificates or domain controllers.
- Ask any provider which GitLab versions their support covers and how they will test Kerberos and smart card changes before release.
