When ldap-auth fits Apache APISIX LDAP authentication
Choose ldap-auth when your API callers already hold accounts in Active Directory or OpenLDAP and you want the gateway to check those credentials before a request reaches an upstream service. The plugin takes the caller's directory credentials, performs an LDAP bind against your directory, and lets APISIX accept the request only when the bind succeeds. Under the APISIX documentation, ldap-auth is one of the authentication plugins that identify a consumer, so each authenticated caller maps to a consumer object you define in APISIX, and the consumer's plugin settings (such as rate limits or access restrictions) apply to that caller. APISIX also documents a second plugin, ldap-auth-advanced, so confirm in the plugin list which one matches the directory layout and the consumer lookup you need before you build around either.
The fit depends on how your callers are represented in the directory. Plugin-level bind settings, the base DN, and the attribute used to find each caller determine which consumer a bind resolves to, and mistakes here show up as callers mapped to the wrong consumer or rejected without a clear reason. Ask your directory team which account type your API callers use (named user accounts, service accounts, or groups), whether those accounts can be bound directly by a non-interactive client, and whether your security policy allows a gateway to hold a bind account. If callers are partners outside your directory, or if you need a single sign-on flow with a browser login, the directory is usually not the right source of identity for the gateway, and an identity provider in front of the directory is the better route.
Plan the directory side before you configure the gateway. Confirm the exact LDAP server, port and TLS setup your environment supports, and whether the directory is Active Directory (commonly run on Windows Server) or OpenLDAP. The Active Directory and Entra ID comparison from Microsoft notes that most on-premises applications authenticate against Active Directory with LDAP, which makes it a common source for this pattern, while the OpenLDAP 2.6 Administrator's Guide describes slapd's LDAPv3 support and TLS certificate options. Your directory team should confirm the deployment details for their own environment. Also confirm the APISIX version you run, because certificate verification and DN handling for ldap-auth changed in 3.18.0, which affects how you write the configuration and test it.
How ldap-auth identifies and checks a caller
A caller's Basic credentials are checked by a bind against the directory, and the APISIX consumer is then found from the bind DN. Each step depends on the directory choice and on how the DN is escaped, so the cards below follow the request from the header to the consumer lookup.
Basic credentials become a bind
The caller sends credentials in the HTTP Basic header, and ldap-auth uses them to attempt a bind against the configured directory. A successful bind is the only proof of identity the gateway receives, so a wrong bind DN template or search base produces failures that look like bad passwords. Check the bind template against a real user from each directory you serve before any route is switched over.
Active Directory Domain Services as the source
Active Directory Domain Services stores users and groups and replicates them to every domain controller in a domain. Most organizations that bind from APISIX will point at AD DS, which Microsoft describes as the on-premises directory that most applications already authenticate against with LDAP. Confirm which domain controllers and ports your network team permits for the gateway before testing.
OpenLDAP slapd as the source
OpenLDAP's slapd server implements LDAPv3 over IPv4, IPv6 and Unix IPC, with strong authentication through SASL and certificate authentication through TLS. Teams running Linux-based directories use slapd, and its replication options matter here because a single directory outage stops every gateway bind. Confirm the schema, the user naming attribute and the replication topology before you write the bind template.
Consumer lookup keyed on the escaped bind DN
From APISIX 3.18, the consumer lookup uses the escaped bind DN, so a user DN containing RFC 4514 special characters must be written in its escaped form to match the consumer. A consumer created with the unescaped name will silently fail to resolve for those users. Test one user whose name includes a comma or plus sign for each consumer before rollout.
Consumer identity set by the directory entry
The consumer that ldap-auth resolves is the one whose configured identity matches the directory entry used for the bind. Design one consumer per user or per directory group that needs its own limits, and map each consumer name to the exact DN the directory returns. Mismatched names between the consumer and the DN are the most common source of unexpected 401 responses after go-live.
Credentials sent to the gateway on every call
Because ldap-auth checks the Basic header on each request, the caller's password crosses the gateway and each request triggers a directory bind. TLS on the client connection and on the LDAP connection both protect that password, and TLS verification must be on for the LDAP leg. Plan the directory load per request and confirm the directory team accepts that bind volume.
Configuration options and when each fits
This table lists the ldap-auth settings a reviewer must decide before build, what each one controls and where teams usually get it wrong. Confirm every key name and default against the plugin page for your APISIX version, since this table gives no default values. The main takeaway is that TLS verification and DN handling need explicit decisions, because APISIX 3.18.0 changed how both behave.
| Setting | What it controls | Decision to make |
|---|---|---|
| ldap_uri | Address of the directory server the gateway binds to and searches | Use an LDAPS address where traffic leaves the gateway host, and confirm the scheme and port expected by your APISIX version |
| base_dn | Point in the directory tree where user searches start | Scope it to the OU that holds API callers, so service accounts and unrelated users are not matched |
| Bind DN and search filter, or user DN pattern | How the gateway turns a caller's username into a directory entry it can authenticate | Choose a search-then-bind approach if users sit in varied OUs, or a fixed DN pattern if every caller shares one layout |
| tls_verify | Whether the gateway checks the directory server certificate chain | Keep verification on and supply the correct CA certificate, since APISIX 3.18.0 began performing real certificate checks |
| Consumer mapping | Which APISIX consumer a successful LDAP login is attributed to | Map each caller or application to one consumer, and key it on the escaped bind DN so rate limits and audit logs stay correct |
| ldap-auth | Basic LDAP bind authentication for a defined set of callers | Keep it when one directory, a small number of settings and simple per-user consumers meet the requirement |
| ldap-auth-advanced | Additional LDAP lookup and matching options beyond the basic plugin | Choose it when lookup logic, group-based matching or a more complex directory layout needs settings ldap-auth does not expose |
Why TLS verification and DN escaping change in 3.18
Upgrading to APISIX 3.18.0 can break ldap-auth callers that worked before, because the release changed two behaviors that earlier versions handled silently. First, tls_verify now performs real certificate verification. The previous LDAP library accepted the setting but ignored it, so a gateway configured with tls_verify set to true may have been connecting to a directory with an untrusted, expired or mismatched certificate without any error. After the upgrade, those connections fail. Before you upgrade, confirm that the directory certificate chains to a CA the gateway trusts, that its subject or SAN matches the host name in the configuration, and that the CA bundle is present on every gateway node. Treat a failed bind after the upgrade as a certificate problem first, not as a credential problem.
Second, consumer lookup now keys on the escaped bind DN. Plugin configuration that stored a user_dn containing RFC 4514 special characters, such as a comma, plus sign, equals sign, quotation mark, backslash or leading space in a common name, must be rewritten into the escaped form before the consumer will match. An illustrative example: a user whose common name is Smith, Jane would have a DN with a comma that must be escaped as \, in the stored value. A consumer stored with the unescaped string will still authenticate at the directory, but the gateway will not map the request to that consumer. Export your consumer definitions through the Admin API, list every user_dn containing those characters, and rewrite and test them in a staging gateway before the production change.
How to set up ldap-auth on a consumer
This sequence takes an LDAP directory from a confirmed LDAPS endpoint to a tested APISIX consumer that authenticates callers through ldap-auth. Each step produces a artifact or check that the next step depends on, so the gateway enforces the directory's answer for valid, invalid and disabled accounts.
Confirm directory type and LDAPS endpoint
The platform team confirms whether the directory is Active Directory Domain Services, OpenLDAP or another LDAP service, and records the host name, port and base DN that APISIX will reach. Ask the directory owner which domain controllers or servers are approved for gateway traffic and whether LDAPS is offered on them. Done means you can open a TLS connection to the chosen endpoint from the gateway network and see the certificate presented, with its subject name matching the host name you will configure.
Obtain the CA chain for verification
Ask the directory team or your internal PKI owner for the full certificate chain that issued the LDAPS server certificate, including any intermediate CA. Store the PEM bundle where the gateway can read it and record which CA it came from and its expiry. Because APISIX 3.18.0 performs real certificate verification for ldap-auth tls_verify, a missing or incomplete chain will cause connections to fail, which is the behavior you want to find now. Done means a test handshake from the gateway host succeeds using only that bundle.
Create a least-privilege service bind account
The directory administrator creates a dedicated service account used only for the bind that APISIX performs. It should have read access to the user objects and the attributes your login logic needs, and no write, group-management or administrative rights. Record its distinguished name and store its password in your secrets manager, not in route files. Done means a manual bind with that account succeeds and a search for a known test user returns the expected entry, while a write attempt is refused.
Create the consumer with the ldap-auth credential
Create an APISIX consumer through the Admin API or your configuration pipeline and attach an ldap-auth credential that maps the caller's user DN pattern to the consumer. Escape RFC 4514 special characters in any DN value, because APISIX 3.18.0 keys the consumer lookup on the escaped bind DN. Done means the consumer appears in the Admin API with the credential present and the DN stored in the escaped form you verified with a manual bind.
Route the service behind the plugin
Attach the ldap-auth plugin to the route for the service, pointing it at the LDAPS endpoint, the CA bundle and the service bind account, with tls_verify enabled. Keep the route in a staging environment until the tests pass. Note that the plugin identifies a consumer, so any consumer-restriction or rate-limit rules should be defined against that consumer. Done means the route returns a challenge for unauthenticated requests and the configuration is saved in your version-controlled gateway definitions.
Test valid, invalid and disabled accounts
Run three test sets against the staging route: a valid directory user with correct credentials, a user with a wrong password, and a disabled or locked account whose bind should fail even if the password is correct. Confirm that the valid user reaches the upstream with the expected consumer identity, and that the other two receive a rejection without reaching the upstream. Also confirm that the gateway logs record the outcome without logging passwords. Done means each case produces the expected status and log entry, and you have the results recorded for the change review.
Confirm disabled account behavior with the directory team
Disabled and expired accounts depend on how the directory reports them during a bind, which differs between Active Directory and OpenLDAP and between deployment setups. Ask the directory owner to disable a test account, then repeat the test to confirm the gateway refuses it. Where a disabled account still authenticates, treat that as a blocking finding and decide with the directory team whether to add a group check or move to OpenID Connect. Done means the directory owner has signed off on the observed behavior for each account state you rely on.
Promote the route and document the rollback
Move the validated configuration to production through your normal change process and record the CA bundle version, service account owner and the consumer list. Write down how to remove the plugin or revert the route if the directory becomes unreachable, and who approves that action. Done means production shows the same three test outcomes on a controlled test account, and the rollback procedure has been rehearsed once.
Active Directory and OpenLDAP considerations
The directory behind ldap-auth decides how bind accounts are created, how TLS is verified and how the service survives an outage. The cards below compare Active Directory and OpenLDAP on the points that matter at the gateway, then cover licensing and the Linux-only alternative.
Active Directory replication scope
Active Directory Domain Services replicates directory data to every domain controller in a domain, so a gateway can point at any reachable controller. Check which controllers are reachable from the APISIX data plane subnets, which DNS names resolve to them, and whether a load balancer or a fixed list of hosts will be used. Confirm with your directory team how a failed controller is handled, because the gateway configuration must name a host or a load-balanced address.
LDAP access in Windows-centric estates
Most on-premises applications authenticate against Active Directory with LDAP, Windows-integrated authentication or header-based authentication. For a gateway, LDAP is the practical option because ldap-auth performs a bind for each caller. Ask the directory team which service account may perform binds, whether that account has read access to the user attributes the gateway needs, and whether LDAPS or StartTLS is available on the domain controllers the gateway will reach.
OpenLDAP replication and TLS
OpenLDAP slapd implements LDAPv3 over IPv4, IPv6 and Unix IPC, with strong authentication through SASL and certificate authentication through TLS. It supports single-provider, multiple-consumer replication and multi-provider replication for environments where a single point of failure is not acceptable. Plan the consumer nodes, the certificate chain that APISIX must trust and the failover behavior before the gateway is pointed at them.
Linux-only estates and FreeIPA trusts
If the identity source is Linux-based, FreeIPA can establish a cross-forest trust with an Active Directory domain on Windows Server 2008 R2 or later, so Active Directory users can reach Linux resources. This is a directory design decision, not a gateway setting. Confirm whether the users who call the APIs live in Active Directory, FreeIPA or OpenLDAP, and whether the directory you choose is the one ldap-auth will query.
Windows Server licensing
Windows Server 2025 is licensed per core, with a minimum of 16 cores per server and 8 per processor. Both Standard and Datacenter editions also need a Windows Server Client Access License for every user or device that accesses the server, so API callers may count if they connect to the directory. Microsoft's published price for 16 core licenses is a suggested figure that varies by region, and pay-as-you-go pricing through Azure Arc is also listed. Ask Microsoft or your reseller for a current quote.
OpenLDAP licensing and support
OpenLDAP Software is available under the OpenLDAP Public License, which the project describes as a non-restrictive, free, open-source license. The license cost is zero, so the budget question shifts to the people who run the servers, the replication design and any commercial support contract you choose to buy. Confirm the license terms with your legal team, and decide which release line to deploy, since the current feature release and long term support release differ.
When OpenID Connect through an identity provider is the better route
Choose OpenID Connect through an identity provider when the callers or the access model go beyond what a directory bind can handle well. ldap-auth fits machine-adjacent or internal callers that authenticate with a username and password against Active Directory or OpenLDAP. It is a weaker fit when your clients are SaaS applications, when they need tokens rather than repeated credential checks, when multi-factor authentication must be enforced at sign-in, or when many services need the same login. In those cases, an identity provider that issues OAuth 2.0 or OIDC tokens usually gives you a single place to manage sessions, MFA and revocation, and APISIX can validate the result with the openid-connect plugin. That plugin is documented to work with identity providers such as Keycloak, Microsoft Entra ID and Okta, among others, and supports flows including authorization code, client credentials and token introspection.
Microsoft's comparison of Active Directory and Entra ID says most on-premises applications authenticate against Active Directory with LDAP, Windows-integrated authentication or header-based authentication, and that SaaS applications need a federation system such as AD FS. It also notes that organizations with existing Active Directory use Microsoft Entra Connect to sync identities to Microsoft Entra ID. Before you commit to ldap-auth for a SaaS-facing or token-based design, confirm with your identity team whether Entra Connect or an existing federation service already provides the tokens you need, because that changes which path has the lower operating burden. Confirm the exact sync scope and MFA policy in your own tenant, since those settings are not part of the supplied facts.
A practical test is to ask who will own each credential and its lifecycle. With ldap-auth, the password check, account lockout and password rotation stay in the directory, and APISIX holds the consumer mapping and bind DN handling. With OIDC, the identity provider owns sign-in and token issuance, and APISIX owns signature or introspection checks, issuer and audience validation and fail-closed behavior. If your audit scope requires MFA or short-lived tokens for API callers, plan the OIDC route as the target and treat ldap-auth as a bridge only where the directory is the sole source of identity.
Questions buyers ask before hiring help with ldap-auth
What drives the effort and cost of an ldap-auth implementation?
The main drivers are the number of directories and domains the gateway must check, whether connections use LDAPS with a certificate chain your team must trust, how many consumers and bind identities need to be modeled, and how much testing is required before rollout. Each directory adds its own bind account, search base, and certificate handling. Each consumer adds a mapping that must be tested for correct allow and deny results. A written scope should list these counts explicitly so that you can compare quotes on the same basis. Ask for the testing approach as a separate line item, since it is often the largest share of effort when several directories are involved.
What does the work need from our directory and network teams?
You will need a directory administrator who can create a read-only service account for the gateway and confirm the search base and attributes the gateway should use. The network and security team should provide the LDAPS endpoint, the certificate authority chain that signs it, and firewall rules that allow the gateway nodes to reach the directory on the required port. If you use Active Directory, the team should confirm which domain controllers are reachable from the gateway subnet. Expect to provide a test account for each access scenario, and a named owner who can approve changes to the service account password and certificate renewals.
Can our own team implement ldap-auth without outside help?
A team with APISIX experience, directory administration skills and access to a test environment can often implement ldap-auth alone, especially for one directory and a small number of consumers. The work is most difficult where certificate trust, escaped bind DNs and consumer mapping interact, because errors in these areas can look like successful logins while allowing the wrong callers. Outside help is most useful when several directories are involved, when the team has not handled LDAPS trust chains before, or when independent review of the configuration is needed. Whichever route you choose, ask for the verification steps in writing so your team can repeat them after handover.
How does the APISIX 3.18 change affect existing ldap-auth clients?
APISIX 3.18.0 changed two behaviors that existing ldap-auth setups may depend on. The tls_verify option now performs real certificate verification, where the previous library silently ignored it, so connections that previously worked with an untrusted or misconfigured certificate may now fail. The consumer lookup also uses the escaped bind DN, so user_dn values containing RFC 4514 special characters must be rewritten. Before upgrading, inventory every route that uses ldap-auth, confirm each certificate chain, and test lookups for users whose DNs contain special characters. Plan the upgrade in a staging environment first, and confirm the exact procedure in the APISIX changelog.
What typically determines how long an ldap-auth project takes?
Duration depends mainly on how quickly the directory and certificate owners respond, how many directories and consumer groups are in scope, and whether a staging environment with a representative directory exists. Delays often come from waiting for a service account, a certificate chain, or a firewall change rather than from APISIX configuration itself. Consumer mapping and testing of denied access also take longer when the directory structure is complex or inconsistent. Ask any provider for a schedule that separates client dependencies from implementation tasks, so you can see which steps depend on your teams. No general duration applies, since it depends on the written scope.
Does DeployOpen issue compliance attestations for our ldap-auth setup?
No. DeployOpen does not issue audit reports, attestations or certifications. It can plan and configure the gateway, document the authentication design and prepare evidence such as configuration records, test results and access decisions for your compliance assessment. Independent auditors and certification bodies perform the assessment and decide whether controls meet a given requirement. Before the engagement starts, ask your auditor which evidence they expect for directory-based authentication, and include those items in the written scope so they are produced during the work.
Security and operational considerations
An LDAP bind gives the gateway a standing path into your directory, so its credentials, transport and query scope need the same care as the directory itself. The cards below cover the controls to decide before go-live and the checks to repeat after it.
Service bind account and password
The gateway authenticates to the directory with a dedicated service bind account, and its password must not sit in plain route configuration that many people can read. Use a read-only account that exists only for lookups, store its password in a secrets backend your team already controls, and confirm which Admin API role can read consumer configuration, since consumer entries carry the bind DN. Ask who approves changes to this account.
LDAPS with verified certificates
Credentials sent over plain LDAP are exposed on the wire, so the bind should use LDAPS with tls_verify enabled and the directory's certificate chain trusted by the gateway. APISIX 3.18.0 began performing real certificate verification in ldap-auth, which earlier releases silently skipped. Confirm your running version, then test that a connection to a host with a wrong certificate fails.
Least-privilege search scopes
Set the search base and filter as narrowly as the user population allows, so a lookup cannot return directory-wide results or groups the API does not serve. Restrict the bind account's read permissions to the attributes the gateway needs. Escape user input before it reaches a DN or filter, because unescaped special characters can match the wrong entry.
Logging failed binds
Failed binds are the earliest signal of password guessing or a misconfigured client, so route the gateway's error logs to your central log platform and keep them with timestamps and client addresses. Also enable directory-side logging on the domain controllers or slapd server. Check that log lines never record the password supplied by the caller or the bind account's password.
Rate limits on brute-force attempts
LDAP binds are an expensive, slow check that attackers can repeat from many callers. Put limit-count or a similar limit in front of the authentication route, keyed by client address or API key, and set a lockout or backoff policy in the directory for repeated failures. Test the limit with a scripted set of failed attempts so you know the threshold and the response callers receive.
Rotating the bind secret
Plan rotation of the bind password as a routine change. Create the new password in the directory, update the secrets backend, reload the gateway configuration, confirm successful binds, then retire the old password. Record who owns each step and how long the old password stays valid. Confirm with your directory team how your Active Directory or OpenLDAP policy handles password history and service account expiry.
Admin API and etcd hardening
The bind configuration is only as protected as the Admin API that writes it and the etcd cluster that stores it. Restrict Admin API access, protect etcd with transport encryption and access control, and review the controls in the security hardening group before the LDAP route goes live.
How DeployOpen scopes and delivers APISIX LDAP authentication
DeployOpen plans and delivers ldap-auth on APISIX inside your own infrastructure, starting with a written scope that names your directory, bind accounts and consumer model. We build, test and document the configuration so your team can run it after handover, and we offer ongoing support as a retainer.
How we scope
- Confirm whether the directory is Active Directory, OpenLDAP or another LDAP service, and who owns it.
- Define which API callers authenticate through LDAP and which stay on keys, JWTs or mTLS.
- Agree the bind DN, search base, TLS trust chain and consumer mapping in the written scope before work starts.
- Record the APISIX version you run and confirm it includes the 3.18 tls_verify and DN escaping changes.
How we build
- Configure ldap-auth or ldap-auth-advanced routes and consumers in a non-production APISIX environment first.
- Enable and verify TLS certificate checking against your directory CA, not a disabled or ignored setting.
- Escape user DN values that contain RFC 4514 special characters and test lookups with those names.
- Test valid logins, wrong passwords, disabled accounts and directory outages against each protected route.
How we hand over
- Deliver the APISIX configuration, consumer design and bind account scope as versioned files with a runbook.
- Document how to rotate the bind account password and renew directory certificates without downtime.
- Walk your operations and security teams through the test cases, expected denials and logging output.
- Provide a record of what was changed, tested and left open, so your auditors can review the evidence.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, APISIX upgrades and continuous testing are available as a retainer, which we can quote from your scope.
- Upgrade reviews re-check TLS and DN handling against each APISIX release before your team moves to it.
- Confirm with DeployOpen whether OpenID Connect through your identity provider suits your callers better.
