Learn Vault - Authentication Methods (Token, Userpass, AppRole, OIDC)

#Introduction

After building Vault's security fence through policies in episode 9 — rules about who can do what — this episode covers the other side of that coin: how you prove who you are. Policies govern authorization, but before authorization there is always authentication.

The important question: in the real working world, Vault is accessed by two very different types of users. On one side are humans — engineers who need to read secrets from their laptops, and already have company SSO accounts. On the other side are machines — applications, servers, and CI/CD pipelines that must fetch credentials automatically without a human typing a password. Designing the right authentication for both groups is one of the most important architecture decisions in Vault, and getting it wrong here means a big security hole.

In this episode we'll dissect Authentication Methods: their general concept, the token types they produce, auth methods for humans (userpass, OIDC/SSO), and auth methods for machines (AppRole). Let's begin.

#Main Discussion

#The Auth Method Concept: The Gateway to Tokens

An auth method is a mechanism that verifies the credentials a client provides, then issues an access token as proof of identity. Think of it this way: Vault is a locked building. At each entrance there's a guard (auth method) with a different way to verify you — some ask for an ID card (userpass), some scan your face (OIDC SSO), some accept machine access cards (AppRole). Once you pass, you're given a lanyard (token) that determines how far you can move inside the building (policy).

The full flow:

1. The client sends credentials to the auth method endpoint (e.g. POST /v1/auth/userpass/login/:username).
2. The auth method verifies the credentials against its identity source (local file, LDAP, OIDC IdP, etc.).
3. Vault issues a token with the policy determined by those credentials.
4. The client uses this token for all subsequent requests (the X-Vault-Token header).

Auth methods are pluggable and can be enabled as many times as needed at different paths:

vault auth enable userpass
vault auth enable -path=ldap-auth ldap
vault auth list

Path         Type        Accessor                  Description                Version
----         ----        --------                  -----------                -------
ldap-auth/   ldap        auth_ldap_1a2b3c          n/a                        n/a
token/       token       auth_token_4d5e6f         token based credentials    n/a
userpass/    userpass    auth_userpass_7g8h9i      n/a                        n/a

Note that token/ (the token auth method) is always active and can't be disabled — it's the "raw" way to enter Vault: you carry an already-issued token. All other auth methods ultimately also produce tokens, so understand this: the token is Vault's universal currency, and auth methods are just currency exchange machines.

#The Token Auth Method and Four Token Types

A token is the core artifact that represents an identity (from an auth method), carries policies, and has a lifetime (TTL). There are four token types you must know:

Service Token is the most common default type. It's stored in Vault (has a token accessor for reference without exposing the real token), can be renewed, revoked, and monitored. Suitable for almost all cases.

Batch Token is issued when you need high throughput with minimum overhead. It isn't stored in Vault at all — all its information is encoded into the token itself — so it can't be renewed and can't be revoked individually (only through policies or TTL expiry). The consequence: it's good for short-lived secrets and very high request volumes, but don't use it for anything needing full lifecycle control.

vault token create -policy=app-backend -type=batch -ttl=30m

Periodic Token is very useful for daemons or Vault Agents running forever. Its TTL is automatically extended each time it's used, with no maximum limit. However, because it never expires, it's a big responsibility: you must ensure the token is kept safe and revoked when no longer needed.

Orphan Token breaks the parental chain. Normally, a child token (along with all its descendants) disappears if the parent token is revoked. An orphan token doesn't inherit this "genealogy," so it stays alive even if its parent is revoked. This is ideal when you want a token fully isolated from the token that issued it.

#Userpass: Auth Method for Humans (Simple)

userpass is the simplest auth method for human users: Vault stores the username and a password hash. Good for labs, staging, or small teams without SSO yet.

1. Enable and create a user

vault auth enable userpass

vault write auth/userpass/users/deva \
    password="S3cur3Pa55word!" \
    policies="dev-kv"

2. Log in as the user

vault login -method=userpass username=deva password=S3cur3Pa55word!

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
 
Key                  Value
---                  -----
token                hvs.CAESIKn...
token_accessor       8X9vR2w4...
token_duration       768h
token_renewable      true
token_policies       ["default" "dev-kv"]
identity_policies    []
policies             ["default" "dev-kv"]

