HashiCorp Vault — Userpass & LDAP

2 minute read

Userpass and LDAP are human-friendly auth methods. Userpass stores credentials in Vault; LDAP validates against an external directory.

Userpass Auth Method

Enable Userpass

vault auth enable userpass

Create Users

# Create a user with policies
vault write auth/userpass/users/alice \
    password="alice-password" \
    policies="dev-team" \
    token_ttl=8h \
    token_max_ttl=24h

vault write auth/userpass/users/bob \
    password="bob-password" \
    policies="ops-team,dev-team" \
    token_ttl=8h

Login

# Login via CLI
vault login -method=userpass username=alice password=alice-password

Expected output:

Success! You are now authenticated. The token information displayed below
is already stored in the token helper.

Key                    Value
---                    -----
token                  hvs.CAESI...
token_accessor         abc123
token_duration         8h
token_renewable        true
token_policies         ["default", "dev-team"]
identity_policies      []
policies               ["default", "dev-team"]
token_meta_username    alice

Login via API

curl -s --request POST \
     --data '{"password": "alice-password"}' \
     "$VAULT_ADDR/v1/auth/userpass/login/alice" | jq

Manage Users

# List users
vault list auth/userpass/users

# Read user config
vault read auth/userpass/users/alice

# Update password
vault write auth/userpass/users/alice password="new-password"

# Update policies
vault write auth/userpass/users/alice policies="admin-team"

# Delete user
vault delete auth/userpass/users/bob

LDAP Auth Method

LDAP authenticates users against an external LDAP directory (Active Directory, OpenLDAP, etc.).

Enable LDAP

vault auth enable ldap

Configure LDAP Connection

# Configure LDAP (Active Directory example)
vault write auth/ldap/config \
    url="ldaps://ldap.example.com:636" \
    userdn="OU=Users,DC=example,DC=com" \
    groupdn="OU=Groups,DC=example,DC=com" \
    userattr="sAMAccountName" \
    groupattr="cn" \
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
    binddn="CN=vault-svc,OU=Service Accounts,DC=example,DC=com" \
    bindpass="service-account-password" \
    certificate=@ldap-ca.pem \
    insecure_tls=false \
    starttls=false

# Configure LDAP (OpenLDAP example)
vault write auth/ldap/config \
    url="ldaps://ldap.example.com:636" \
    userdn="ou=People,dc=example,dc=com" \
    groupdn="ou=Groups,dc=example,dc=com" \
    userattr="uid" \
    groupattr="cn" \
    groupfilter="(|(memberUid={{.Username}})(member={{.UserDN}}))" \
    binddn="cn=admin,dc=example,dc=com" \
    bindpass="admin-password"

Map LDAP Groups to Policies

# Map "engineering" LDAP group to Vault policies
vault write auth/ldap/groups/engineering policies="dev-team,deploy"

# Map "sre" group
vault write auth/ldap/groups/sre policies="ops-team,admin-read"

# Map specific users (overrides group policies)
vault write auth/ldap/users/alice policies="admin-team"

Login with LDAP

vault login -method=ldap username=alice
# Enter password at prompt

# Or non-interactively
vault login -method=ldap username=alice password=alice-ldap-pass

Userpass vs LDAP

Feature Userpass LDAP
User store Vault internal External LDAP directory
Password management Manual in Vault Managed by LDAP/AD
Group mapping Manual policy assignment Automatic from LDAP groups
SSO integration ❌ ✅ (via AD/LDAP)
Best for Dev/test, small teams Enterprise with existing AD/LDAP
MFA support Vault MFA LDAP + Vault MFA

Security Best Practices

Practice Why
Use LDAP over TLS (ldaps://) Prevent credential sniffing
Use a dedicated service account for bind Limit blast radius
Map LDAP groups (not individual users) Easier management
Set token TTLs Limit exposure of leaked tokens
Prefer OIDC over Userpass for humans Better UX, supports MFA

Quick Reference

Command Description
vault auth enable userpass Enable userpass
vault write auth/userpass/users/NAME password=PASS policies=POL Create user
vault login -method=userpass username=NAME Login
vault auth enable ldap Enable LDAP
vault write auth/ldap/config url=URL ... Configure LDAP
vault write auth/ldap/groups/GROUP policies=POL Map LDAP group
vault login -method=ldap username=NAME LDAP login

Next: AppRole

You may also enjoy