> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/cli/authentication-and-authorization/vhsm-auth.md). # vhsm auth The `auth` command in vHSM provides a set of subcommands for managing authentication methods. Users can enable, disable, list, and tune authentication methods. {% hint style="info" %} **Note**: This command is for managing authentication methods, not for authenticating users or machines. To authenticate, use the `vhsm login` command instead. {% endhint %} For further details, refer to the authentication concepts and auth method documentation. ### Usage ``` vhsm auth [options] [args] ``` #### Available Subcommands | Subcommand | Description | | -------------------------------- | --------------------------------------- | | [`enable`](#vault-auth-enable) | Enables a new auth method | | [`disable`](#vault-auth-disable) | Disables an auth method | | [`list`](#vault-auth-list) | Lists enabled auth methods | | [`tune`](#vault-auth-tune) | Tunes an auth method configuration | | [`help`](#vhsm-auth-help) | Prints usage details for an auth method | *** ### `vhsm auth enable` The `enable` subcommand enables an authentication method at a specified path. If the auth method already exists at the path, an error is returned. Configuration of the auth method is required post-enablement. #### Usage ``` vhsm auth enable ``` #### Example Enable the `userpass` authentication method: ``` vhsm auth enable -description="This is a user password method" userpass ``` **Output** ``` Success! Enabled userpass auth method at: userpass/ ``` #### Options | Flag | Type | Description | | -------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `-allowed-response-headers` | `string` | Response header values that the auth method will be allowed to set. Multiple keys may be specified by providing this option multiple times. | | `-audit-non-hmac-request-keys` | `string` | Key that will not be HMAC'd by audit devices in the request data object. Multiple keys may be specified. | | `-audit-non-hmac-response-keys` | `string` | Key that will not be HMAC'd by audit devices in the response data object. Multiple keys may be specified. | | `-default-lease-ttl` | `duration` | The default lease TTL for this auth method. Defaults to the vHSM server's global default lease TTL if unspecified. | | `-description` | `string` | Specifies the description of the auth method. Overrides the current stored value, if any. | | `-listing-visibility` | `string` | Toggles whether to show the mount in the UI listing. Valid values: `"unauth"` or `"hidden"`. An empty string keeps the current setting unchanged. | | `-max-lease-ttl` | `duration` | The maximum lease TTL for this auth method. Defaults to the global maximum lease TTL unless specified. Can override the server’s global max TTL. | | `-passthrough-request-headers` | `string` | Request header values that will be sent to the auth method. Multiple keys may be specified. | | `-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 takes effect only after the mount is reloaded. | | `-user-lockout-threshold` | `string` | Number of failed login attempts after which the user is locked out. | | `-user-lockout-duration` | `duration` | Duration for which a user will be locked out. | | `-user-lockout-counter-reset-duration` | `duration` | Duration after which the lockout counter is reset if there are no failed login attempts. | | `-user-lockout-disable` | `bool` | If set to `true`, disables the user lockout feature. | ### `vhsm auth disable` The `disable` subcommand removes an authentication method at a specified path. All access tokens associated with the disabled method are immediately revoked. #### Usage ``` vhsm auth disable ``` #### Example Disable the `userpass` authentication method: ``` vhsm auth disable userpass ``` **Output** ``` Success! Disabled the auth method (if it existed) at: userpass/ ``` *** ### `vhsm auth list` The `list` subcommand displays all enabled authentication methods. #### Usage ``` vhsm auth list [options] ``` #### Example List enabled authentication methods: ``` vhsm auth list ``` **Output** ``` Path Type Accessor Description Version ---- ---- -------- ----------- ------- token/ token auth_token_57118dd8 token based credentials n/a userpass/ userpass auth_userpass_a07fb2b4 This is a user password method n/a ``` List detailed information: ``` vhsm auth list -detailed ``` #### Options | Flag | Description | | ------------------ | ------------------------------------------ | | `-format=` | Output format: `table`, `json`, or `yaml`. | | `-detailed` | Displays additional configuration details. | *** ### `vhsm auth tune` The `tune` subcommand adjusts the configuration of an authentication method at a given path. #### Usage ``` vhsm auth tune [options] ``` #### Example Set the default lease TTL to 30 minutes for `userpass`: ``` vhsm auth tune -max-lease-ttl=30m userpass ``` **Output** ``` Success! Tuned the auth method at: userpass/ ``` #### Options | Flag | Type | Description | | ------------------------------ | ---------- | ------------------------------------------------------------------ | | `-default-lease-ttl` | `duration` | Sets the default lease TTL. | | `-max-lease-ttl` | `duration` | Defines the maximum lease duration. | | `-audit-non-hmac-request-keys` | `key` | Excludes specified request keys from HMAC auditing. | | `-token-type` | `string` | Defines the type of tokens issued. | | `-user-lockout-threshold` | `int` | Specifies the number of failed login attempts before user lockout. | | `-user-lockout-duration` | `duration` | Defines how long a user remains locked out. | *** ### `vhsm auth help` The `help` subcommand provides usage details for a specified authentication method. #### Usage ``` vhsm auth help ``` #### Example Get help for the `userpass` authentication method: ``` vhsm auth help userpass ``` **Output** ``` Usage: vhsm login -method=userpass [CONFIG K=V...] The userpass auth method allows users to authenticate using vHSM's internal user database. Authenticate as "sally": $ vhsm login -method=userpass username=sally Password (will be hidden): Authenticate as "bob": $ vhsm login -method=userpass username=bob password=password Configuration: password= Password to use for authentication. If not provided, the CLI will prompt for this on stdin. username= Username to use for authentication. ``` ***