mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-03 20:17:59 +00:00
388 lines
12 KiB
Plaintext
388 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.
|
||
|
||
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. If the goal of marking an auth method
|
||
as `local` was to comply with GDPR guidelines, then care must be taken to not
|
||
set the data pertaining to local auth mount or local auth mount aliases in the
|
||
metadata of the associated entity. Metadata related to local auth mount aliases
|
||
can be stored as `custom_metadata` on the alias itself which will also be
|
||
retained locally to the cluster.
|
||
|
||
~> ** 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.
|
||
|
||
| 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
|
||
```
|