mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-10 00:27:02 +02:00
e287773fd8
I'm using an internal document for reviewing these changes. Please reach out to me if you want to discuss these further.
395 lines
12 KiB
Plaintext
395 lines
12 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/auth - HTTP API
|
||
description: The `/sys/auth` endpoint is used to manage auth methods in Vault.
|
||
---
|
||
|
||
# `/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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/auth
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"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.vault",
|
||
"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.vault",
|
||
"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.
|
||
|
||
!> **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 precedence.
|
||
|
||
- `identity_token_key` `(string: "")` - The key to use for signing plugin workload
|
||
identity tokens. If not provided, this will default to Vault's OIDC
|
||
[default key](/vault/docs/concepts/oidc-provider#keys).
|
||
|
||
Additionally, the following options are allowed in Vault open-source, but
|
||
relevant functionality is only supported in Vault Enterprise:
|
||
|
||
- `local` `(bool: false)` – Specifies if the auth method is local only. Local
|
||
auth methods are not replicated nor (if a secondary) removed by replication.
|
||
Local auth mounts also generate entities for tokens issued. The entity will
|
||
be replicated across clusters and the aliases generated on the local auth
|
||
mount will be local to the cluster. Entities created by local auth mounts
|
||
are still replicated to other clusters, however it is possible to prevent
|
||
data pertaining to the local auth mount, including related aliases, from being
|
||
replicated by omitting them from the entity metadata.
|
||
|
||
~> ** Warning:** Remember, policies when using replication secondaries are
|
||
validated by the local cluster. An administrator that can set up a local auth
|
||
method mount can assign policies to tokens that are valid on the replication
|
||
primary if a request is forwarded. Never give untrusted administrators the
|
||
ability to assign policies or configure authentication methods.
|
||
|
||
- `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.
|
||
|
||
### Sample payload
|
||
|
||
```json
|
||
{
|
||
"type": "github",
|
||
"description": "Login with GitHub"
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ 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.
|
||
_This endpoint requires `sudo` capability on the final path, but the same
|
||
functionality can be achieved without `sudo` via `sys/mounts/auth/[auth-path]`._
|
||
|
||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||
any path-specific capabilities.
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------- |
|
||
| `GET` | `/sys/auth/:path` |
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/auth/my-auth
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"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.vault",
|
||
"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
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/auth/my-auth/tune
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"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. User lockout feature was added in Vault 1.13. 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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/sys/auth/my-auth/tune
|
||
```
|