Hashicorp Vault is a secrets management tool. For setup, configuration, and management, the Vault CLI can be used. It offers more than 30 subcommands, and in this blog series, they are explored systematically.
This article focuses on Authentication. It covers the setup and management of authentication engines, and it shows how to perform logins for the engines.
The technical context of this article is hashicorp_vault_v1.21.1, released 2025-11-18. All provided information and command examples should be valid with newer versions too, baring an update of the CLI commands' syntax.
The background material for this article stems from the official Hashicorp Vault documentation about .
Vault CLI Overview
The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.
Groups marked with a checkmark were covered in an earlier article, and the section marked with an at sign is the focus for this article.
- ✅ Initialization
server: Starts a server process
agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
proxy: Starts a vault proxy process
- ✅ Configuration
operator: Cluster management operations, including memberships, encryption and unseal keys
plugin: Manage and install additional plugins
read/list: Access stored configuration and secrets
write/patch: Modify or create any data
delete: Delete configuration data or secrets
- ✅ Introspection
status: Show status information of the vault server
version: Shows compact version information and build timestamp
version-history: Shows detailed version information about all previously used vault server instances
print: Detailed view of the vault’s server runtime configuration
path-help: Detailed documentation about API endpoints
events: Subscribe to the event stream of a running vault instance
monitor: Print vault log messages
debug: Shows debug information of the connected Vault server
audit: Interact with connected audit devices
- ✅ Vault Enterprise
hcp: Operate a managed Hashicorp Vault cluster
namespace: Interact with configured namespaces of the cluster
- ✅ Authorization
policy: Manage policy definitions that govern all vault operations
tokens: General token management
lease: Manage current token leases, including renewal, revocation and TTL modification
- 🌀 Authentication
auth: Interact with configured authentication options
login: Authenticates access to a Vault server
- Secrets Management
secrets: General configuration of secret engines
kv: Access to the essential key-value store
transform: Interact with the transform secrets engine
transit: Interact with the Vaults transit secrets engine
unwrap: One-time access to arbitrary encrypted data
pki: Access the private key infrastructure secrets engine
ssh: Initiates SSH sessions via the SSH secrets engine
Authentication Commands
auth
A new vault instance supports exactly one, not disableable authentication method: token. Using either the initially defined root token, or other created tokens with the required policies, access to the Vault server can be given.
The vault auth command provides several subcommands with which the available authentication methods can be managed.
enable: Activate a new authentication method
move: Change the mount path of an auth method
tune: Modify the configuration of an auth method
list: Show all configured auth methods
help: Show supporting information about how to use an authentication method
disable: Deactivate an authentication method
As explored in more detail in my article
The other option is to access the plugin management and list authentication plugins.
> vault plugin list auth
Name Version
---- -------
alicloud v0.22.0+builtin
approle v1.21.1+builtin.vault
aws v1.21.1+builtin.vault
azure v0.22.0+builtin
cert v1.21.1+builtin.vault
cf v0.22.0+builtin
gcp v0.22.0+builtin
github v1.21.1+builtin.vault
jwt v0.25.0+builtin
kerberos v0.16.0+builtin
kubernetes v0.23.1+builtin
ldap v1.21.1+builtin.vault
oci v0.20.0+builtin
oidc v1.21.1+builtin.vault
okta v1.21.1+builtin.vault
pcf v1.21.1+builtin.vault
radius v1.21.1+builtin.vault
userpass v1.21.1+builtin.vault
The following two sections contrast examples for builtin and user authentication methods.
Managing Builtin Authentication Method: Userpass
A new authentication method can be enabled by just passing its name. Several options can be passed already at initialization time, including the TTL of leases and plugin-specific options, or technical options like access to Vault-external entropy sources.
> vault auth enable userpass
# Log messages
Success! Enabled userpass auth method at: userpass/
core: enabled credential backend: path=userpass/ type=userpass version="v1.21.1+builtin.vault"
The default mount path can be changed, with the immediate effect that all existing tokens will be invalidated immediately. Internally, the authentication methods endpoints configuration will be copied, then unmounted, and mounted at the new path - a background operation that can take some time.
> vault auth move auth/userpass auth/login
# Log messages
Started moving auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Waiting for terminal status in migration of auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Success! Finished moving auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Once the authentication method is mounted, its configuration can be changed with the tune command. All options available during initialization can be accessed and modified. The following command shows how to change the default lease time.
> vault auth tune -default-lease-ttl=1h login/
# Log messages
2025-12-11T20:07:33.703+0100 [INFO] core: mount tuning of leases successful: path=auth/login/
Success! Tuned the auth method at: login/
To get an overview to all defined authentication methods, run the following:
> vault auth list
# Log messages
Path Type Accessor Description Version
---- ---- -------- ----------- -------
login/ userpass auth_userpass_208f6abe n/a n/a
token/ token auth_token_a5a09180 token based credentials n/a
Each authentication methods can be used with the Vault CLI via vault login. A helpful shortcut to see when parameters an authentication method requires can be obtained as follows:
> vault auth help login/
# Log messages
Usage: vault login -method=userpass [CONFIG K=V...]
The userpass auth method allows users to authenticate using Vault's
internal user database.
Authenticate as "sally":
$ vault login -method=userpass username=sally
Password (will be hidden):
Authenticate as "bob":
$ vault login -method=userpass username=bob password=password
Configuration:
password=<string>
Password to use for authentication. If not provided, the CLI will prompt
for this on stdin.
username=<string>
Username to use for authentication.
Finally, a configured auth method can be disabled, immediately revoking all existing leases.
> vault auth disable login/
# Log messages
2025-12-11T20:14:25.462+0100 [INFO] core: disabled credential backend: path=auth/login/
Success! Disabled the auth method (if it existed) at: login/
Managing User Authentication Method: OIDC
The OIDC method is activated and mounted at a predefined path.
> vault auth oidc
# Log messages
2025-12-13T11:20:44.946+0100 [INFO] core: enabled credential backend: path=oidc/ type=oidc version="v1.21.1+builtin.vault"
Success! Enabled oidc auth method at: oidc/
However, it should be available at the path /openid-login. Let’s move it there.
> vault auth move auth/oidc auth/openid-login
# Log messages
2025-12-13T11:21:23.440+0100 [INFO] core.mounts.migration: Starting to update the mount table and revoke leases: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
Started moving auth method auth/oidc/ to auth/openid-login/, with migration ID 64a573e0-b9f5-1a92-bf63-68578a90ee13
Waiting for terminal status in migration of auth method auth/oidc/ to auth/openid-login/, with migration ID 64a573e0-b9f5-1a92-bf63-68578a90ee13
2025-12-13T11:21:23.734+0100 [INFO] core.mounts.migration: Removing the source mount from filtered paths on secondaries: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
2025-12-13T11:21:23.734+0100 [INFO] core.mounts.migration: Updating quotas associated with the source mount: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
2025-12-13T11:21:23.735+0100 [INFO] core.mounts.migration: Completed mount move operations: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
The OIDC authentication can be used in conjunction with an external system. To see tunable properties, run the following command:
> vault read sys/auth/openid-login/tune
# Log messages
Key Value
--- -----
default_lease_ttl 768h
description n/a
force_no_cache false
max_lease_ttl 768h
token_type default-service
Let’s limit the TTL, and ensure unauthenticated users can access the method as well.
> vault auth tune -max-lease-ttl=1m -listing-visibility=unauth openid-login
2025-12-13T11:37:08.199+0100 [INFO] core: mount tuning of leases successful: path=auth/openid-login/
2025-12-13T11:37:08.456+0100 [INFO] core: mount tuning of listing_visibility successful: path=auth/openid-login/
Success! Tuned the auth method at: openid-login/
To see how to perform a login with this method, run the following command:
> vault auth help openid-login/
# Log messages
Usage: vault login -method=oidc [CONFIG K=V...]
The OIDC auth method allows users to authenticate using an OIDC provider.
The provider must be configured as part of a role by the operator.
Authenticate using role "engineering":
$ vault login -method=oidc role=engineering
Complete the login via your OIDC provider. Launching browser to:
https://accounts.google.com/o/oauth2/v2/...
The default browser will be opened for the user to complete the login. Alternatively,
the user may visit the provided URL directly.
Finally, the authentication method will be disabled again.
> vault auth disable openid-login
# Log messages
2025-12-13T11:44:33.916+0100 [INFO] core: disabled credential backend: path=auth/openid-login/
Success! Disabled the auth method (if it existed) at: openid-login/
login
To login to a configured authentication method, both the GUI and the CLI can be used. An invocation via the CLI requires the following command flags to be present:
method: The authentication method type
path: In case of a non-default mount path, it needs to be configured specifically.- parameters: Additional parameters as required by the authentication method
Continuing with the examples from the last two sections, to perform the login for the userpass method, run the following commands:
> vault login -method=userpass -path=login username=user
# Log messages
Password (will be hidden):
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.CAESICzlbzAXoGcIvdAgGQ1NToqs5jARRfP4oFJAS_37Mw-HGh4KHGh2cy5ORGMzYmYyQWlGbFk5em92cHVuNXFBbkU
token_accessor EjZQYdMEMCAsN7VvVCR1ef1r
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_username user
To properly setup the OIDC authentication method, additional steps are required: Registration with an OIDC provider, configuring the discovery URL and secrets in vaults, and the setup of policies and roles. Assuming these steps were done, the login works as follows:
> vault login -method=oidc -path=openid-login role=user
#logMessages
Complete the login via your OIDC provider. Launching browser to:
...
Waiting for OIDC authentication to complete...
Conclusion
The Hashicorp Vault CLI offers more then 30 commands. In this article, you learned all about authentication. First, authentication methods are enabled at a specific mountpoints. Their properties can be modified, their mount path changed, and a list of all active methods obtained. Not required authentication methods can be disabled, immediately revoking all token leases. Second, users and systems alike can use the CLI also to login. Providing the authentication methods name, its mount path, and other required parameters. When successful, a new token is created, access policies attached, and the token owner can interact with the Vault server.
SOCIAL SHARE CARD GENERATOR