auth

The auth command groups subcommands for interacting with Vault's auth methods. Users can list, enable, disable, and get help for different auth methods.

For more information, please see the auth method documentation or the authentication concepts page.

To authenticate to Vault as a user or machine, use the vault login command instead. This command is for interacting with the auth methods themselves, not authenticating to Vault.

Examples

Enable an auth method:

$ vault auth enable userpass
Success! Enabled userpass auth method at: userpass/

List all auth methods:

$ vault auth list
Path         Type        Description
----         ----        -----------
token/       token       token based credentials
userpass/    userpass    n/a

Get help about how to authenticate to a particular auth method:

$ vault auth help userpass/
Usage: vault login -method=userpass [CONFIG K=V...]
# ...

Disable an auth method:

$ vault auth disable userpass/
Success! Disabled the auth method (if it existed) at: userpass/

Tune an auth method:

$ vault auth tune -max-lease-ttl=30m userpass/
Success! Tuned the auth method at: userpass/

Usage

Usage: vault auth <subcommand> [options] [args]

  # ...

Subcommands:
    disable    Disables an auth method
    enable     Enables a new auth method
    help       Prints usage for an auth method
    list       Lists enabled auth methods
    tune       Tunes an auth method configuration

For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.

auth disable

The auth disable command disables an auth method at a given path, if one exists. This command is idempotent, meaning it succeeds even if no auth method is enabled at the path.

Once an auth method is disabled, it can no longer be used for authentication. All access tokens generated via the disabled auth method are immediately revoked. This command will block until all tokens are revoked.

Examples

Disable the auth method enabled at "userpass/":

$ vault auth disable userpass/
Success! Disabled the auth method (if it existed) at: userpass/

Usage

There are no flags beyond the standard set of flags included on all commands.

auth enable

The auth enable command enables an auth method at a given path. If an auth method already exists at the given path, an error is returned. After the auth method is enabled, it usually needs configuration. The configuration varies by auth method.

An auth method is responsible for authenticating users or machines and assigning them policies and a token with which they can access Vault. Authentication is usually mapped to policy. Please see the policies concepts page for more information.

Examples

Enable the auth method "userpass" enabled at "userpass/":

$ vault auth enable userpass
Success! Enabled the userpass auth method at: userpass/

Create a user:

$ vault write auth/userpass/users/sethvargo password=secret
Success! Data written to: auth/userpass/users/sethvargo

For more information on the specific configuration options and paths, please see the auth method documentation.

Usage

The following flags are available in addition to the standard set of flags included on all commands.

• -audit-non-hmac-request-keys (string: "") - Key that will not be HMAC'd by audit devices in the request data object. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key. An example of this is provided in the tune section.

• -audit-non-hmac-response-keys (string: "") - Key that will not be HMAC'd by audit devices in the response data object. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key.

• -default-lease-ttl (duration: "") - The default lease TTL for this auth method. If unspecified, this defaults to the Vault server's globally configured default lease TTL, or a previously configured value for the auth method. Uses duration format strings.

• -passthrough-request-headers (string: "") - request header values that will be sent to the auth method. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key.

• -allowed-response-headers (string: "") - response header values that the auth method will be allowed to set. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key.

• -description (string: "") - Human-friendly description for the purpose of this auth method.

• -listing-visibility (string: "") - The flag to toggle whether to show the mount in the UI-specific listing endpoint. Valid values are "unauth" or "hidden", with the default "" being equivalent to "hidden".

• -local (bool: false) - Mark the auth method as local-only. Local auth methods are not replicated nor removed by replication.

• -max-lease-ttl (string: "") - The maximum lease duration, specified as a string duration like "5s" or "30m".

• -path (string: "") - Place where the auth method will be accessible. This must be unique across all auth methods. This defaults to the "type" of the auth method. The auth method will be accessible at /auth/<path>.

• -seal-wrap (bool: false) - Enable seal wrapping for the mount, causing values stored by the mount to be wrapped by the seal's encryption capability.

• -token-type (string: "") - Specifies the type of tokens that should be returned by the auth method.

• -plugin-version (string: "") - Configures the semantic version of the plugin to use. If unspecified, implies the built-in or any matching unversioned plugin that may have been registered.

auth help

The auth help command prints usage and help for an auth method.

• If given a TYPE, this command prints the default help for the auth method of that type.

• If given a PATH, this command prints the help output for the auth method enabled at that path. This path must already exist.

Each auth method produces its own help output.

Examples

Get usage instructions for the userpass auth method:

$ vault auth help userpass
Usage: vault login -method=userpass [CONFIG K=V...]

  The userpass auth method allows users to authenticate using Vault's
  internal user database.

# ...

Print usage for the auth method enabled at my-method/

$ vault auth help my-method/
# ...

Usage

There are no flags beyond the standard set of flags included on all commands.

auth list

The auth list command lists the auth methods enabled. The output lists the enabled auth methods and options for those methods.

Deprecation status column

All built-in auth engines will have an associated Deprecation Status. This status will be reflected in the Deprecation Status column, seen below. All auth engines which are not provided by built-in plugins will show a Deprecation Status of "n/a".

Version columns

The -detailed view displays some version information for each mount.

The Version field indicates the configured version for the plugin. Empty, or "n/a", indicates the built-in or any matching unversioned plugin that may have been registered.

Running Version indicates the actual plugin version running, which may differ from Version if the plugin hasn't been reloaded since the configured version was updated using the secrets tune command. Finally, the Running SHA256 field indicates the SHA256 sum of the running plugin's binary. This may be different from the SHA256 registered in the catalog if the plugin hasn't been reloaded since the plugin version was overwritten in the catalog.

