/sys/auth

The /sys/auth endpoint is used to list, create, update, and delete auth methods. Auth methods convert user or machine-supplied information into a token which can be used for all future requests.

List auth methods

This endpoint lists all enabled auth methods.

Method	Path
GET	/sys/auth

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/auth

Sample response

{
  "request_id": "9bc0fab8-d65c-3961-afe6-d05f50c5fd22",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "github/": {
      "accessor": "auth_github_badd7fd0",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0,
        "token_type": "default-service"
      },
      "deprecation_status": "supported",
      "description": "",
      "external_entropy_access": false,
      "local": false,
      "options": null,
      "plugin_version": "",
      "running_plugin_version": "v1.12.0+builtin.openbao",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "github",
      "uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be"
    },
    "token/": {
      "accessor": "auth_token_bd90f507",
      "config": {
        "default_lease_ttl": 0,
        "force_no_cache": false,
        "max_lease_ttl": 0,
        "token_type": "default-service"
      },
      "description": "token based credentials",
      "external_entropy_access": false,
      "local": false,
      "options": null,
      "plugin_version": "",
      "running_plugin_version": "v1.12.0+builtin.openbao",
      "running_sha256": "",
      "seal_wrap": false,
      "type": "token",
      "uuid": "e162baec-721b-7657-7913-c960df402f8a"
    }
  },
  "warnings": null
}

Enable auth method

This endpoint enables a new auth method. After enabling, the auth method can be accessed and configured via the auth path specified as part of the URL. This auth path will be nested under the auth prefix.

For example, enable the "foo" auth method will make it accessible at /auth/foo.

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
POST	/sys/auth/:path

Parameters

• path (string: <required>) – Specifies the path in which to enable the auth method. This is part of the request URL.

danger

NOTE: Use ASCII printable characters to specify the desired path.

• description (string: "") – Specifies a human-friendly description of the auth method.

• type (string: <required>) – Specifies the name of the authentication method type, such as "github" or "token".

• config (map<string|string>: nil) – Specifies configuration options for this auth method. These are the possible values:

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

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

  • audit_non_hmac_request_keys (array: []) - List of keys that will not be HMAC'd by audit devices in the request data object.

  • audit_non_hmac_response_keys (array: []) - List of keys that will not be HMAC'd by audit devices in the response data object.

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

  • passthrough_request_headers (array: []) - List of headers to allow and pass from the request to the plugin.

  • allowed_response_headers (array: []) - List of headers to allow, allowing a plugin to include them in the response.

  • plugin_version (string: "") – Specifies the semantic version of the plugin to use, e.g. "v1.0.0". If unspecified, the server will select any matching unversioned plugin that may have been registered, the latest versioned plugin registered, or a built-in plugin in that order of precendence.

Sample payload

{
  "type": "github",
  "description": "Login with GitHub"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/auth/my-auth

Read auth method configuration

This endpoints returns the configuration of the auth method at the given path.

Method	Path
GET	/sys/auth/:path

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/auth/my-auth

Sample response

{
  "request_id": "8d2a1e33-4c00-46a5-f50d-4dc5f5d96f12",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "accessor": "auth_github_badd7fd0",
    "config": {
      "default_lease_ttl": 0,
      "force_no_cache": false,
      "max_lease_ttl": 0,
      "token_type": "default-service"
    },
    "deprecation_status": "supported",
    "description": "",
    "external_entropy_access": false,
    "local": false,
    "options": null,
    "plugin_version": "",
    "running_plugin_version": "v1.12.0+builtin.openbao",
    "running_sha256": "",
    "seal_wrap": false,
    "type": "github",
    "uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be"
  },
  "warnings": null
}

Disable auth method

This endpoint disables the auth method at the given auth path.

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
DELETE	/sys/auth/:path

Parameters

• path (string: <required>) – Specifies the path to disable. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/auth/my-auth

Read auth method tuning

• This endpoint reads the given auth path's configuration. This endpoint requires sudo capability on the final path, but the same functionality can be achieved without sudo via sys/mounts/auth/[auth-path]/tune._

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
GET	/sys/auth/:path/tune

Parameters

• path (string: <required>) – Specifies the path in which to tune.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/auth/my-auth/tune

Sample response

{
  "default_lease_ttl": 2764800,
  "description": "",
  "force_no_cache": false,
  "max_lease_ttl": 2764800,
  "token_type": "default-service"
}

Tune auth method

Tune configuration parameters for a given auth path. This endpoint requires sudo capability on the final path, but the same functionality can be achieved without sudo via sys/mounts/auth/[auth-path]/tune.

• sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
POST	/sys/auth/:path/tune

Parameters

• default_lease_ttl (int: 0) – Specifies the default time-to-live. If set on a specific auth path, this overrides the global default.

• max_lease_ttl (int: 0) – Specifies the maximum time-to-live. If set on a specific auth path, this overrides the global default.

• description (string: "") – Specifies the description of the mount. This overrides the current stored value, if any.

• audit_non_hmac_request_keys (array: []) - Specifies the list of keys that will not be HMAC'd by audit devices in the request data object.

• audit_non_hmac_response_keys (array: []) - Specifies the list of keys that will not be HMAC'd by audit devices in the response data object.

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

• passthrough_request_headers (array: []) - List of headers to allow and pass from the request to the plugin.

• allowed_response_headers (array: []) - List of headers to allow, allowing a plugin to include them in the response.

• token_type (string: "") – Specifies the type of tokens that should be returned by the mount. The following values are available:

  • default-service: Unless the auth method requests a different type, issue service tokens
  • default-batch: Unless the auth method requests a different type, issue batch tokens
  • service: Override any auth method preference and always issue service tokens from this mount
  • batch: Override any auth method preference and always issue batch tokens from this mount

• plugin_version (string: "") – Specifies the semantic version of the plugin to use, e.g. "v1.0.0". Changes will not take effect until the mount is reloaded.

• user_lockout_config (map<string|string>: nil) – Specifies the user lockout configuration for the mount. These are the possible values:

  • lockout_threshold (string: "") - Specifies the number of failed login attempts after which the user is locked out, specified as a string like "15".

  • lockout_duration (string: "") - Specifies the duration for which an user will be locked out, specified as a string duration like "5s" or "30m".

  • lockout_counter_reset (string: "") - Specifies the duration after which the lockout counter is reset with no failed login attempts, specified as a string duration like "5s" or "30m".

  • lockout_disable (bool: false) - Disables the user lockout feature for this mount if set to true.

Sample payload

{
  "default_lease_ttl": 1800,
  "max_lease_ttl": 86400,
  "audit_non_hmac_request_keys": ["client_nonce"],
  "user_lockout_config":{
    "lockout_threshold":"20",
    "lockout_duration":"5m",
    "lockout_counter_reset":"5m"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/auth/my-auth/tune