Authentication Methods · Topic 3 of 3

Authenticating and Configuring Auth Methods

Vault Associate (003): enable, list, tune and disable auth methods, then log in with userpass, AppRole and tokens using the CLI, the HTTP API and the UI.

  • 4 min
In a nutshell
  • Enable with vault auth enable, or POST /sys/auth/:path with a type.
  • The mount path defaults to the method type and can be changed with -path.
  • Log in with vault login -method=TYPE; add -path if the mount path differs.

What it is

Configuring an auth method means an operator enables it at a path and sets up who may log in. Authenticating means a client sends credentials to the method's login endpoint and receives a token.

You can do both through the CLI, the HTTP API or the UI. They all call the same API underneath.

Operatorvault auth enableMounted methodconfigureUsers or rolesClientloginMounted methodreturnsclient token

How it works

Configure with the CLI

vault auth enable userpass
vault auth enable -path=my-auth userpass
vault auth list
vault auth help userpass
vault auth disable my-auth

-path sets the mount path, which must be unique and defaults to the method type. The method is then served at auth/<path>. Other flags include -description, -default-lease-ttl and -max-lease-ttl.

vault auth tune changes settings of an existing mount. The built-in token method cannot be disabled.

After enabling, you configure the method by writing to its path:

vault write auth/userpass/users/alice password=change-me token_policies=app-read

Configure with the API

ActionRequest
List methodsGET /sys/auth
Enable a methodPOST /sys/auth/:path with {"type": "userpass"}
Tune a methodPOST /sys/auth/:path/tune
Disable a methodDELETE /sys/auth/:path
Create a userPOST /auth/userpass/users/:username

Enabling, tuning and disabling need the sudo capability on those sys/auth paths. Over HTTP the address starts with /v1, for example /v1/sys/auth/my-auth.

Configure with the UI

Open the Access area, choose Enable new method, pick the method, keep or change the path, and select Enable Method. The UI also has a CLI shell, where you can run the same vault write commands.

Authenticate with the CLI

vault login -method=userpass username=alice
vault login -method=github -path=github-prod
vault write auth/approle/login role_id=ROLE_ID secret_id=SECRET_ID

-method is the method type and -path is where it is mounted. The token is saved by the token helper so later commands use it automatically. -no-store skips saving it, and -token-only prints only the token.

Passing a token on the command line, as in vault login TOKEN, may leave it in shell history. The VAULT_TOKEN environment variable takes precedence over other tokens.

Authenticate with the API

curl --request POST --data '{"password": "change-me"}' \
  http://127.0.0.1:8200/v1/auth/userpass/login/alice

The reply holds the token at auth.client_token, along with auth.policies, auth.lease_duration and auth.renewable. API clients must attach the token to later requests themselves, in the X-Vault-Token header or as an Authorization: Bearer header.

AppRole logs in at POST /auth/approle/login with role_id and secret_id.

Authenticate with the UI

You sign in from the UI sign-in page with the token method or another enabled method. Results are the same: the UI uses the token you receive.

AppRole setup in order

Adminenable approlewritesPolicy and rolereadsrole idAdmingeneratessecret iddeliveredAppApplogin with bothToken
vault auth enable approle
vault write auth/approle/role/jenkins token_policies=jenkins token_type=batch
vault read auth/approle/role/jenkins/role-id
vault write -force auth/approle/role/jenkins/secret-id

How the exam asks about this

  • "Which command enables an auth method at a custom path?" vault auth enable -path=NAME TYPE.
  • "A script must log in over HTTP without the CLI." POST to the method's login endpoint and read auth.client_token.
  • "Which command lists enabled auth methods?" vault auth list.

What to remember for the exam

  • Enable with vault auth enable, or POST /sys/auth/:path with a type.
  • The mount path defaults to the method type and can be changed with -path.
  • Log in with vault login -method=TYPE; add -path if the mount path differs.
  • The CLI stores the token; API users must send it in the X-Vault-Token header.
  • The login response returns the token at auth.client_token.
  • AppRole needs a role ID and, by default, a secret ID.
Watch out

If VAULT_TOKEN is set, it takes precedence over a token saved by vault login. A new login can appear to have no effect until you unset it.

Common mistakes

Mixing up method and path. -method takes the type, such as userpass. If you mounted it elsewhere, add -path, or the login goes to the default mount.

Forgetting the token on API calls. The CLI attaches the token for you. With curl you must add the header yourself.

Expecting enabling to create users. Enabling only mounts the method. You still create users or roles by writing to its path.

Check yourself

  • Which API call enables an auth method at my-auth?

    POST /sys/auth/my-auth with a body such as {"type": "userpass"}, which needs the sudo capability.

  • Where does the API return the new token after a userpass login?

    In auth.client_token of the JSON response.

  • What does vault login -method=github -path=github-prod do?

    It logs in with the GitHub method mounted at github-prod/ rather than at the default github/ path.

Topic 3 of 3 in Authentication Methods

Test yourself on Authentication Methods

The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.