Examples

List all auth methods:

$ vault auth list
Path         Type        Description
----         ----        -----------
token/       token       token based credentials
userpass/    userpass    n/a

List detailed auth method information:

$ vault auth list -detailed
Path        Plugin     Accessor                 Default TTL    Max TTL    Token Type         Replication    Seal Wrap    External Entropy Access    Options    Description                UUID                                    Deprecation Status
----        ------     --------                 -----------    -------    ----------         -----------    ---------    -----------------------    -------    -----------                ----                                    ------------------
app-id/     app-id     auth_app-id_c88ad56f     system         system     default-service    replicated     false        false                      map[]      n/a                        a7c702b4-0dba-02b6-483c-2fd6be33240a    pending removal
approle/    approle    auth_approle_95df932e    system         system     default-service    replicated     false        false                      map[]      n/a                        931df9d1-8737-b7dc-4ca2-3e0e892fce92    supported
token/      token      auth_token_aafab997      system         system     default-service    replicated     false        false                      map[]      token based credentials    6eb5db7b-ac7f-4304-1f52-9b802c6f06c1    n/a

Usage

The following flags are available in addition to the standard set of flags included on all commands.

Output options

• -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

• -detailed (bool: false) - Print detailed information such as configuration and replication status about each auth method.

auth move

The auth move command moves an existing auth method to a new path. Any leases from the old auth method are revoked, but all configuration associated with the engine is preserved. The command can be issued for a move within or across namespaces, using namespace prefixes in the arguments.

The command will trigger a remount operation and uses the returned migration ID to poll the status of the operation until a terminal state of success or failure is reached.

Moving an existing auth method will revoke any leases from the old method.

Examples

Move the existing auth method at ns1/approle/ to ns2/new-approle/:

$ vault auth move ns1/auth/approle/ ns2/auth/new-approle/

Usage

There are no flags beyond the standard set of flags included on all commands.

auth tune

The auth tune command tunes the configuration options for the auth method at the given PATH.

Note

The argument corresponds to the path where the auth method is enabled, not the auth type.

Examples

Before tuning the auth method configuration, view the current configuration of the auth method enabled at github/.

$ vault read sys/auth/github/tune
Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service

The default lease for the auth method enabled at github/ is currently set to 768 hours. Tune this value to 72 hours.

$ vault auth tune -default-lease-ttl=72h github/
Success! Tuned the auth method at: github/

Verify the updated configuration.

$ vault read sys/auth/github/tune
Key                  Value
---                  -----
default_lease_ttl    72h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service

To restore back to the system default, you can use -1.

$ vault auth tune -default-lease-ttl=-1 github/
Success! Tuned the auth method at: github/

Verify the updated configuration.

$ vault read sys/auth/github/tune
Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service

You can specify multiple audit non-hmac request keys.

$ vault auth tune -audit-non-hmac-request-keys=value1 -audit-non-hmac-request-keys=value2 github/
Success! Tuned the auth method at: github/

Enable user lockout

User lockout feature is only supported for userpass, ldap, and approle auth methods.

Tune the userpass/ auth method to lock out the user after 10 failed login attempts within 10 minutes.

$ vault auth tune -user-lockout-threshold=10  -user-lockout-duration=10m userpass/
Success! Tuned the auth method at: userpass/

View the current configuration of the auth method enabled at userpass/.

$ vault read sys/auth/userpass/tune

Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service
user_lockout_counter_reset_duration    0s
user_lockout_disable                   false
user_lockout_duration                  10m
user_lockout_threshold                 10

Usage

The following flags are available in addition to the standard set of flags included on all commands.

• -allowed-response-headers (string: "") - response header values that the auth method will be allowed to set.

• -audit-non-hmac-request-keys (string: "") - Key that will not be HMAC'd by audit devices in the request data object. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key.

• -audit-non-hmac-response-keys (string: "") - Key that will not be HMAC'd by audit devices in the response data object. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key.

• -default-lease-ttl (duration: "") - The default lease TTL for this auth method. If unspecified, this defaults to the Vault server's globally configured default lease TTL, or a previously configured value for the auth method.

• -description (string: "") - Specifies the description of the auth method. This overrides the current stored value, if any.

• -listing-visibility (string: "") - The flag to toggle whether to show the mount in the UI-specific listing endpoint. Valid values are "unauth" or "hidden". Passing empty string leaves the current setting unchanged.

• -max-lease-ttl (duration: "") - The maximum lease TTL for this auth method. If unspecified, this defaults to the Vault server's globally configured maximum lease TTL, or a previously configured value for the auth method. This value is allowed to override the server's global max TTL; it can be longer or shorter.

• -passthrough-request-headers (string: "") - request header values that will be sent to the auth method. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key.

• -token-type (string: "") - Specifies the type of tokens that should be returned by the auth method.

• -plugin-version (string: "") - Configures the semantic version of the plugin to use. The new version will not start running until the mount is reloaded.

• -user-lockout-threshold (string: "") - Specifies the number of failed login attempts after which the user is locked out. User lockout feature was added in Vault 1.13.

• -user-lockout-duration (duration: "") - Specifies the duration for which a user will be locked out. User lockout feature was added in Vault 1.13.

• -user-lockout-counter-reset-duration (duration: "") - Specifies the duration after which the lockout counter is reset with no failed login attempts. User lockout feature was added in Vault 1.13.

• -user-lockout-disable (bool: false) - Disables the user lockout feature if set to true. User lockout feature was added in Vault 1.13.