Why GitLab blocks LDAP users during a directory hiccup and how to unblock them
The ldap_blocked state is a designed safeguard, not a defect. GitLab marks an LDAP-linked account as blocked when the directory no longer returns that account as active during a sync or sign-in check, and a blocked account cannot sign in. The trouble is that a directory outage, a domain controller failover, a lockout of the bind account or directory-side rate limiting can make many healthy accounts look inactive at once, so a short incident can appear as a mass removal. Before you change anything, confirm the exact trigger conditions for your installed version in the GitLab authentication documentation, since the behavior depends on the version you run.
Teams need this playbook after any directory event that could have affected reads, including maintenance windows, directory replication delays and incidents on the service account GitLab uses to query LDAP. This page covers how to tell a real departure from a directory fault, how to clear the blocked state for one user, how to resync a single account and how to set up monitoring so the next hiccup is caught early. Group sync, SAML and SCIM are covered in their own sections, so the focus here stays on the LDAP user state. The first step is always to check the directory, not to unblock accounts: confirm that the affected users are enabled, that the bind account could read them during the outage window, and that the outage has ended.
Diagnosing the cause by symptom and environment
A full outage means the directory cannot answer bind or search requests, so every LDAP sign-in fails during the same window. Users usually report that valid credentials are rejected or that the sign-in page returns an error after the password is entered. Confirm the outage sits in the directory before touching GitLab, because a failed bind from a host outside GitLab settles the question quickly.
- Directory health: Check domain controller or LDAP server reachability, service status and replication from the directory side first.
- GitLab application log: Search the Rails production log for LDAP connection errors inside the outage window. Confirm the log location for your installation in the GitLab authentication documentation.
- Blocking behavior: Confirm in your GitLab version whether failed lookups during an outage mark accounts as
ldap_blocked. If they do, the affected accounts need review after recovery. - Fix path: Restore the directory, run a test bind, then sign in with one known account before asking the wider group to retry.
Record the start and end times of the outage, since you will need them to decide which accounts to review.
Intermittent timeouts are harder to spot because some sign-ins succeed on retry while others fail. Users report that the second or third attempt works, that sign-in is slow at certain times of day, or that a small set of accounts is blocked after a sync run. The directory itself looks healthy in most monitoring, so the evidence sits in the timing of failures.
- Timeout settings: Review the timeout value in the LDAP server block of
gitlab.rband confirm the exact key name for your version in the GitLab documentation. - Network path: Compare latency and packet loss between the GitLab nodes and each directory server, including any firewall or load balancer in the path.
- Server selection: Check whether GitLab points to one directory host or several, and whether a slow host is in the list.
- Sync logs: Look for partial sync results in the production log and note which accounts failed, then compare them against the failure window.
Repeat test binds from every GitLab node over the same period, because a single successful test rarely proves a timeout problem is gone.
Rate limiting or query throttling appears when the directory refuses or truncates requests after a burst of activity. Users report sign-in failures that cluster around scheduled group sync or large lookups, and administrators may see many accounts flagged together rather than one or two. The pattern follows load, not individual accounts, which is the key difference from a changed user record.
- Directory query policy: Ask the directory team which query limits, page sizes and administrative throttles apply to the account GitLab uses for binds. Microsoft documents LDAP query policy controls for Active Directory, but confirm the values for your environment.
- Sync scope: Review the group base and user base settings in
gitlab.rbto find searches that return more objects than needed. - Sync timing: Compare the configured sync interval with the times when failures cluster, and check whether other systems query the directory at the same time.
- Service account: Confirm whether the bind account is shared with other applications, since a shared account concentrates load.
Agree on any change to query limits with the directory owner, because a limit that protects the directory from other clients should not be relaxed for GitLab alone.
A single-user problem is the most contained situation. One person cannot sign in while colleagues on the same directory work normally. Typical causes are a renamed account or an account moved to another organizational unit, which changes its distinguished name, or an account that has been disabled in the directory for a legitimate reason such as leave or offboarding.
- Current directory record: Look up the user in the directory and confirm the current DN, the enabled state and the attribute GitLab uses to match the account.
- GitLab user record: In the Admin area, check the user's state and last sign-in, and confirm whether the account shows
ldap_blocked. - LDAP check task: Run the LDAP check task documented for your version, for example
gitlab-rake gitlab:ldap:check, and review the output for this user. - Resync or restore: After the directory record is correct and enabled, trigger a sync for that user only. Confirm the procedure for your version before running it.
Deleting and recreating the account can orphan the user's projects and contributions, so confirm the sync result with the owner of the account first.
Recovery options and when each one fits
This table compares five ways to recover LDAP users that GitLab has blocked, from waiting for a sync to rolling back a configuration change. Match each row to the cause you have confirmed, and start with the least invasive option. The main takeaway is that access should be restored only after the directory shows the account is still active.
| Recovery path | When it fits | What it changes | What to confirm first |
|---|---|---|---|
| Wait for the next sync | The directory outage was brief and the account still exists in the directory | No manual change; the account stays blocked until a successful sync runs | The sync schedule for your GitLab version and that the directory is reachable again |
| Resync a single user | One account stays blocked after the directory has recovered | Triggers a lookup for that account only; other users are not touched | The single-user sync method in the LDAP documentation for your installed version |
| Unblock in the admin area | The person is confirmed active in the directory, but GitLab still shows the account as blocked | Sets the account back to active; the next sync decides whether it stays active | That the account was not removed from the directory on purpose and that the next sync will not block it again |
| Edit the user record | The lookup fails because a stored attribute, such as the LDAP identity, no longer matches the directory | Changes stored account data by hand, which can break the link to the directory entry | Which attribute the lookup uses, and a record of current values before any edit |
| Roll back a configuration change | Blocking began right after a change to LDAP server, base or filter settings | Restores earlier gitlab.rb settings and reconfigures the instance, which affects all LDAP users | A saved copy of gitlab.rb and the reconfigure steps in your change runbook |
Clearing blocked users and resyncing safely
This sequence confirms the directory is reachable, finds the accounts GitLab has blocked, and restores them one user at a time before widening the change, so a single directory fault does not turn into a wider sign-in outage.
Confirm the directory answers a test bind
Before touching GitLab, the directory team or the GitLab administrator runs a test bind from the GitLab host to the LDAP server, using the same host names, port, encryption mode and bind account that appear in the LDAP section of the GitLab configuration. Use the LDAP connection check that the official GitLab authentication documentation describes for your version, and confirm the exact command there. Confirm that a known test account authenticates and that the search base returns the expected entries. Done means the bind succeeds from the GitLab host itself, not only from an administrator workstation, because the GitLab host is the client that will be tried again later.
Check GitLab logs for LDAP errors
Review the GitLab application and authentication logs for the period when users were blocked, looking for LDAP connection failures, timeouts, bind errors and entries that show accounts moved to the blocked state after a failed lookup. Match the timestamps to the directory outage or rate limit reported by the directory team. Confirm the log file names and their locations in the GitLab monitoring and maintenance documentation for your installation method. Done means you can state, with timestamps, that the blocks started during the directory fault and that no separate cause, such as a disabled account in the directory, explains them.
Identify affected accounts in the admin area
In the Admin area, open the users list and filter for accounts in the blocked state caused by LDAP. Export or record the usernames and the directory identifier each account uses, and separate accounts that the directory still shows as active from accounts that were genuinely disabled there. Compare this list with the groups that the directory maps to GitLab roles, so you know which teams are affected. Done means you have a written list of affected accounts and a second list of accounts that must stay blocked because their directory status is disabled.
Resync one test user first
Choose one affected account that is active in the directory and resync only that user, using the single-user LDAP sync procedure in the official GitLab documentation for your version. Confirm the exact command or console steps there rather than relying on memory, and run them during a window where the administrator can watch the output. Done means the command reports the account as updated and the blocked state is cleared in the admin area for that one user.
Verify sign-in for the test user
Ask the owner of the test account, or sign in with a test identity you control, to sign in through LDAP in a private browser session. Confirm that the user reaches the dashboard, that group membership and roles match the directory, and that the user can open a project they are expected to access. Check the GitLab logs again for new LDAP errors during the attempt. Done means the sign-in succeeds, the expected roles appear, and the logs show no new failures. If any check fails, stop and return to the directory health step.
Resync the wider group in batches
Once the test user works, resync the remaining active accounts in small batches, following the documented procedure for your version, and pause between batches to watch the directory and the GitLab logs for rate limit or timeout messages. Use the blocked list from the earlier step to track progress, and leave accounts that the directory shows as disabled blocked. Done means each batch clears its accounts, no new directory errors appear, and the blocked list contains only the accounts that should remain blocked.
Record the outcome and review monitoring
Write a short record of the timeline, the affected accounts, the commands used, the sign-in checks and any remaining exceptions, and store it with your incident notes. Then confirm that the directory health check and the LDAP error alerting described in your GitLab monitoring setup would have caught this fault, and adjust thresholds if they would not. Done means the incident record is complete, every remaining blocked account has an owner and a reason, and monitoring has been checked against this incident.
Monitoring that catches a directory hiccup before users are locked out
GitLab blocks an LDAP user when a lookup or bind fails in a way it reads as a reason to block, so a short directory fault can lock out far more people than were affected. The controls below run in parallel: each one detects a different part of the failure chain, from the directory itself to GitLab's own logs, and together they shorten the time between a fault and a response.
LDAP bind checks from GitLab hosts
Run a scheduled bind and a single-user search from each GitLab node, using the same bind account and TLS settings that gitlab.rb uses. This tests the path GitLab actually takes, including DNS, firewall rules and certificate chains, which a check from a workstation may not exercise. Confirm the check runs on every node that serves sign-in, not only the primary, and that a failure pages a person rather than writing to a log nobody reads.
Authentication failure spike alerts
Alert when failed LDAP sign-ins in GitLab's production log rise sharply over a short window, compared with a normal baseline for your organization. A spike that spans many distinct usernames points to the directory, while a spike against one account points to that user. Confirm which log entries your GitLab version writes for LDAP failures, and set the baseline from your own traffic rather than a generic threshold.
Prometheus metrics where available
Scrape GitLab's Prometheus endpoints and graph sign-in and request error rates next to the directory alerts so both sources appear on one timeline. Metric names and availability depend on your installation method and version, so confirm which exporters are enabled in your deployment before writing alert rules against them. Treat this card as a complement to log alerts, not a replacement, until you have verified that the metrics capture LDAP failures.
Directory-side health and rate limit alerts
Watch the directory server for signs of load, such as connection exhaustion, lockout policy triggers, replication lag between domain controllers or query throttling. These symptoms often appear before GitLab shows errors, and they tell you whether the fault sits in the directory or on the network path. Ask the directory team which of these signals they already collect, and whether a rate limit applies to the service account GitLab uses for lookups.
Documented manual unblock runbook
Write a runbook for clearing an ldap_blocked state on individual accounts and for resyncing a single user after the directory recovers, so an on-call engineer does not improvise under pressure. Include who may run it, how the change is recorded and how to confirm that the affected users can sign in again. Test the runbook on a non-production instance before you need it, and confirm the exact commands for your GitLab version in the administration documentation.
Change control for LDAP settings
Route every change to LDAP settings, bind credentials, base DNs and filters through a reviewed change record, and test each change against a staging directory first. Many lockouts follow a small edit to a filter or a rotated service password that propagated unevenly across nodes. Confirm that settings in gitlab.rb stay identical on every node and that a rollback path is written down before the change window opens.
Design choices that keep one outage from locking everyone out
The most effective protection against a blocked-user incident is limiting how far one directory problem can reach. Start with directory redundancy: GitLab authenticates against whatever LDAP endpoints you configure, so a single domain controller or load balancer becomes a single point of failure for every LDAP-backed sign-in. Confirm with your directory team how LDAP traffic is routed during a domain controller outage, which secure LDAP endpoints GitLab can reach in each site, and whether the bind account can authenticate against more than one of them. Also review the bind account itself. It should be a dedicated service account with read access to the users and groups GitLab needs, and nothing more. A bind account that is locked by a password expiry policy or disabled during an unrelated cleanup will look, from GitLab's side, like a mass directory failure.
Keep recovery paths that do not depend on the directory. Local administrator accounts on the GitLab instance should exist, be protected with strong credentials and two-factor authentication, and be tested before you need them. Write a break-glass procedure that names who can use these accounts, where the credentials are stored, how use is logged and how access returns to normal afterward. Rehearse it on a non-production instance. Sync timing also deserves a review for large directories. Confirm how often GitLab syncs group membership in your edition and how long a full sync takes against your directory size, because a short outage during a long sync cycle can change the scope of the damage. Group sync, SCIM provisioning and blocking choices should be designed together, since a SCIM deprovisioning event can block users faster than LDAP ever will. The right balance depends on your identity architecture, so test each combination in staging before you rely on it.
Security and audit considerations for LDAP unblocking
Unblocking LDAP users is a privileged change to who can sign in, so it needs the same care as any access decision. The cards below cover verifying directory state before acting, limiting the service account, recording what was done, and protecting the directory connection itself. Confirm how each control maps to your framework with your auditor or the standard's owner.
Verify directory state before unblocking
A block triggered by a directory outage or rate limit often clears on its own once the directory recovers. Before unblocking anyone, confirm the account is enabled, not locked, expired or disabled in the directory itself, and that the user's group membership is what you expect. Unblocking an account that was disabled on purpose for a leaver or investigation reverses a control rather than fixing a fault. Make this check a written step in your runbook, not a judgment made under pressure during an incident.
Least privilege for the bind account
GitLab authenticates to the directory with a service bind account, and that account's rights determine what the sync can read. Give it read access to the user and group attributes GitLab needs and nothing more, and avoid reusing an administrator or personal account. Use a dedicated, non-interactive identity with a password rotation process your directory team owns. A bind account with excess rights turns a GitLab compromise into a directory compromise.
Logs as evidence of unblock actions
Every manual unblock changes who can access source code and CI/CD, so it should leave a traceable record. Capture who performed the action, which account was unblocked, the time, the reason and the directory state observed beforehand. Keep GitLab's own logs and your ticket or change record together, and confirm with your team how long they are retained. Without this trail, a later access review cannot show whether an unblock was legitimate.
Avoid disabling sign-in controls to end an outage
During a directory outage, the fastest-looking fix is to turn off LDAP sign-in, disable two-factor requirements or open password sign-in for everyone. Each of these widens access while the cause is still unknown, and some are hard to reverse cleanly. Prefer a documented fallback path, such as a named break-glass administrator with strong authentication, and restore normal controls as soon as the directory is healthy. Record any temporary change and its reversal in the incident record.
Encrypt the LDAP connection
LDAP carries the bind credentials and user attributes that GitLab uses to decide who can sign in. Confirm that the connection uses TLS, either through LDAPS or STARTTLS, and that GitLab trusts the directory's certificate chain. Check the configured host names and certificate validation settings in your GitLab configuration, and review them after any directory certificate change. An unencrypted or unverified connection exposes credentials to anyone on the network path.
Confirm control mapping with auditors
Access reviews, change management and logging requirements vary by framework, and the same unblock action can map to different controls in each. Ask your internal auditor or the owner of the relevant standard which controls the unblock process should support, and which evidence they expect. Use NIST SP 800-53 hardening guidance for GitLab as a reference point for configuration decisions, and document the mapping you agree on. DeployOpen prepares controls and evidence for assessments but does not issue audit opinions.
Questions teams ask before fixing LDAP lockouts themselves
How much effort does fixing LDAP blocked users in GitLab take?
The effort depends mostly on how many users are affected, whether the cause is a one-time outage or a recurring rate limit, and how much of the directory path your team can already see. A single user who needs a resync is a short task for an administrator with console access. A blocked population after a directory outage is larger work: you must confirm the directory is healthy, check which accounts GitLab marked, clear the state in a controlled way and then verify that sign-in works for a sample of users. Ask any partner to price the work against the number of affected users, the number of LDAP servers in the configuration and whether monitoring must be built as part of the same scope.
Can our own team fix blocked LDAP users without outside help?
Often yes, for a single incident, if an administrator with access to the GitLab server and the directory team can read logs together. The steps are documented in GitLab, and the most common cause, an overloaded or unavailable directory followed by automatic blocking, is well understood. Outside help becomes more useful when the lockout recurs, when the cause sits in a firewall, load balancer or directory replication path that no one on the GitLab side controls, or when the team needs evidence of the fix for an internal audit. Decide before an incident who owns the GitLab side, who owns the directory side and who approves changes.
What access and information does a diagnosis need from our team?
A diagnosis needs read access to the GitLab application and production logs for the period of the outage, the relevant LDAP settings from the GitLab configuration file, and an account that can be used to test a bind without changing anything. From the directory side, you need domain controller health and event information for the same window, plus any rate limits, account lockout policies or service account password changes that were in effect. Also ask for a change window, because clearing state and testing sign-in usually means briefly touching production authentication. Confirm with your directory team which service accounts are allowed to be used for testing.
How long does diagnosis depend on log access?
Diagnosis is limited by log access more than by any other step. Without the GitLab production log and the directory logs for the same time window, the team can only guess whether the block came from a failed bind, a timeout, a password policy change or a retry storm. Once logs are available, the first pass is usually a matter of matching timestamps between the two systems, which is quick for one incident and slower when logs are short-lived or split across servers. Ask any partner how long their diagnosis depends on log retention, and confirm your own retention period before an incident happens, since older logs may already be gone.
What should a fixed-scope engagement for LDAP lockouts cover?
A fixed-scope engagement should name the GitLab version and installation method in scope, the directory servers and LDAP settings involved, the affected user population and the deliverables. Typical deliverables include a written root cause finding, a documented procedure for clearing the blocked state and resyncing single users, a tested change plan, and monitoring that alerts on directory failures before users are locked out. Scope should also state what is excluded, such as changes to the directory itself or to network equipment. Agree the scope and timelines in writing before work starts, and ask for a quote that follows from that written scope.
Does the fix depend on the GitLab version we run?
Yes, the exact steps and the areas to check depend on the installed GitLab version, the installation method and the edition, because LDAP features and the administration paths can change between releases. GitLab ships a major release yearly, a minor release on the third Thursday of each month and patch releases twice a month, and it maintains 19.5, 19.4 and 19.3 at the time of this page. Confirm your running version against the GitLab maintenance policy before following any procedure, and plan any upgrade through the required upgrade stops rather than as part of the incident response.
What monitoring should we ask for so a directory hiccup does not lock everyone out?
Ask for alerts on directory health and on GitLab sign-in failures, not only on the GitLab service itself. Useful signals include LDAP bind failures and timeouts in the GitLab log, a sudden rise in failed sign-ins, and directory availability checked from the GitLab host. The goal is to see a directory outage early enough to pause any automated blocking or to confirm that blocking is not spreading. Ask whether the monitoring is written as part of the scope, who receives the alerts, and how the team will test them, since untested alerts often fail during the first real outage.
Does DeployOpen fix blocked users and provide compliance proof?
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, which includes diagnosing and fixing authentication problems in a GitLab deployment under a written scope. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies do that work. Most engagements are fixed-scope, and ongoing support or upgrades are available as retainers, so ask for the scope in writing before the work starts.
How DeployOpen scopes and supports LDAP troubleshooting for GitLab
DeployOpen handles this work as a fixed-scope engagement with a written scope, deliverables and timeline agreed before any work starts. For blocked LDAP users, that scope usually covers four parts: diagnosing why accounts entered the ldap_blocked state during a directory outage or rate-limit event, writing a runbook for clearing that state and resyncing individual users, designing the monitoring that flags directory failures before they lock accounts out, and verifying the result in a controlled test. Diagnosis starts with the evidence your team already has, such as GitLab production logs, the directory's own event logs and the LDAP bind account's history, so the findings tie to specific users, groups and times rather than general advice. The scope should name which LDAP server, bind account and GitLab instance are covered, and which of your directory replicas or network paths are in or out.
Ownership stays with your organization throughout. Your team keeps the directory, the bind account, the network paths, the GitLab instance and the change approvals. DeployOpen works inside those systems under access you grant and documents every setting it recommends, including any change to gitlab.rb, so your administrators can review and apply it under your change process. Before signing, ask the proposed partner to state in writing who holds administrator credentials, where the runbook will be stored, and what the handover includes. Ongoing support, monitoring review and periodic testing after directory or GitLab upgrades are available as retainers, which keeps the runbook current as your directory and GitLab versions change. DeployOpen does not issue audit reports, certifications or attestations, so any evidence produced by this work is operational evidence for your own assessors to evaluate.
