Auth methods

Auth methods are pluggable backends mounted under auth/<name>/. Their job is to take some external credential (a username/password, a JWT, an AWS sigv4-signed request, a Kubernetes service-account token, …) and return a Vault token. Sources: builtin/credential/ for built-ins, vault-plugin-auth-* repositories for the rest.

Purpose

Convert non-Vault credentials into Vault tokens with a set of attached policies. Each method advertises a login path; clients POST credentials there and get back an auth block which the token store consumes (see Token store).

Built-in auth methods

Mount type	Source	Highlights
approle	builtin/credential/approle/	Role-id + secret-id; the canonical app-to-Vault flow.
aws	builtin/credential/aws/	EC2 metadata signing or IAM role.
cert	builtin/credential/cert/	TLS client certificate auth.
github	builtin/credential/github/	GitHub personal access tokens.
ldap	builtin/credential/ldap/	LDAP/Active Directory bind + search.
okta	builtin/credential/okta/	Okta TOTP and password.
radius	builtin/credential/radius/	RADIUS auth.
token	builtin/credential/token/	Token "auth method" — proves you have a Vault token.
userpass	builtin/credential/userpass/	Username/password stored in Vault.

The minimal set wired in command/commands.go is approle, cert, jwt, oidc, userpass. The full set in helper/builtinplugins/registry_full.go adds Azure, GCP, AliCloud, CF, Kerberos, Kubernetes, OCI, plus the deprecated pcf alias and the removedFactory app-id entry.

External auth plugins

Anything not in builtin/credential/ lives in its own vault-plugin-auth-* repo and is imported in helper/builtinplugins/registry_full.go:

vault-plugin-auth-alicloud, vault-plugin-auth-azure, vault-plugin-auth-cf, vault-plugin-auth-gcp, vault-plugin-auth-jwt (also serves OIDC), vault-plugin-auth-kerberos, vault-plugin-auth-kubernetes, vault-plugin-auth-oci, plus hashicorp/vault-hcp-lib for HCP integration.

How it works

sequenceDiagram
    participant C as Client
    participant H as http/handler.go
    participant Core as vault.Core
    participant R as Router
    participant AM as Auth method
    participant TS as Token store
    C->>H: POST /v1/auth/<mount>/login + creds
    H->>Core: HandleRequest
    Core->>R: route by "auth/<mount>"
    R->>AM: backend.HandleRequest(login)
    AM-->>Core: *logical.Auth (policies, ttl, identity)
    Core->>TS: Mint token from Auth
    TS-->>Core: token + accessor
    Core-->>H: response with token
    H-->>C: JSON body

The *logical.Auth returned by an auth method describes:

• Policies, TokenPolicies, IdentityPolicies
• Accessor, EntityID
• LeaseOptions (TTL, MaxTTL, Renewable, Period)
• Alias (for identity-store deduplication)
• MFARequirement (if login MFA is configured)
• Metadata (custom audit fields)

Login MFA hook

If the request matches an MFA-enforced auth method or path, Core.HandleRequest does not hand back the token directly — it returns a mfa_request_id that the client must POST to sys/mfa/validate along with proof factors. See Login MFA and vault/login_mfa.go (3,122 lines).

Identity store integration

When an auth method returns an Alias, Vault looks up an identity entity that owns that alias (or creates one). The token's effective policies are the union of:

• The auth method's Policies and TokenPolicies
• The entity's policies (per-namespace)
• The entity's groups' policies (transitively)
• The token's IdentityPolicies

vault/identity_store_aliases.go handles alias-to-entity matching.

User lockout

Mount tunables user_lockout_threshold, user_lockout_duration, and user_lockout_counter_reset_duration apply to auth methods that opt in (userpass, ldap, approle, userpass-like). Implementation: vault/logical_system_user_lockout.go.

Integration points

• Mount lifecycle: see Router and mounts.
• Tokens: see Token store.
• Identity: see Identity store.
• MFA: see Login MFA.
• Plugins: see Plugin catalog.

Entry points for modification

• Add a built-in: create builtin/credential/<name>/, register a Factory in helper/builtinplugins/registry.go (or registry_full.go), wire into command/commands.go's loginHandlers if it has a CLI.
• Add an external plugin: ship as a separate binary, add to helper/builtinplugins/registry_full.go.
• Add a CLI helper for vault login <method>: implement cli.LoginHandler in your backend and register in command/commands.go's loginHandlers.
• Tweak login MFA enforcement: extend vault/login_mfa.go.