Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Authentication Methods

Userpass and LDAP Authentication

Set up username and password login (userpass) and directory login (LDAP) in Vault: creating users, mapping LDAP groups to policies, and logging in with the CLI.

Two of the simplest ways for people to log in to Vault are the userpass method, which stores usernames and passwords inside Vault, and LDAP, which checks credentials against a directory such as Active Directory or OpenLDAP. Userpass is ideal for labs and tiny teams; LDAP lets an existing directory control who gets in and which policies they receive.

This lesson shows setup and login for both and how group membership turns into policies. Models let you run the mapping logic.

Vault, LDAP servers and the userpass backend are not available here. The commands are read-only and no output is invented. The Python examples model password hashing and group mapping in simplified form.

Userpass

Enable the method and create a user, attaching policies:

Terminal
vault auth enable userpass
vault write auth/userpass/users/alice password="change-me-now" policies="dev-read"

Passwords stored by Vault are hashed; they cannot be read back. Log in:

Terminal
vault login -method=userpass username=alice

The CLI prompts for the password and prints the token info. To change a user's policies later, write the user again, or use vault write auth/userpass/users/alice/policies policies="dev-read,ops". Tokens issued before the change keep their old policies until they expire, which is a general rule for Vault tokens.

Useful settings are token_ttl, token_max_ttl and token_policies (the newer, preferred names for the common token parameters), which are shared by many auth methods.

Userpass has no MFA of its own, no password policy beyond what you enforce, and no link to a directory, so it does not scale to many people. For production teams, use LDAP or OIDC.

LDAP

Configure the connection, then map groups to policies:

Terminal
vault auth enable ldap

vault write auth/ldap/config \
    url="ldaps://ldap.example.internal" \
    userdn="ou=People,dc=example,dc=internal" \
    userattr="uid" \
    groupdn="ou=Groups,dc=example,dc=internal" \
    groupattr="cn" \
    binddn="cn=vault,ou=Services,dc=example,dc=internal" \
    bindpass="$LDAP_BIND_PASSWORD" \
    [email protected]

vault write auth/ldap/groups/engineering policies="dev-read"
vault write auth/ldap/groups/sre policies="ops,dev-read"

The bind account (binddn) lets Vault search for users and their groups; give it read-only access. Use ldaps:// or StartTLS, because credentials cross the wire. The user's group names come from the directory, and each group that has a matching mapping in Vault contributes its policies, so the final policy set is the union.

Logging in is the same as before:

Terminal
vault login -method=ldap username=alice
sequenceDiagram
    participant U as User
    participant V as Vault (auth/ldap)
    participant D as Directory
    U->>V: username + password
    V->>D: bind as the user to verify
    V->>D: search groups with the bind account
    D-->>V: groups: engineering, sre
    V-->>U: token with union of mapped policies

Vault never stores LDAP passwords; it passes them to the directory.

Mapping groups to policies

Python Union of policies from LDAP groups

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Group matching is case-sensitive in some configurations, and a directory group with no mapping contributes nothing. A user in no mapped group still gets the default policy, which is attached to every token unless you disable it.

Password hashing model

Userpass stores a hash, never the password. This model shows salted, iterated hashing with the standard library, a simplified stand-in for the idea (Vault uses bcrypt internally; real systems should use bcrypt, scrypt or Argon2, not this loop).

Python Why salted slow hashes protect stored passwords

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

compare_digest takes the same time however many bytes match, which avoids leaking information through timing.

Operational tips

  • With LDAP, set token_ttl to a working-day length, and disable stale users in the directory: their existing tokens still work until they expire, so revoke by accessor or entity if someone leaves in an emergency.
  • Do not use a personal account as the bind DN.
  • Keep a break-glass admin path that does not depend on LDAP being reachable, such as a userpass admin or the generate-root procedure.
  • Many organizations prefer OIDC for SSO, which can enforce MFA at the identity provider.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does Vault store LDAP user passwords?

    Vault binds to the directory as the user and does not keep the password.
  2. 2. A user belongs to two LDAP groups that are both mapped in Vault. What policies do they get?

    Policies from all matching groups are combined.
  3. 3. You change a userpass user's policies. What happens to their existing token?

    Policies are attached to a token at creation time.
  4. 4. Why use ldaps:// or StartTLS?

    Unencrypted LDAP exposes passwords on the wire.

Summary

  • Userpass keeps users inside Vault; fine for labs and tiny teams, with no MFA or directory link.
  • LDAP verifies credentials against a directory and maps groups to policies using a read-only bind account.
  • A user's final policies are the union of mapped group policies plus default.
  • Existing tokens do not change when policies change; plan revocation.
  • Use TLS to the directory and keep a break-glass path.

Next: AppRole Authentication