Practical LDAP Auth in HashiCorp Vault: Integrating Existing Directories

LDAP auth integrates Vault token issuance with an existing corporate directory (Active Directory or OpenLDAP). The biggest benefit is that you can assign policies through existing groups without adding new local users.

Based on HashiCorp Vault's official behavior, this article covers the concepts most often tested on the Vault Associate exam alongside the points teams commonly miss in real deployments.

Why Integrate Vault with LDAP (Overview and Prerequisites)

LDAP is one of Vault's auth methods. It delegates password verification to the directory and issues a Vault token on successful authentication. By mapping directory groups to Vault policies, you can centralize authorization management.

Stable prerequisites: an LDAP/LDAPS connection, a bind account for searches (avoid anonymous bind), clearly defined user and group DN scopes, and configured TLS trust. The exam frequently asks where policies are attached and what gets configured at which endpoint.

• Prerequisite check: Vault can reach the LDAP server on 389/TCP (StartTLS) or 636/TCP (LDAPS)
• Provision a service account (binddn/bindpass) with enough rights to search users and groups
• Pre-build a mapping table of user group names to the Vault policies you will assign
• Provide the LDAP server's CA cert to Vault via the certificate parameter. Never use insecure_tls in production

High-level LDAP authentication flow

Core Configuration Items and Safe Defaults

URL and TLS: use ldaps:// or ldap:// + starttls=true. Either way, pass a trusted CA via certificate and keep insecure_tls set to false.

Bind for searching: specify binddn and bindpass to search for users and groups. Set deny_null_bind=true to explicitly reject anonymous binds.

User and group scope: configure userdn (e.g. ou=Users,dc=example,dc=com) and groupdn. userattr is typically uid for OpenLDAP and sAMAccountName for AD. Enabling discoverdn=true makes it easier to resolve a DN from a username.

• In production, require LDAPS or StartTLS (and provide the certificate chain to Vault)
• Keep deny_null_bind=true and insecure_tls=false
• Validate userattr and groupfilter against your specific directory implementation
• Attach policies at auth/ldap/groups/<name> or users/<name> (manage by group as the default)

Step-by-Step Implementation (Enable, Configure, Map, Test)

1) Enable the auth method: enable it with an explicit path (e.g. auth/ldap/).

2) Configure the connection: set the LDAP/LDAPS URL, binddn, search scope, and TLS trust.

3) Map policies: associate directory group names with Vault policies (by group as the default).

• Start by assigning a limited policy for verification and confirm no unintended permissions are granted
• Watch for case-sensitivity differences in group names (behavior varies by directory implementation)
• Inspect the policies on the issued token after a successful login to catch missing mappings

CLI example for configuration and testing

vault auth enable -path=ldap ldap

vault write auth/ldap/config \
  url="ldaps://ldap.example.com:636" \
  binddn="cn=vault-bind,ou=svc,dc=example,dc=com" \
  bindpass="s3cr3t" \
  userdn="ou=users,dc=example,dc=com" \
  userattr="uid" \
  groupdn="ou=groups,dc=example,dc=com" \
  groupfilter="(&(objectClass=groupOfNames)(member={{.UserDN}}))" \
  starttls=false \
  insecure_tls=false \
  certificate=@/etc/ssl/certs/ldap-ca.pem \
  discoverdn=true \
  deny_null_bind=true

# Map groups to policies
vault write auth/ldap/groups/platform-admin policies="admin,kv-ro"
vault write auth/ldap/groups/dev policies="default,kv-ro"

# Optionally override per user (keep to a minimum)
# vault write auth/ldap/users/alice policies="breakglass"

# Login test
echo "<password>" | vault login -method=ldap -format=json username=alice

# Tune the auth method (e.g. token type)
vault auth tune -token-type=default-service ldap/

AD vs. OpenLDAP Differences and Filter Examples (with Comparison Table)

Because schemas and attribute names differ, the right userattr and groupfilter are not the same for AD and OpenLDAP. AD typically uses sAMAccountName or UPN, the group member attribute, and the matching rule for nested groups (1.2.840.113556.1.4.1941). For OpenLDAP, the filter depends on whether you use groupOfNames or posixGroup along with uid.

Vault searches for groups using groupfilter and attaches policies via the auth/ldap/groups/<name> mapping against the returned group names. Whether you use the {{.UserDN}} or {{.Username}} template variable in groupfilter depends on what the directory's group entries contain (DN vs. name).

• AD: userattr=sAMAccountName with member:...=UserDN is the solid choice. Consider the in-chain rule for nested groups
• OpenLDAP: either uid + groupOfNames(member=UserDN), or posixGroup(memberUid=Username)
• Iterate on groupfilter incrementally, validating with ldapsearch to confirm the expected groups are returned

Filter examples by use case

# AD: direct group membership
(&(objectClass=group)(member={{.UserDN}}))

# AD: membership including nested groups (in-chain)
(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))

# OpenLDAP: groupOfNames
(&(objectClass=groupOfNames)(member={{.UserDN}}))

# OpenLDAP: posixGroup (match by username)
(&(objectClass=posixGroup)(memberUid={{.Username}}))

Operations and Security Considerations (Rotation, Certificates, Auditing, Incidents)

Credential rotation: rotate bindpass on a schedule and automate login tests after applying the change to detect failures early. Provide a mechanism to safely run vault write from CI/CD.

Certificate operations: when the LDAP server's CA changes, update the certificate parameter before switching over to avoid disruption. Avoid the pattern of temporarily setting insecure_tls=true to muddle through.

Auditing: enable a Vault audit device (file/syslog/etc.) and record events for writes to auth/ldap/login. If failures persist, correlate against the LDAP server's logs.

• Periodically verify the bind account is still valid (detect expiration and lockouts)
• Verify the group mapping result (policies) via the audit log
• Pre-validate filter changes with ldapsearch in a staging environment
• Roll out certificate changes in stages during maintenance windows

Representative operational commands

# Rotate the bind password
vault write auth/ldap/config \
  binddn="cn=vault-bind,ou=svc,dc=example,dc=com" \
  bindpass="<new-password>"

# Detailed list of LDAP auth methods
vault auth list -detailed

# Audit (example: file output)
vault audit enable file file_path=/var/log/vault_audit.log

Exam Prep Angles and Pitfalls (for the Associate Exam)

Can you name where policies are attached? You write policies at auth/ldap/groups/<groupname> or users/<username>. groupfilter itself is just a search condition; policy attachment is a separate concept.

Login path: users log in with vault login -method=ldap username=<name> (or auth/ldap/login/<name>). The user's password is not stored in Vault (it is verified by LDAP).

TLS basics: do not use insecure_tls in production; provide trust via certificate. If you use ldap://, set starttls=true.

• Pitfall: changing groupfilter does not attach policies unless a mapping exists under auth/ldap/groups
• Pitfall: StartTLS uses 389/TCP and LDAPS uses 636/TCP. Don't forget to confirm firewall exceptions
• Pitfall: certificate chain mismatches cause TLS failure. Include intermediate CAs in the certificate you pass

Check Your Understanding

Frequently Asked Questions