Notice the output: this token has token_policies: ["default" "dev-kv"] — the policy we assigned when creating the user. All of this token's operations are governed by those policies, as we learned in episode 9.

#OIDC / SSO: Enterprise-Scale Human Authentication

For real organizations, human authentication should be pointed at an existing identity provider (IdP) like Okta, Azure AD, GitHub, or Google. Vault has the oidc auth method (OpenID Connect) that redirects the user's browser to the IdP, receives a callback after a successful login, and issues a Vault token.

The key concept: Vault never sees the user's password. It only receives an identity token signed by the IdP, verifies the signature, then maps claims from that token to Vault policies.

Here's the outline:

vault auth enable oidc

# Minimal OIDC config example via CLI
vault write auth/oidc/config \
    oidc_discovery_url="https://login.microsoftonline.com/<tenant>/v2.0" \
    oidc_client_id="<client-id>" \
    oidc_client_secret="<client-secret>" \
    default_role="engineer"
 
# Map IdP claims to Vault policies
vault write auth/oidc/role/engineer \
    bound_audiences="<client-id>" \
    allowed_redirect_uris="http://localhost:8250/oidc/callback" \
    user_claim="sub" \
    groups_claim="groups" \
    policies="dev-kv"

vault login -method=oidc role=engineer

When the command above runs, Vault opens a browser, you log in to the company IdP, and after success you receive a Vault token. The biggest advantage: account revocation and lifecycle are managed by the IdP — when an employee leaves the company, their Vault access automatically dies when the SSO account is deactivated. No orphaned userpass accounts left wandering around.

#AppRole: Machine-to-Machine Authentication

Now we enter the DevOps favorite: how applications authenticate themselves without human interaction. The answer is AppRole — a combination of two credentials:

• RoleID — a sort of "username" for the machine; static and can be stored in config.
• SecretID — a sort of "password"; secret, generated on-demand, and usually delivered securely (we'll cover the secure delivery in episode 13 on response wrapping).

The RoleID + SecretID combination produces a Vault token. It's equivalent to a machine showing an access card + PIN.

1. Enable AppRole and create a role

vault auth enable approle

vault write auth/approle/role/app-backend \
    token_ttl=1h \
    token_max_ttl=24h \
    secret_id_ttl=48h \
    token_policies="app-backend"

The important options above:

2. Fetch the RoleID and generate a SecretID

vault read auth/approle/role/app-backend/role-id

vault write -f auth/approle/role/app-backend/secret-id

Key                   Value
---                   -----
secret_id             f7f9b3b6-...
secret_id_accessor    3a4d5c6e-...
secret_id_ttl         48h
secret_id_num_uses     0

3. Log in with the combination of both

vault write auth/approle/login \
    role_id="<role-id>" \
    secret_id="<secret-id>"

Key                     Value
---                     -----
token                   hvs.CAESILf...
token_accessor          Z6Xb...
token_duration          1h
token_renewable         true
token_policies          ["app-backend" "default"]
identity_policies       []
policies                ["app-backend" "default"]
token_meta_role_name    app-backend

Notice token_duration: 1h — this token follows the token_ttl we set. For long-running applications, the token renewal mechanism (which we'll cover in detail in episode 12) is the application's or Vault Agent's responsibility.

#Auth Method Comparison at a Glance

#Common Authentication Mistakes

#Conclusion

In this episode we've dissected Authentication Methods: the concept that an auth method is a machine that issues tokens, the four token types (service, batch, periodic, orphan) and when to use them, human authentication via userpass and OIDC/SSO, and machine-to-machine authentication via AppRole with RoleID and SecretID. We also reaffirmed the prohibition on using the root token in production and the importance of separating auth mechanisms for humans vs machines.

The essence of this episode: authentication only determines who, while what's allowed is still determined by policies (episode 9). The two work together, and in episode 11 we'll see how Vault unifies them through the Identity Engine — when a user logging in via either userpass or OIDC turns out to be the same entity with unified policies.

In episode 11, we'll cover the Identity Engine (Entities, Aliases & Groups) — how Vault unifies identities from various auth methods and inherits policies through groups. Keep your enthusiasm up!