luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

API Docs updates (#3101)

This commit is contained in:
Chris Hoffman 2017-08-08 12:28:17 -04:00 committed by GitHub
parent af4d141e3b
commit 191d48f848
21 changed files with 4035 additions and 4583 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
website/source/api/auth/app-id/index.html.md Normal file
View File

@ -0,0 +1,17 @@
---
layout: "api"
page_title: "App ID Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-appid"
description: |-
This is the API documentation for the Vault App ID authentication backend.
---
# App ID Auth Backend HTTP API (DEPRECATED)
This is the API documentation for the Vault App ID authentication backend. For
general information about the usage and operation of the App ID backend, please
see the [Vault App ID backend documentation](/docs/auth/app-id.html).
This documentation assumes the App ID backend is mounted at the `/auth/app-id`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.

630
website/source/api/auth/approle/index.html.md Normal file
View File

@ -0,0 +1,630 @@
---
layout: "api"
page_title: "AppRole Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-approle"
description: |-
This is the API documentation for the Vault AppRole authentication backend.
---
# AppRole Auth Backend HTTP API
This is the API documentation for the Vault AppRole authentication backend. For
general information about the usage and operation of the AppRole backend, please
see the [Vault AppRole backend documentation](/docs/auth/approle.html).
This documentation assumes the AppRole backend is mounted at the `/auth/approle`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.
## List Roles
This endpoint returns a list the existing AppRoles in the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/approle/role` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/approle/role
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"dev",
"prod",
"test"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Create New AppRole
Creates a new AppRole or updates an existing AppRole. This endpoint
supports both `create` and `update` capabilities. There can be one or more
constraints enabled on the role. It is required to have at least one of them
enabled while creating or updating a role.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when
logging in using this AppRole.
- `bind_cidr_list` `(array: [])` - Comma-separated list of CIDR blocks; if set,
specifies blocks of IP addresses which can perform the login operation.
- `policies` `(array: [])` - Comma-separated list of policies set on tokens
issued via this AppRole.
- `secret_id_num_uses` `(integer: 0)` - Number of times any particular SecretID
can be used to fetch a token from this AppRole, after which the SecretID will
expire. A value of zero will allow unlimited uses.
- `secret_id_ttl` `(string: "")` - Duration in either an integer number of
seconds (`3600`) or an integer time unit (`60m`) after which any SecretID
expires.
- `token_num_uses` `(integer: 0)` - Number of times issued tokens can be used.
A value of 0 means unlimited uses.
- `token_ttl` `(string: "")` - Duration in either an integer number of seconds
(`3600`) or an integer time unit (`60m`) to set as the TTL for issued tokens
and at renewal time.
- `token_max_ttl` `(string: "")` - Duration in either an integer number of
seconds (`3600`) or an integer time unit (`60m`) after which the issued token
can no longer be renewed.
- `period` `(string: "")` - Duration in either an integer number of seconds
(`3600`) or an integer time unit (`60m`). If set, the token generated using
this AppRole is a _periodic_ token; so long as it is renewed it never expires,
but the TTL set on the token at each renewal is fixed to the value specified
here. If this value is modified, the token will pick up the new value at its
next renewal.
### Sample Payload
```json
{
"token_ttl": "10m",
"token_max_ttl": "15m",
"policies": [
"default"
],
"period": 0,
"bind_secret_id": true
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/approle/role/application1
```
## Read AppRole
Reads the properties of an existing AppRole.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/approle/role/:role_name` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/approle/role/application1
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"token_ttl": 1200,
"token_max_ttl": 1800,
"secret_id_ttl": 600,
"secret_id_num_uses": 40,
"policies": [
"default"
],
"period": 0,
"bind_secret_id": true,
"bound_cidr_list": ""
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Delete AppRole
Deletes an existing AppRole from the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/approle/role/:role_name` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/approle/role/application1
```
## Read AppRole Role ID
Reads the RoleID of an existing AppRole.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/approle/role/:role_name/role-id` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/approle/role/application1/role-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Update AppRole Role ID
Updates the RoleID of an existing AppRole to a custom value.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/role-id` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `role_id` `(string: <required>)` - Value to be set as RoleID.
### Sample Payload
```json
{
"role_id": "custom-role-id"
}
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/role-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Generate New Secret ID
Generates and issues a new SecretID on an existing AppRole. Similar to
tokens, the response will also contain a `secret_id_accessor` value which can
be used to read the properties of the SecretID without divulging the SecretID
itself, and also to delete the SecretID from the AppRole.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `metadata` `(map: {})` - Metadata to be tied to the SecretID. This should be
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
audit logs _in plaintext_.
- `cidr_list` `(string: "")` - Comma separated list of CIDR blocks enforcing
secret IDs to be used from ppecific set of IP addresses. If 'bound_cidr_list'
is set on the role, then the list of CIDR blocks listed here should be a
subset of the CIDR blocks listed on the role.
### Sample Payload
```json
{
"metadata": {
"tag1": "production"
}
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/secret-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## List Secret ID Accessors
Lists the accessors of all the SecretIDs issued against the AppRole.
This includes the accessors for "custom" SecretIDs as well.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/approle/role/:role_name/secret-id` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/approle/role/application1/secret-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"ce102d2a-8253-c437-bf9a-aceed4241491",
"a1c8dee4-b869-e68d-3520-2040c1a0849a",
"be83b7e2-044c-7244-07e1-47560ca1c787",
"84896a0c-1347-aa90-a4f6-aca8b7558780",
"239b1328-6523-15e7-403a-a48038cdc45a"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read AppRole Secret ID
Reads out the properties of a SecretID.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id/lookup` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - Secret ID attached to the role.
### Sample Payload
```json
{
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--payload @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/secret-id/lookup
```
## Destroy AppRole Secret ID
Destroy an AppRole secret ID.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id/destroy` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - Secret ID attached to the role.
### Sample Payload
```json
{
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--payload @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/secret-id/destroy
```
## Read AppRole Secret ID Accessor
Reads out the properties of a SecretID.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/lookup` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id_accessor` `(string: <required>)` - Secret ID accessor attached to the role.
### Sample Payload
```json
{
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--payload @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/secret-id-accessor/lookup
```
## Destroy AppRole Secret ID Accessor
Destroy an AppRole secret ID by its accessor.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/destroy` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id_accessor` `(string: <required>)` - Secret ID accessor attached to the role.
### Sample Payload
```json
{
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--payload @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/secret-id-accessor/destroy
```
## Create Custom AppRole Secret ID
Assigns a "custom" SecretID against an existing AppRole. This is used in the
"Push" model of operation.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/role/:role_name/custom-secret-id` | `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - SecretID to be attached to the Role.
- `metadata` `(map: {})` - Metadata to be tied to the SecretID. This should be
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
audit logs _in plaintext_.
- `cidr_list` `(string: "")` - Comma separated list of CIDR blocks enforcing
secret IDs to be used from ppecific set of IP addresses. If 'bound_cidr_list'
is set on the role, then the list of CIDR blocks listed here should be a
subset of the CIDR blocks listed on the role.
### Sample Payload
```json
{
"secret-id": "testsecretid"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/approle/role/application1/custom-secret-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id": "testsecretid"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Login With AppRole
Issues a Vault token based on the presented credentials. `role_id` is always
required; if `bind_secret_id` is enabled (the default) on the AppRole,
`secret_id` is required too. Any other bound authentication values on the
AppRole (such as client IP CIDR) are also evaluated.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/approle/login` | `200 application/json` |
### Parameters
- `role_id` `(string: <required>)` - RoleID of the AppRole.
- `secret_id` `(string: <required>)` - SecretID belonging to AppRole.
### Sample Payload
```json
{
"role_id": "59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8",
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/approle/login
```
### Sample Response
```json
{
"auth": {
"renewable": true,
"lease_duration": 1200,
"metadata": null,
"policies": [
"default"
],
"accessor": "fd6c9a00-d2dc-3b11-0be5-af7ae0e1d374",
"client_token": "5b1a0318-679c-9c45-e5c6-d1b9a9035d49"
},
"warnings": null,
"wrap_info": null,
"data": null,
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read, Update, or Delete AppRole Properties
Updates the respective property in the existing AppRole. All of these
parameters of the AppRole can be updated using the `/auth/approle/role/:role_name`
endpoint directly. The endpoints for each field is provided separately
to be able to delegate specific endpoints using Vault's ACL system.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/policies` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-num-uses` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-max-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/bind-secret-id` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/bound-cidr-list` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/period` | `200/204` |
Refer to `/auth/approle/role/:role_name` endpoint.

1254
website/source/api/auth/aws/index.html.md Normal file
View File

File diff suppressed because it is too large Load Diff

329
website/source/api/auth/cert/index.html.md Normal file
View File

@ -0,0 +1,329 @@
---
layout: "api"
page_title: "TLS Certificate Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-cert"
description: |-
This is the API documentation for the Vault TLS Certificate authentication
backend.
---
# TLS Certificate Auth Backend HTTP API
This is the API documentation for the Vault TLS Certificate authentication
backend. For general information about the usage and operation of the TLS
Certificate backend, please see the [Vault TLS Certificate backend documentation](/docs/auth/cert.html).
This documentation assumes the TLS Certificate backend is mounted at the
`/auth/cert` path in Vault. Since it is possible to mount auth backends at any
location, please update your API calls accordingly.
## Create CA Certificate Role
Sets a CA cert and associated parameters in a role name.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/cert/certs/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - The name of the certificate role.
- `certificate` `(string: <required>)` - The PEM-format CA certificate.
- `allowed_names` `(string: "")` - Constrain the Common and Alternative Names in
the client certificate with a [globbed pattern]
(https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
a comma-separated list of patterns. Authentication requires at least one Name matching at least one pattern. If not set, defaults to allowing all names.
- `policies` `(string: "")` - A comma-separated list of policies to set on tokens
issued when authenticating against this CA certificate.
- `display_name` `(string: "")` - The `display_name` to set on tokens issued
when authenticating against this CA certificate. If not set, defaults to the
name of the role.
- `ttl` `(string: "")` - The TTL period of the token, provided as a number of
seconds. If not provided, the token is valid for the the mount or system
default TTL time, in that order.
### Sample Payload
```json
{
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"display_name": "test"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
https://vault.rocks/v1/auth/cert/certs/test-ca
```
## Read CA Certificate Role
Gets information associated with the named role.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/cert/certs/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` - The name of the certificate role.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/cert/certs/test-ca
```
### Sample Response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"display_name": "test",
"policies": "",
"allowed_names": "",
"ttl": 2764800
},
"warnings": null,
"auth": null
}
```
## List Certificate Roles
Lists configured certificate names.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/cert/certs` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/cert/certs
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"cert1",
"cert2"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Delete Certificate Role
Deletes the named role and CA cert from the backend mount.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/cert/certs/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - The name of the certificate role.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/cert/certs/cert1
```
## Create CRL
Sets a named CRL.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/cert/crls/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
- `crl` `(string: <required>)` - The PEM format CRL.
### Sample Payload
```json
{
"crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--date @payload.json \
https://vault.rocks/v1/auth/cert/crls/custom-crl
```
## Read CRL
Gets information associated with the named CRL (currently, the serial
numbers contained within). As the serials can be integers up to an
arbitrary size, these are returned as strings.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/cert/crls/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/cert/crls/custom-crl
```
### Sample Response
```json
{
"auth": null,
"data": {
"serials": {
"13": {}
}
},
"lease_duration": 0,
"lease_id": "",
"renewable": false,
"warnings": null
}
```
## Delete Certificate Role
Deletes the named role and CA cert from the backend mount.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/cert/crls/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/cert/crls/cert1
```
## Configure TLS Certificate Backend
Configuration options for the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/cert/config` | `204 (empty body)` |
### Parameters
- `disable_binding` `(boolean: false)` - If set, during renewal, skips the
matching of presented client identity with the client identity used during
login.
### Sample Payload
```json
{
"disable_binding": true
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--date @payload.json \
https://vault.rocks/v1/auth/cert/certs/cert1
```
## Login with TLS Certiicate Backend
Log in and fetch a token. If there is a valid chain to a CA configured in the
backend and all role constraints are matched, a token will be issued.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/cert/login` | `200 application/json` |
### Parameters
- `name` `(string: "")` - Authenticate against only the named certificate role,
returning its policy list if successful. If not set, defaults to trying all
certificate roles and returning any one that matches.
### Sample Payload
```json
{
"name": "cert1"
}
```
### Sample Request
```
$ curl \
--request POST \
--date @payload.json \
https://vault.rocks/v1/auth/cert/login
```
### Sample Response
```json
{
"auth": {
"client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425",
"policies": [
"web",
"stage"
],
"lease_duration": 3600,
"renewable": true,
}
}
```

17
website/source/api/auth/github/index.html.md Normal file
View File

@ -0,0 +1,17 @@
---
layout: "api"
page_title: "Github Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-github"
description: |-
This is the API documentation for the Vault Github authentication backend.
---
# Github Auth Backend HTTP API
This is the API documentation for the Vault Github authentication backend. For
general information about the usage and operation of the Github backend, please
see the [Vault Github backend documentation](/docs/auth/github.html).
This documentation assumes the Github backend is mounted at the `/auth/github`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.

19
website/source/api/auth/index.html.md Normal file
View File

@ -0,0 +1,19 @@
---
layout: "api"
page_title: "HTTP API"
sidebar_current: "docs-http-auth"
description: |-
Each authentication backend publishes its own set of API paths and methods.
These endpoints are documented in this section.
---
# Authentication Backends
Each authentication backend publishes its own set of API paths and methods.
These endpoints are documented in this section. Authentication backends are
mount at a path, but the documentation will assume the default mount points for
simplicity. If you are mounting at a different path, you should adjust your API
calls accordingly.
For the API documentation for a specific authentication backend, please choose a
authentication backend from the navigation.

450
website/source/api/auth/ldap/index.html.md Normal file
View File

@ -0,0 +1,450 @@
---
layout: "api"
page_title: "LDAP Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-ldap"
description: |-
This is the API documentation for the Vault LDAP authentication backend.
---
# LDAP Auth Backend HTTP API
This is the API documentation for the Vault LDAP authentication backend. For
general information about the usage and operation of the LDAP backend, please
see the [Vault LDAP backend documentation](/docs/auth/ldap.html).
This documentation assumes the LDAP backend is mounted at the `/auth/ldap`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.
## Configure LDAP Backend
This endpoint configures the LDAP authentication backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/ldap/config` | `204 (empty body)` |
### Parameters
- `url` `(string: <required>)` – The LDAP server to connect to. Examples:
`ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`
- `starttls` `(bool: false)` – If true, issues a `StartTLS` command after
establishing an unencrypted connection.
- `tls_min_version` `(string: tls12)` – Minimum TLS version to use. Accepted
values are `tls10`, `tls11` or `tls12`.
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
values are `tls10`, `tls11` or `tls12`.
- `insecure_tls` `(bool: false)` – If true, skips LDAP server SSL certificate
verification - insecure, use with caution!
- `certificate` `(string: "")` – CA certificate to use when verifying LDAP server
certificate, must be x509 PEM encoded.
- `binddn` `(string: "")` – Distinguished name of object to bind when performing
user search. Example: `cn=vault,ou=Users,dc=example,dc=com`
- `bindpass` `(string: "")` – Password to use along with `binddn` when performing
user search.
- `userdn` `(string: "")` – Base DN under which to perform user search. Example:
`ou=Users,dc=example,dc=com`
- `userattr` `(string: "")` – Attribute on user attribute object matching the
username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid`
- `discoverdn` `(bool: false)` – Use anonymous bind to discover the bind DN of a
user.
- `deny_null_bind` `(bool: true)` – This option prevents users from bypassing
authentication when providing an empty password.
- `upndomain` `(string: "")` – The userPrincipalDomain used to construct the UPN
string for the authenticating user. The constructed UPN will appear as
`[username]@UPNDomain`. Example: `example.com`, which will cause vault to bind
as `username@example.com`.
- `groupfilter` `(string: "")` – Go template used when constructing the group
membership query. The template can access the following context variables:
\[`UserDN`, `Username`\]. The default is
`(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`,
which is compatible with several common directory schemas. To support
nested group resolution for Active Directory, instead use the following
query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`.
- `groupdn` `(string: "")` – LDAP search base to use for group membership
search. This can be the root containing either groups or users. Example:
`ou=Groups,dc=example,dc=com`
- `groupattr` `(string: "")` – LDAP attribute to follow on objects returned by
`groupfilter` in order to enumerate user group membership. Examples: for
groupfilter queries returning _group_ objects, use: `cn`. For queries
returning _user_ objects, use: `memberOf`. The default is `cn`.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/ldap/config
```
### Sample Payload
```json
{
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"url": "ldaps://ldap.myorg.com:636",
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com"
}
```
## Read LDAP Configuration
This endpoint retrieves the LDAP configuration for the authentication backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/ldap/config` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/ldap/config
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"bindpass": "",
"certificate": "",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"upndomain": "",
"url": "ldaps://ldap.myorg.com:636",
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## List LDAP Groups
This endpoint returns a list of existing groups in the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/ldap/groups` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/ldap/groups
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"scientists",
"engineers"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read LDAP Group
This endpoint returns the policies associated with a LDAP group.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/ldap/groups/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/ldap/groups/admins
```
### Sample Response
```json
{
"data": {
"policies": "admin,default"
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
```
## Create/Update LDAP Group
This endpoint creates or updates LDAP group policies.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/ldap/groups/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group
- `policies` `(string: "")` – Comma-separated list of policies associated to the
group.
### Sample Payload
```json
{
"policies": "admin,default"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/ldap/groups/admins
```
## Delete LDAP Group
This endpoint deletes the LDAP group and policy association.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/ldap/groups/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – The name of the LDAP group
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/ldap/groups/admins
```
## List LDAP Users
This endpoint returns a list of existing users in the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/ldap/users` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/ldap/users
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"mitchellh",
"armon"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Read LDAP User
This endpoint returns the policies associated with a LDAP user.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/ldap/users/:username` | `200 application/json` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/ldap/users/mitchellh
```
### Sample Response
```json
{
"data": {
"policies": "admin,default",
"groups": ""
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
```
## Create/Update LDAP User
This endpoint creates or updates LDAP users policies and group associations.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/ldap/users/:username` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
- `policies` `(string: "")` – Comma-separated list of policies associated to the
user.
- `groups` `(string: "")` – Comma-separated list of groups associated to the
user.
### Sample Payload
```json
{
"policies": "admin,default"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/ldap/users/mitchellh
```
## Delete LDAP User
This endpoint deletes the LDAP user and policy association.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/ldap/users/:username` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/ldap/users/mitchellh
```
## Login with LDAP User
This endpoint allows you to log in with LDAP credentials
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/ldap/login/:username` | `200 application/json` |
### Parameters
- `username` `(string: <required>)` – The username of the LDAP user
- `password` `(string: <required>)` – The password for the LDAP user
### Sample Payload
```json
{
"password": "MyPassword1"
}
```
### Sample Request
```
$ curl \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/ldap/login/mitchellh
```
### Sample Response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"auth": {
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies": [
"admins",
"default"
],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 0,
"renewable": false
}
}
```

17
website/source/api/auth/mfa/index.html.md Normal file
View File

@ -0,0 +1,17 @@
---
layout: "api"
page_title: "MFA Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-mfa"
description: |-
This is the API documentation for the Vault MFA authentication backend.
---
# MFA Auth Backend HTTP API
This is the API documentation for the Vault MFA authentication backend. For
general information about the usage and operation of the AppRole backend, please
see the [Vault MFA backend documentation](/docs/auth/mfa.html).
This documentation assumes the MFA backend is mounted at the `/auth/mfa`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.

17
website/source/api/auth/okta/index.html.md Normal file
View File

@ -0,0 +1,17 @@
---
layout: "api"
page_title: "Okta Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-okta"
description: |-
This is the API documentation for the Vault Okta authentication backend.
---
# Okta Auth Backend HTTP API
This is the API documentation for the Vault Okta authentication backend. For
general information about the usage and operation of the Okta backend, please
see the [Vault Okta backend documentation](/docs/auth/okta.html).
This documentation assumes the Okta backend is mounted at the `/auth/okta`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.

238
website/source/api/auth/radius/index.html.md Normal file
View File

@ -0,0 +1,238 @@
---
layout: "api"
page_title: "RADIUS Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-radius"
description: |-
This is the API documentation for the Vault RADIUS authentication backend.
---
# RADIUS Auth Backend HTTP API
This is the API documentation for the Vault RADIUS authentication backend. For
general information about the usage and operation of the RADIUS backend, please
see the [Vault RADIUS backend documentation](/docs/auth/radius.html).
This documentation assumes the RADIUS backend is mounted at the `/auth/radius`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.
## Configure RADIUS
Configures the connection parameters and shard secret used to communicate with
RADIUS.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/radius/config` | `204 (empty body)` |
### Parameters
- `host` `(string: <required>)` - The RADIUS server to connect to. Examples:
`radius.myorg.com`, `127.0.0.1`
- `port` `(integer: 1812)` - The UDP port where the RADIUS server is listening
on. Defaults is 1812.
- `secret` `(string: <required>)` - The RADIUS shared secret.
- `unregistered_user_policies` `(string: "")` - A comma-separated list of
policies to be granted to unregistered users.
- `dial_timeout` `(integer: 10)` - Number of second to wait for a backend
connection before timing out. Defaults is 10.
- `read_timeout` `(integer: 10)` - Number of second to wait for a backend
response before timing out. Defaults is 10.
- `nas_port` `(integer: 10)` - The NAS-Port attribute of the RADIUS request.
Defaults is 10.
### Sample Payload
```json
{
"host": "radius.myorg.com",
"port": 1812,
"secret": "mySecret"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/radius/config
```
## Register User
Registers a new user and maps a set of policies to it. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/radius/users/:username` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
- `policies` `(string: "")` - Comma-separated list of policies. If set to
empty string, only the `default` policy will be applicable to the user.
```json
{
"policies": "dev,prod",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/radius/users/test-user
```
## Read User
Reads the properties of an existing username.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/radius/users/:username` | `200 application/json` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/radius/users/test-user
```
### Sample Response
```javascript
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"policies": "default,dev"
},
"warnings": null
}
```
## Delete User
Deletes an existing username from the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/radius/users/:username` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/radius/users/test-user
```
## List Users
List the users registered with the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/radius/users` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/radius/users
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"devuser",
"produser"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Login
Login with the username and password.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/radius/login` | `200 application/json` |
| `POST` | `/auth/radius/login/:username` | `200 application/json` |
### Parameters
- `username` `(string: <required>)` - Username for this user.
- `password` `(string: <required>)` - Password for the autheticating user.
### Sample Payload
```json
{
"password": "Password!"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://vault.rocks/v1/auth/radius/login/test-user
```
### Sample Response
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "vishal"
},
},
"lease_duration": 7200,
"renewable": true
}
```

702
website/source/api/auth/token/index.html.md Normal file
View File

@ -0,0 +1,702 @@
---
layout: "api"
page_title: "Token Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-token"
description: |-
This is the API documentation for the Vault token authentication backend.
---
# Token Auth Backend HTTP API
This is the API documentation for the Vault token authentication backend. For
general information about the usage and operation of the token backend, please
see the [Vault Token backend documentation](/docs/auth/token.html).
## List Accessors
This endpoint lists token accessor. This requires `sudo` capability, and access
to it should be tightly controlled as the accessors can be used to revoke very
large numbers of tokens and their associated leases at once.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/token/accessors` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/auth/token/accessors
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"476ea048-ded5-4d07-eeea-938c6b4e43ec",
"bb00c093-b7d3-b0e9-69cc-c4d85081165b"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Create Token
Creates a new token. Certain options are only available when called by a
root token. If used via the `/auth/token/create-orphan` endpoint, a root
token is not required to create an orphan token (otherwise set with the
`no_parent` option). If used with a role name in the path, the token will
be created against the specified role name; this may override options set
during this call.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/create` | `200 application/json` |
| `POST` | `/auth/token/create-orphan` | `200 application/json` |
| `POST` | `/auth/token/create/:role_name` | `200 application/json` |
### Parameters
- `id` `(string: "")` – The ID of the client token. Can only be specified by a
root token. Otherwise, the token ID is a randomly generated UUID.
- `role_name` `(string: "")` – The name of the token role.
- `policies` `(array: "")` – A list of policies for the token. This must be a
subset of the policies belonging to the token making the request, unless root.
If not specified, defaults to all the policies of the calling token.
- `meta` `(map: {})` – A map of string to string valued metadata. This is
passed through to the audit backends.
- `no_parent` `(bool: false)` - If true and set by a root caller, the token will
not have the parent token of the caller. This creates a token with no parent.
- `no_default_policy` `(bool: false)` - If true the `default` policy will not be
contained in this token's policy set.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
to be renewed past its initial TTL. Setting the value to `true` will allow
the token to be renewable up to the system/mount maximum TTL.
- `lease` `(string: "")` - DEPRECATED; use `ttl` instead
- `ttl` `(string: "")` -The TTL period of the token, provided as "1h", where
hour is the largest suffix. If not provided, the token is valid for the
[default lease TTL](/docs/configuration/index.html), or indefinitely if the
root policy is used.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL *cannot* be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
or used past the value set at issue time.
- `display_name` `(string: "token")` - The display name of the token.
- `num_uses` `(integer: 0)` - The maximum uses for the given token. This can be
used to create a one-time-token or limited use token. The value of 0 has no
limit to the number of uses.
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
will use the given period. Requires a root/sudo token to use.
### Sample Payload
```json
{
"policies": [
"web",
"stage"
],
"metadata": {
"user": "armon"
},
"ttl": "1h",
"renewable": true
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/create
```
### Sample Response
```json
{
"auth": {
"client_token": "ABCD",
"policies": [
"web",
"stage"
],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true,
}
}
```
## Lookup a Token
Returns information about the client token.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/lookup` | `200 application/json` |
| `GET` | `/auth/token/lookup/:token` | `200 application/json` |
### Parameters
- `token` `(string: <required>)` - Token to lookup.
### Sample Payload
```json
{
"token": "ClientToken"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/lookup
```
### Sample Response
```json
{
"data": {
"id": "ClientToken",
"policies": [
"web",
"stage"
],
"path": "auth/github/login",
"meta": {
"user": "armon",
"organization": "hashicorp"
},
"display_name": "github-armon",
"num_uses": 0,
}
}
```
## Lookup a Token (Self)
Returns information about the current client token.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/token/lookup-self` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/token/lookup-self
```
### Sample Response
```json
{
"data": {
"id": "ClientToken",
"policies": [
"web",
"stage"
],
"path": "auth/github/login",
"meta": {
"user": "armon",
"organization": "hashicorp"
},
"display_name": "github-armon",
"num_uses": 0,
}
}
```
## Lookup a Token Accessor
Returns information about the client token from the accessor.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/lookup-accessor` | `200 application/json` |
| `GET` | `/auth/token/lookup-accessor/:accessor` | `200 application/json` |
### Parameters
- `accessor` `(string: <required>)` - Token accessor to lookup.
### Sample Payload
```json
{
"accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/lookup-accessor
```
### Sample Response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"creation_time": 1457533232,
"creation_ttl": 2764800,
"display_name": "token",
"meta": null,
"num_uses": 0,
"orphan": false,
"path": "auth/token/create",
"policies": [
"default",
"web"
],
"ttl": 2591976
},
"warnings": null,
"auth": null
}
```
## Renew a Token
Renews a lease associated with a token. This is used to prevent the expiration
of a token, and the automatic revocation of it. Token renewal is possible only
if there is a lease associated with it.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/renew` | `200 application/json` |
| `POST` | `/auth/token/renew/:token` | `200 application/json` |
### Parameters
- `token` `(string: <required>)` - Token to renew. This can be part of the URL
or the body.
- `increment` `(string: "")` - An optional requested lease increment can be
provided. This increment may be ignored.
### Sample Payload
```json
{
"token": "ClientToken"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/renew
```
### Sample Response
```json
{
"auth": {
"client_token": "ABCD",
"policies": [
"web",
"stage"
],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true,
}
}
```
## Renew a Token (Self)
Renews a lease associated with the calling token. This is used to prevent the
expiration of a token, and the automatic revocation of it. Token renewal is
possible only if there is a lease associated with it.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/renew-self` | `200 application/json` |
### Parameters
- `increment` `(string: "")` - An optional requested lease increment can be
provided. This increment may be ignored.
### Sample Payload
```json
{
"increment": "1h"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/renew-self
```
### Sample Response
```json
{
"auth": {
"client_token": "ABCD",
"policies": [
"web",
"stage"
],
"metadata": {
"user": "armon"
},
"lease_duration": 3600,
"renewable": true,
}
}
```
## Revoke a Token
Revokes a token and all child tokens. When the token is revoked, all secrets
generated with it are also revoked.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/revoke` | `204 (empty body)` |
### Parameters
- `token` `(string: <required>)` - Token to revoke.
### Sample Payload
```json
{
"token": "ClientToken"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/revoke
```
## Revoke a Token (Self)
Revokes the token used to call it and all child tokens. When the token is
revoked, all dynamic secrets generated with it are also revoked.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/revoke-self` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://vault.rocks/v1/auth/token/revoke-self
```
## Revoke a Token Accessor
Revoke the token associated with the accessor and all the child tokens. This is
meant for purposes where there is no access to token ID but there is need to
revoke a token and its children.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/revoke-accessor` | `204 (empty body)` |
### Parameters
- `accessor` `(string: <required>)` - Accessor of the token.
### Sample Payload
```json
{
"accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/revoke-accessor
```
## Revoke Token and Orphan Children
Revokes a token but not its child tokens. When the token is revoked, all secrets
generated with it are also revoked. All child tokens are orphaned, but can be
revoked sub-sequently using `/auth/token/revoke/`. This is a root-protected
endpoint.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/revoke-orphan` | `204 (empty body)` |
| `POST` | `/auth/token/revoke-orphan/:token` | `204 (empty body)` |
### Parameters
- `token` `(string: <required>)` - Token to revoke. This can be part of the URL
or the body.
### Sample Payload
```json
{
"token": "ClientToken"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/token/revoke-orphan
```
## Read Token Role
Fetches the named role configuration.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/token/roles/:role_name`| `200 application/json` |
### Parameters
- `role_name` `(string: <required>)` - The name of the token role.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/token/roles/nomad
```
### Sample Response
```javascript
{
"request_id": "075a19cd-4e56-a3ca-d956-7609819831ec",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"allowed_policies": [
"dev"
],
"disallowed_policies": [],
"explicit_max_ttl": 0,
"name": "nomad",
"orphan": false,
"path_suffix": "",
"period": 0,
"renewable": true
},
"warnings": null
}
```
## List Token Roles
List available token roles.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/token/roles` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
https://vault.rocks/v1/auth/token/roles
```
### Sample Response
```json
{
"data": {
"keys": [
"role1",
"role2"
]
}
}
```
## Create/Update Token Role
Creates (or replaces) the named role. Roles enforce specific behavior when
creating tokens that allow token functionality that is otherwise not
available or would require `sudo`/root privileges to access. Role
parameters, when set, override any provided options to the `create`
endpoints. The role name is also included in the token path, allowing all
tokens created against a role to be revoked using the `sys/revoke-prefix`
endpoint.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/roles/:role_name` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` – The name of the token role.
- `allowed_policies` `(list: [])` – If set, tokens can be created with any
subset of the policies in this list, rather than the normal semantics of
tokens being a subset of the calling token's policies. The parameter is a
comma-delimited string of policy names. If at creation time
`no_default_policy` is not set and `"default"` is not contained in
`disallowed_policies`, the `"default"` policy will be added to the created
token automatically.
- `disallowed_policies` `(list: [])` – If set, successful token creation via
this role will require that no policies in the given list are requested. The
parameter is a comma-delimited string of policy names. Adding `"default"` to
this list will prevent `"default"` from being added automatically to created
tokens.
- `orphan` `(bool: true)` - If `true`, tokens created against this policy will
be orphan tokens (they will have no parent). As such, they will not be
automatically revoked by the revocation of any other token.
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
will use the given period. Requires a root/sudo token to use.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
to be renewed past its initial TTL. Setting the value to `true` will allow
the token to be renewable up to the system/mount maximum TTL.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL *cannot* be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
or used past the value set at issue time.
- `path_suffix` `(string: "")` - If set, tokens created against this role will
have the given suffix as part of their path in addition to the role name. This
can be useful in certain scenarios, such as keeping the same role name in the
future but revoking all tokens created against it before some point in time.
The suffix can be changed, allowing new callers to have the new suffix as part
of their path, and then tokens with the old suffix can be revoked via
`sys/revoke-prefix`.
### Sample Payload
```json
"allowed_policies": [
"dev"
],
"name": "nomad",
"orphan": false,
"renewable": true
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST
--data @payload.json
https://vault.rocks/v1/auth/token/roles/nomad
```
## Delete Token Role
This endpoint deletes the named token role.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/token/roles/:role_name` | `204 (empty body)` |
### Parameters
- `role_name` `(string: <required>)` - The name of the token role.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/token/roles/admins
```
## Tidy Tokens
Performs some maintenance tasks to clean up invalid entries that may remain
in the token store. Generally, running this is not needed unless upgrade
notes or support personnel suggest it. This may perform a lot of I/O to the
storage backend so should be used sparingly.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/token/tidy` | `204 (empty body)` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://vault.rocks/v1/auth/token/tidy
```

254
website/source/api/auth/userpass/index.html.md Normal file
View File

@ -0,0 +1,254 @@
---
layout: "api"
page_title: "Userpass Auth Backend - HTTP API"
sidebar_current: "docs-http-auth-userpass"
description: |-
This is the API documentation for the Vault username and password
authentication backend.
---
# Username & Password Auth Backend HTTP API
This is the API documentation for the Vault Username & Password authentication backend. For
general information about the usage and operation of the Username and Password backend, please
see the [Vault Userpass backend documentation](/docs/auth/userpass.html).
This documentation assumes the Username & Password backend is mounted at the `/auth/userpass`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.
## Create/Update User
Create a new user or update an existing user. This path honors the distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/userpass/users/:username` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `password` `(string: <required>)` - The password for the user. Only required
when creating the user.
- `policies` `(string: "")` – Comma-separated list of policies. If set to empty
string, only the `default` policy will be applicable to the user.
- `ttl` `(string: "")` - The lease duration which decides login expiration.
- `max_ttl` `(string: "")` - Maximum duration after which login should expire.
### Sample Payload
```json
{
"password": "superSecretPassword",
"policies": "admin,default"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/userpass/users/mitchellh
```
## Read User
Reads the properties of an existing username.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/userpass/users/:username` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/userpass/users/mitchellh
```
### Sample Response
```json
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"max_ttl": 0,
"policies": "default,dev",
"ttl": 0
},
"warnings": null
}
```
## Delete User
This endpoint deletes the user from the backend.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/auth/userpass/users/:username` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` - The username for the user.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/auth/userpass/users/mitchellh
```
## Update Password on User
Update password for an existing user.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/userpass/users/:username/password` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `password` `(string: <required>)` - The password for the user.
### Sample Payload
```json
{
"password": "superSecretPassword2",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/userpass/users/mitchellh/password
```
## Update Policies on User
Update policies for an existing user.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/userpass/users/:username/policies` | `204 (empty body)` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `policies` `(string: "")` – Comma-separated list of policies. If set to empty
### Sample Payload
```json
{
"policies": "policy1,policy2",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/userpass/users/mitchellh/policies
```
## List Users
List available userpass users.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/userpass/users` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
https://vault.rocks/v1/auth/userpass/users
```
### Sample Response
```json
{
"data": {
"keys": [
"mitchellh",
"armon"
]
}
}
```
## Login
Login with the username and password.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/userpass/login/:username` | `200 application/json` |
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `password` `(string: <required>)` - The password for the user.
### Sample Payload
```json
{
"password": "superSecretPassword2",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/auth/userpass/login/mitchellh
```
### Sample Response
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 7200,
"renewable": true
}
}
```

732
website/source/docs/auth/approle.html.md
View File

@ -219,733 +219,7 @@ $ curl -X POST \
```
## API
### /auth/approle/role
#### LIST/GET
<dl class="api">
<dt>Description</dt>
<dd>
Lists the existing AppRoles in the backend
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/approle/role` (LIST) or `/auth/approle/role?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"dev",
"prod",
"test"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/approle/role/[role_name]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates a new AppRole or updates an existing AppRole. This endpoint
supports both `create` and `update` capabilities. There can be one or more
constraints enabled on the role. It is required to have at least one of them
enabled while creating or updating a role.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">role_name</span>
<span class="param-flags">required</span>
Name of the AppRole.
</li>
</ul>
<ul>
<li>
<span class="param">bind_secret_id</span>
<span class="param-flags">optional</span>
Require `secret_id` to be presented when logging in using this AppRole.
Defaults to 'true'.
</li>
</ul>
<ul>
<li>
<span class="param">bound_cidr_list</span>
<span class="param-flags">optional</span>
Comma-separated list of CIDR blocks; if set, specifies blocks of IP
addresses which can perform the login operation.
</li>
</ul>
<ul>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
Comma-separated list of policies set on tokens issued via this AppRole.
</li>
</ul>
<ul>
<li>
<span class="param">secret_id_num_uses</span>
<span class="param-flags">optional</span>
Number of times any particular SecretID can be used to fetch a token
from this AppRole, after which the SecretID will expire.
</li>
</ul>
<ul>
<li>
<span class="param">secret_id_ttl</span>
<span class="param-flags">optional</span>
Duration in either an integer number of seconds (`3600`) or an integer
time unit (`60m`) after which any SecretID expires.
</li>
</ul>
<ul>
<li>
<span class="param">token_num_uses</span>
<span class="param-flags">optional</span>
Number of times issued tokens can be used.
</li>
</ul>
<ul>
<li>
<span class="param">token_ttl</span>
<span class="param-flags">optional</span>
Duration in either an integer number of seconds (`3600`) or an integer
time unit (`60m`) to set as the TTL for issued tokens and at renewal
time.
</li>
</ul>
<ul>
<li>
<span class="param">token_max_ttl</span>
<span class="param-flags">optional</span>
Duration in either an integer number of seconds (`3600`) or an integer
time unit (`60m`) after which the issued token can no longer be
renewed.
</li>
</ul>
<ul>
<li>
<span class="param">period</span>
<span class="param-flags">optional</span>
Duration in either an integer number of seconds (`3600`) or an integer
time unit (`60m`). If set, the token generated using this AppRole is a
_periodic_ token; so long as it is renewed it never expires, but the
TTL set on the token at each renewal is fixed to the value specified
here. If this value is modified, the token will pick up the new value
at its next renewal.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Reads the properties of an existing AppRole.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"token_ttl": 1200,
"token_max_ttl": 1800,
"secret_id_ttl": 600,
"secret_id_num_uses": 40,
"policies": [
"default"
],
"period": 0,
"bind_secret_id": true,
"bound_cidr_list": ""
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes an existing AppRole from the backend.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/approle/role/[role_name]/role-id
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Reads the RoleID of an existing AppRole.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/role-id`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Updates the RoleID of an existing AppRole to a custom value.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/role-id`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">role_id</span>
<span class="param-flags">required</span>
Value to be set as RoleID.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
`204` response code.
</dd>
</dl>
### /auth/approle/role/[role_name]/secret-id
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Generates and issues a new SecretID on an existing AppRole. Similar to
tokens, the response will also contain a `secret_id_accessor` value which can
be used to read the properties of the SecretID without divulging the SecretID
itself, and also to delete the SecretID from the AppRole.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/secret-id`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">metadata</span>
<span class="param-flags">optional</span>
Metadata to be tied to the SecretID. This should be a JSON-formatted
string containing the metadata in key-value pairs. This metadata will
be set on tokens issued with this SecretID, and is logged in audit logs
_in plaintext_.
</li>
</ul>
<ul>
<li>
<span class="param">cidr_list</span>
<span class="param-flags">optional</span>
Comma separated list of CIDR blocks enforcing secret IDs to be used from
specific set of IP addresses. If 'bound_cidr_list' is set on the role, then the
list of CIDR blocks listed here should be a subset of the CIDR blocks listed on
the role.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
Lists the accessors of all the SecretIDs issued against the AppRole.
This includes the accessors for "custom" SecretIDs as well.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/secret-id` (LIST) or `/auth/approle/role/[role_name]/secret-id?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"ce102d2a-8253-c437-bf9a-aceed4241491",
"a1c8dee4-b869-e68d-3520-2040c1a0849a",
"be83b7e2-044c-7244-07e1-47560ca1c787",
"84896a0c-1347-aa90-a4f6-aca8b7558780",
"239b1328-6523-15e7-403a-a48038cdc45a"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/approle/role/[role_name]/secret-id/lookup
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Reads out the properties of a SecretID.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/secret-id/lookup`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_id</span>
<span class="param-flags">required</span>
Secret ID attached to the role
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"request_id": "0d25d8ec-0d16-2842-1dda-c28c25aefd4b",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"cidr_list": null,
"creation_time": "2016-09-28T21:00:46.760570318-04:00",
"expiration_time": "0001-01-01T00:00:00Z",
"last_updated_time": "2016-09-28T21:00:46.760570318-04:00",
"metadata": {},
"secret_id_accessor": "b4bea6b2-0214-9f7f-33cf-e732155feadb",
"secret_id_num_uses": 10,
"secret_id_ttl": 0
}
}
```
</dd>
</dl>
### /auth/approle/role/[role_name]/secret-id/destroy
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Deletes a SecretID.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/secret-id/destroy`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_id</span>
<span class="param-flags">required</span>
Secret ID attached to the role
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
`204` response code.
</dd>
</dl>
### /auth/approle/role/[role_name]/secret-id-accessor/lookup
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Reads out the properties of the SecretID associated with the supplied
accessor.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/secret-id-accessor/lookup`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_id_accessor</span>
<span class="param-flags">required</span>
Accessor of the secret ID
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"request_id": "2132237e-d1b6-d298-6117-b54a2d938d00",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"cidr_list": null,
"creation_time": "2016-09-28T22:09:02.834238344-04:00",
"expiration_time": "0001-01-01T00:00:00Z",
"last_updated_time": "2016-09-28T22:09:02.834238344-04:00",
"metadata": {},
"secret_id_accessor": "54ba219d-b539-ac4f-e3cf-763c02f351fb",
"secret_id_num_uses": 10,
"secret_id_ttl": 0
}
}
```
</dd>
</dl>
### /auth/approle/role/[role_name]/secret-id-accessor/destroy
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Deletes the SecretID associated with the given accessor.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/secret-id-accessor/destroy`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_id_accessor</span>
<span class="param-flags">required</span>
Accessor of the secret ID
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
`204` response code.
</dd>
</dl>
### /auth/approle/role/[role_name]/custom-secret-id
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Assigns a "custom" SecretID against an existing AppRole. This is used in the
"Push" model of operation.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/custom-secret-id`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">secret_id</span>
<span class="param-flags">required</span>
SecretID to be attached to the Role.
</li>
</ul>
<ul>
<li>
<span class="param">metadata</span>
<span class="param-flags">optional</span>
Metadata to be tied to the SecretID. This should be a JSON-formatted
string containing the metadata in key-value pairs. This metadata will
be set on tokens issued with this SecretID, and is logged in audit logs
_in plaintext_.
</li>
</ul>
<ul>
<li>
<span class="param">cidr_list</span>
<span class="param-flags">optional</span>
Comma separated list of CIDR blocks enforcing secret IDs to be used from
specific set of IP addresses. If 'bound_cidr_list' is set on the role, then the
list of CIDR blocks listed here should be a subset of the CIDR blocks listed on
the role.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "a109dc4a-1fd3-6df6-feda-0ca28b2d4a81",
"secret_id": "testsecretid"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/approle/login
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Issues a Vault token based on the presented credentials. `role_id` is always
required; if `bind_secret_id` is enabled (the default) on the AppRole,
`secret_id` is required too. Any other bound authentication values on the
AppRole (such as client IP CIDR) are also evaluated.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/approle/login`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">role_id</span>
<span class="param-flags">required</span>
RoleID of the AppRole.
</li>
</ul>
<ul>
<li>
<span class="param">secret_id</span>
<span class="param-flags">required when `bind_secret_id` is enabled</span>
SecretID belonging to AppRole.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": {
"renewable": true,
"lease_duration": 1200,
"metadata": null,
"policies": [
"default"
],
"accessor": "fd6c9a00-d2dc-3b11-0be5-af7ae0e1d374",
"client_token": "5b1a0318-679c-9c45-e5c6-d1b9a9035d49"
},
"warnings": null,
"wrap_info": null,
"data": null,
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/approle/role/[role_name]/policies
### /auth/approle/role/[role_name]/secret-id-num-uses
### /auth/approle/role/[role_name]/secret-id-ttl
### /auth/approle/role/[role_name]/token-ttl
### /auth/approle/role/[role_name]/token-max-ttl
### /auth/approle/role/[role_name]/bind-secret-id
### /auth/approle/role/[role_name]/bound-cidr-list
### /auth/approle/role/[role_name]/period
#### POST/GET/DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Updates the respective property in the existing AppRole. All of these
parameters of the AppRole can be updated using the `/auth/approle/role/[role_name]`
endpoint directly. The endpoints for each field is provided separately
to be able to delegate specific endpoints using Vault's ACL system.
</dd>
<dt>Method</dt>
<dd>POST/GET/DELETE</dd>
<dt>URL</dt>
<dd>`/auth/approle/role/[role_name]/[field_name]`</dd>
<dt>Parameters</dt>
<dd>
Refer to `/auth/approle/role/[role_name]` endpoint.
</dd>
<dt>Returns</dt>
<dd>
Refer to `/auth/approle/role/[role_name]` endpoint.
</dd>
</dl>
The AppRole authentication backend has a full HTTP API. Please see the
[AppRole API](/api/auth/approle/index.html) for more
details.

1604
website/source/docs/auth/aws.html.md
View File

File diff suppressed because it is too large Load Diff

349
website/source/docs/auth/cert.html.md
View File

@ -124,350 +124,5 @@ of the header should be "X-Vault-Token" and the value should be the token.
## API
### /auth/cert/certs
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes the named role and CA cert from the backend mount.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/cert/certs/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Gets information associated with the named role.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/cert/certs/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"display_name": "test",
"policies": "",
"allowed_names": "",
"ttl": 2764800
},
"warnings": null,
"auth": null
}
```
</dd>
</dl>
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
Lists configured certificate names.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/cert/certs` (LIST) or `/auth/cert/certs?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"keys": ["cert1", "cert2"]
},
"warnings": null,
"auth": null
}
```
</dd>
</dl>
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Sets a CA cert and associated parameters in a role name.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/cert/certs/<name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">certificate</span>
<span class="param-flags">required</span>
The PEM-format CA certificate.
</li>
<li>
<span class="param">allowed_names</span>
<span class="param-flags">optional</span>
Constrain the Common and Alternative Names in the client certificate
with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example).
Value is a comma-separated list of patterns.
Authentication requires at least one Name matching at least one pattern.
If not set, defaults to allowing all names.
</li>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
A comma-separated list of policies to set on tokens issued when
authenticating against this CA certificate.
</li>
<li>
<span class="param">display_name</span>
<span class="param-flags">optional</span>
The `display_name` to set on tokens issued when authenticating
against this CA certificate. If not set, defaults to the name
of the role.
</li>
<li>
<span class="param">ttl</span>
<span class="param-flags">optional</span>
The TTL period of the token, provided as a number of seconds. If not
provided, the token is valid for the the mount or system default TTL
time, in that order.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
### /auth/cert/crls
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes the named CRL from the backend mount.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/cert/crls/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Gets information associated with the named CRL (currently, the serial
numbers contained within). As the serials can be integers up to an
arbitrary size, these are returned as strings.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/cert/crls/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"data": {
"serials": {
"13": {}
}
},
"lease_duration": 0,
"lease_id": "",
"renewable": false,
"warnings": null
}
```
</dd>
</dl>
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Sets a named CRL.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/cert/crls/<name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">crl</span>
<span class="param-flags">required</span>
The PEM-format CRL.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
### /auth/cert/login
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Log in and fetch a token. If there is a valid chain to a CA configured in
the backend and all role constraints are matched, a token will be issued.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/cert/login`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">name</span>
<span class="param-flags">optional</span>
Authenticate against only the named certificate role, returning its
policy list if successful. If not set, defaults to trying all
certificate roles and returning any one that matches.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": {
"client_token": "ABCD",
"policies": ["web", "stage"],
"lease_duration": 3600,
"renewable": true,
}
}
```
</dd>
</dl>
### /auth/cert/config
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Configuration options for the backend.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/cert/config`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">disable_binding</span>
<span class="param-flags">optional</span>
If set, during renewal, skips the matching of presented client identity with the client identity used during login. Defaults to false.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
The TLS Certificate authentication backend has a full HTTP API. Please see the
[TLS Certificate API](/api/auth/cert/index.html) for more details.

523
website/source/docs/auth/ldap.html.md
View File

@ -263,524 +263,7 @@ default, foobar, zoobar
It should be noted that user -> policy mapping happens at token creation time. And changes in group membership on the LDAP server will not affect tokens that have already been provisioned. To see these changes, old tokens should be revoked and the user should be asked to reauthenticate.
## API
### /auth/ldap/config
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Configures the LDAP authentication backend.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/ldap/config`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">url</span>
<span class="param-flags">required</span>
The LDAP server to connect to. Examples: `ldap://ldap.myorg.com`,
`ldaps://ldap.myorg.com:636`
</li>
</ul>
<ul>
<li>
<span class="param">starttls</span>
<span class="param-flags">optional</span>
If true, issues a `StartTLS` command after establishing an unencrypted
connection. Defaults to `false`.
</li>
</ul>
<ul>
<li>
<span class="param">tls_min_version</span>
<span class="param-flags">optional</span>
Minimum TLS version to use. Accepted values are `tls10`, `tls11` or
`tls12`. Defaults to `tls12`.
</li>
</ul>
<ul>
<li>
<span class="param">tls_max_version</span>
<span class="param-flags">optional</span>
Maximum TLS version to use. Accepted values are `tls10`, `tls11` or
`tls12`. Defaults to `tls12`.
</li>
</ul>
<ul>
<li>
<span class="param">insecure_tls</span>
<span class="param-flags">optional</span>
If true, skips LDAP server SSL certificate verification - insecure, use
with caution! Defaults to `false`.
</li>
</ul>
<ul>
<li>
<span class="param">certificate</span>
<span class="param-flags">optional</span>
CA certificate to use when verifying LDAP server certificate, must be
x509 PEM encoded.
</li>
</ul>
<ul>
<li>
<span class="param">binddn</span>
<span class="param-flags">optional</span>
Distinguished name of object to bind when performing user search.
Example: `cn=vault,ou=Users,dc=example,dc=com`
</li>
</ul>
<ul>
<li>
<span class="param">bindpass</span>
<span class="param-flags">optional</span>
Password to use along with `binddn` when performing user search.
</li>
</ul>
<ul>
<li>
<span class="param">userdn</span>
<span class="param-flags">optional</span>
Base DN under which to perform user search. Example:
`ou=Users,dc=example,dc=com`
</li>
</ul>
<ul>
<li>
<span class="param">userattr</span>
<span class="param-flags">optional</span>
Attribute on user attribute object matching the username passed when
authenticating. Examples: `sAMAccountName`, `cn`, `uid`
</li>
</ul>
<ul>
<li>
<span class="param">discoverdn</span>
<span class="param-flags">optional</span>
Use anonymous bind to discover the bind DN of a user. Defaults to
`false`.
</li>
</ul>
<ul>
<li>
<span class="param">deny_null_bind</span>
<span class="param-flags">optional</span>
This option prevents users from bypassing authentication when providing
an empty password. Defaults to `true`.
</li>
</ul>
<ul>
<li>
<span class="param">upndomain</span>
<span class="param-flags">optional</span>
userPrincipalDomain used to construct the UPN string for the
authenticating user. The constructed UPN will appear as
`[username]@UPNDomain`. Example: `example.com`, which will cause
vault to bind as `username@example.com`.
</li>
</ul>
<ul>
<li>
<span class="param">groupfilter</span>
<span class="param-flags">optional</span>
Go template used when constructing the group membership query. The
template can access the following context variables:
\[`UserDN`, `Username`\]. The default is `(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`,
which is compatible with several common directory schemas. To support
nested group resolution for Active Directory, instead use the following
query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`.
</li>
</ul>
<ul>
<li>
<span class="param">groupdn</span>
<span class="param-flags">optional</span>
LDAP search base to use for group membership search. This can be the
root containing either groups or users.
Example: `ou=Groups,dc=example,dc=com`
</li>
</ul>
<ul>
<li>
<span class="param">groupattr</span>
<span class="param-flags">optional</span>
LDAP attribute to follow on objects returned by `groupfilter` in order
to enumerate user group membership. Examples: for groupfilter queries
returning _group_ objects, use: `cn`. For queries returning _user_
objects, use: `memberOf`. The default is `cn`.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Retrieves the LDAP configuration.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/ldap/config`</dd>
<dt>Parameters</dt>
None.
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"binddn": "cn=vault,ou=Users,dc=example,dc=com",
"bindpass": "",
"certificate": "",
"deny_null_bind": true,
"discoverdn": false,
"groupattr": "cn",
"groupdn": "ou=Groups,dc=example,dc=com",
"groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))",
"insecure_tls": false,
"starttls": false,
"tls_max_version": "tls12",
"tls_min_version": "tls12",
"upndomain": "",
"url": "ldaps://ldap.myorg.com:636",
"userattr": "samaccountname",
"userdn": "ou=Users,dc=example,dc=com"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/ldap/groups
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
Lists the existing groups in the backend.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/ldap/groups` (LIST) or `/auth/ldap/groups?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"scientists",
"engineers"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/ldap/groups/[group_name]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates and updates the LDAP group policy associations.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/ldap/groups/[group_name]`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">policies</span>
<span class="param-flags">required</span>
Comma-separated list of policies associated to the group.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Reads the LDAP group policy mappings.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/ldap/groups/[group_name]`</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"policies": "admin,default"
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
```
</dd>
</dl>
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes an LDAP group.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/ldap/groups/[group_name]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/ldap/users
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
Lists the existing users in the backend.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/ldap/users` (LIST) or `/auth/ldap/users?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": [
"tesla"
]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
</dd>
</dl>
### /auth/ldap/users/[username]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates and updates the LDAP user group and policy mappings.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/ldap/users/[username]`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">groups</span>
<span class="param-flags">optional</span>
Comma-separated list of groups associated to the user.
</li>
</ul>
<ul>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
Comma-separated list of policies associated to the user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Reads the LDAP user.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/ldap/users/[username]`</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"policies": "admins,default",
"groups": ""
},
"renewable": false,
"lease_id": ""
"lease_duration": 0,
"warnings": null
}
```
</dd>
</dl>
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes an LDAP user.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/ldap/users/[username]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/ldap/login/[username]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates and updates the LDAP user group and policy associations.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/ldap/login/[username]`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">password</span>
<span class="param-flags">required</span>
Password for the user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"auth": {
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies": [
"admins",
"default"
],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 0,
"renewable": false
}
}
```
</dd>
</dl>
The LDAP authentication backend has a full HTTP API. Please see the
[LDAP auth backend API](/api/auth/ldap/index.html) for more
details.

257
website/source/docs/auth/radius.html.md
View File

@ -108,258 +108,7 @@ This is done through the `unregistered_user_policies` configuration parameter.
## API
### /auth/radius/config
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Configures the connection parameters and shard secret used to communicate with RADIUS
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/radius/config`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">host</span>
<span class="param-flags">required</span>
The RADIUS server to connect to. Examples: `radius.myorg.com`, `127.0.0.1`
</li>
<li>
<span class="param">port</span>
<span class="param-flags">optional</span>
The UDP port where the RADIUS server is listening on. Defaults is 1812
</li>
<li>
<span class="param">secret</span>
<span class="param-flags">required</span>
The RADIUS shared secret
</li>
<li>
<span class="param">unregistered_user_policies</span>
<span class="param-flags">optional</span>
A Comma-Separated list of policies to be granted to unregistered users
</li>
<li>
<span class="param">dial_timeout</span>
<span class="param-flags">optional</span>
Number of second to wait for a backend connection before timing out. Defaults is 10
</li>
<li>
<span class="param">read_timeout</span>
<span class="param-flags">optional</span>
Number of second to wait for a backend response before timing out. Defaults is 10
</li>
<li>
<span class="param">nas_port</span>
<span class="param-flags">optional</span>
The NAS-Port attribute of the RADIUS request. Defaults is 10
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/radius/users/[username]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Registers a new user and maps a set of policies to it.
This path honors the distinction between the `create` and `update` capabilities inside ACL policies.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/radius/users/<username>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">username</span>
<span class="param-flags">required</span>
Username for this user.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
Comma-separated list of policies.
If set to empty string, only the `default` policy will be applicable to the user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Reads the properties of an existing username.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/radius/users/[username]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"policies": "default,dev"
},
"warnings": null
}
```
</dd>
</dl>
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes an existing username from the backend.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/radius/users/[username]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/radius/login
### /auth/radius/login/[username]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Login with the username and password.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URLS</dt>
<dd>`/auth/radius/login`</dd>
<dd>`/auth/radius/login/[username]`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">username</span>
<span class="param-flags">required</span>
Username for the authenticating user.
</li>
<li>
<span class="param">password</span>
<span class="param-flags">required</span>
Password for the authenticating user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "vishal"
},
"lease_duration": 7200,
"renewable": true
}
}
```
</dd>
</dl>
### /auth/radius/users
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
List the users registered with the backend.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/radius/users` (LIST) `/auth/radius/users?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
[
"devuser",
"produser"
]
```
</dd>
</dl>
The RADIUS authentication backend has a full HTTP API. Please see the
[RADIUS Auth API](/api/auth/radius/index.html) for more
details.

813
website/source/docs/auth/token.html.md
View File

@ -26,823 +26,20 @@ to tokens.
## Authentication
#### Via the CLI
### Via the CLI
```
$ vault auth <token>
...
```
#### Via the API
### Via the API
The token is set directly as a header for the HTTP API. The name
of the header should be "X-Vault-Token" and the value should be the token.
## API
### /auth/token/accessors
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
Lists token accessors. This requires `sudo` capability, and access to it
should be tightly controlled as the accessors can be used to revoke very
large numbers of tokens and their associated leases at once.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/token/accessors` (LIST) or `/auth/token/accessors?list=true` (GET)<dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"keys": ["476ea048-ded5-4d07-eeea-938c6b4e43ec", "bb00c093-b7d3-b0e9-69cc-c4d85081165b"]
}
}
```
</dd>
</dl>
### /auth/token/create
### /auth/token/create-orphan
### /auth/token/create/[role_name]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates a new token. Certain options are only available when called by a
root token. If used via the `/auth/token/create-orphan` endpoint, a root
token is not required to create an orphan token (otherwise set with the
`no_parent` option). If used with a role name in the path, the token will
be created against the specified role name; this may override options set
during this call.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URLs</dt>
<dd>`/auth/token/create`</dd>
<dd>`/auth/token/create-orphan`</dd>
<dd>`/auth/token/create/<role_name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">id</span>
<span class="param-flags">optional</span>
The ID of the client token. Can only be specified by a root token.
Otherwise, the token ID is a randomly generated UUID.
</li>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
A list of policies for the token. This must be a subset of the
policies belonging to the token making the request, unless root.
If not specified, defaults to all the policies of the calling token.
</li>
<li>
<span class="param">meta</span>
<span class="param-flags">optional</span>
A map of string to string valued metadata. This is passed through
to the audit backends.
</li>
<li>
<span class="param">no_parent</span>
<span class="param-flags">optional</span>
If true and set by a root caller, the token will not have the
parent token of the caller. This creates a token with no parent.
</li>
<li>
<span class="param">no_default_policy</span>
<span class="param-flags">optional</span>
If true the `default` policy will not be contained in this token's
policy set.
</li>
<li>
<span class="param">renewable</span>
<span class="param-flags">optional</span>
Set to `false` to disable the ability of the token to be renewed past
its initial TTL. Specifying `true`, or omitting this option, will allow
the token to be renewable up to the system/mount maximum TTL.
</li>
<li>
<span class="param">lease</span>
<span class="param-flags">optional</span>
DEPRECATED; use "ttl" instead.
</li>
<li>
<span class="param">ttl</span>
<span class="param-flags">optional</span>
The TTL period of the token, provided as "1h", where hour is
the largest suffix. If not provided, the token is valid for the
[default lease TTL](/docs/configuration/index.html), or
indefinitely if the root policy is used.
</li>
<li>
<span class="param">explicit_max_ttl</span>
<span class="param-flags">optional</span>
If set, the token will have an explicit max TTL set upon it. This
maximum token TTL *cannot* be changed later, and unlike with normal
tokens, updates to the system/mount max TTL value will have no effect
at renewal time -- the token will never be able to be renewed or used
past the value set at issue time.
</li>
<li>
<span class="param">display_name</span>
<span class="param-flags">optional</span>
The display name of the token. Defaults to "token".
</li>
<li>
<span class="param">num_uses</span>
<span class="param-flags">optional</span>
The maximum uses for the given token. This can be used to create
a one-time-token or limited use token. Defaults to 0, which has
no limit to the number of uses.
</li>
<li>
<span class="param">period</span>
<span class="param-flags">optional</span>
If specified, the token will be periodic; it will have no maximum TTL
(unless an "explicit-max-ttl" is also set) but every renewal will use
the given period. Requires a root/sudo token to use.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": {
"client_token": "ABCD",
"policies": ["web", "stage"],
"metadata": {"user": "armon"},
"lease_duration": 3600,
"renewable": true,
}
}
```
</dd>
</dl>
### /auth/token/lookup[/token]
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Returns information about the client token provided in the request path.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/token/lookup/<token>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"id": "ClientToken",
"policies": ["web", "stage"],
"path": "auth/github/login",
"meta": {"user": "armon", "organization": "hashicorp"},
"display_name": "github-armon",
"num_uses": 0,
}
}
```
</dd>
</dl>
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Returns information about the client token provided in the request body.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/lookup`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">token</span>
<span class="param-flags">required</span>
Token to lookup.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"id": "ClientToken",
"policies": ["web", "stage"],
"path": "auth/github/login",
"meta": {"user": "armon", "organization": "hashicorp"},
"display_name": "github-armon",
"num_uses": 0,
}
}
```
</dd>
</dl>
### /auth/token/lookup-accessor[/accessor]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Fetch the properties of the token associated with the accessor, except the token ID.
This is meant for purposes where there is no access to token ID but there is need
to fetch the properties of a token.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/lookup-accessor</accessor>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">accessor</span>
<span class="param-flags">required</span>
Accessor of the token to lookup. This can be part of the URL or the body.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"creation_time": 1457533232,
"creation_ttl": 2764800,
"display_name": "token",
"id": "",
"meta": null,
"num_uses": 0,
"orphan": false,
"path": "auth/token/create",
"policies": ["default", "web"],
"ttl": 2591976
},
"warnings": null,
"auth": null
}
```
</dd>
</dl>
### /auth/token/lookup-self
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Returns information about the current client token.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"accessor": "REDACTED",
"creation_time": 1484093665,
"creation_ttl": 3600,
"display_name": "github-armon",
"explicit_max_ttl": 0,
"id": "ClientToken",
"meta": {"user": "armon", "organization": "hashicorp"},
"num_uses": 0,
"orphan": true,
"path": "auth/github/login",
"policies": ["web", "stage"],
"renewable": true,
"ttl": 3655
}
}
```
</dd>
</dl>
### /auth/token/renew[/token]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Renews a lease associated with a token. This is used to prevent the
expiration of a token, and the automatic revocation of it. Token
renewal is possible only if there is a lease associated with it.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/renew</token>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">token</span>
<span class="param-flags">required</span>
Token to renew. This can be part of the URL or the body.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">increment</span>
<span class="param-flags">optional</span>
An optional requested lease increment can be provided. This
increment may be ignored.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": {
"client_token": "ABCD",
"policies": ["web", "stage"],
"metadata": {"user": "armon"},
"lease_duration": 3600,
"renewable": true,
}
}
```
</dd>
</dl>
### /auth/token/renew-self
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Renews a lease associated with the calling token. This is used to prevent
the expiration of a token, and the automatic revocation of it. Token
renewal is possible only if there is a lease associated with it.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/renew-self`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">increment</span>
<span class="param-flags">optional</span>
An optional requested lease increment can be provided. This
increment may be ignored.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"auth": {
"client_token": "ABCD",
"policies": ["web", "stage"],
"metadata": {"user": "armon"},
"lease_duration": 3600,
"renewable": true,
}
}
```
</dd>
</dl>
### /auth/token/revoke
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Revokes a token and all child tokens. When the token is revoked,
all secrets generated with it are also revoked.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/revoke`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">token</span>
<span class="param-flags">required</span>
Token to revoke.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/token/revoke-accessor
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Revoke the token associated with the accessor and all the child tokens.
This is meant for purposes where there is no access to token ID but
there is need to revoke a token and its children.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/revoke-accessor`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">accessor</span>
<span class="param-flags">required</span>
Accessor of the token.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
### /auth/token/revoke-orphan[/token]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Revokes a token but not its child tokens. When the token is revoked, all
secrets generated with it are also revoked. All child tokens are orphaned,
but can be revoked sub-sequently using `/auth/token/revoke/`. This is a
root-protected endpoint.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/revoke-orphan</token>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">token</span>
<span class="param-flags">required</span>
Token to revoke. This can be part of the URL or the body.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/token/revoke-self/
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Revokes the token used to call it and all child tokens.
When the token is revoked, all dynamic secrets generated
with it are also revoked.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/revoke-self`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/token/roles/[role_name]
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes the named role.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/token/roles/<role_name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Fetches the named role configuration.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/token/roles/<role_name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"request_id": "075a19cd-4e56-a3ca-d956-7609819831ec",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"allowed_policies": [
"dev"
],
"disallowed_policies": [],
"explicit_max_ttl": 0,
"name": "nomad",
"orphan": false,
"path_suffix": "",
"period": 0,
"renewable": true
},
"warnings": null
}
```
</dd>
</dl>
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
Lists available roles.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/token/roles` (LIST) or `/auth/token/roles?list=true` (GET)<dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"keys": ["role1", "role2"]
}
}
```
</dd>
</dl>
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates (or replaces) the named role. Roles enforce specific behavior when
creating tokens that allow token functionality that is otherwise not
available or would require `sudo`/root privileges to access. Role
parameters, when set, override any provided options to the `create`
endpoints. The role name is also included in the token path, allowing all
tokens created against a role to be revoked using the `sys/revoke-prefix`
endpoint.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/roles/<role_name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">allowed_policies</span>
<span class="param-flags">optional</span>
If set, tokens can be created with any subset of the policies in this
list, rather than the normal semantics of tokens being a subset of the
calling token's policies. The parameter is a comma-delimited string of
policy names. If at creation time `no_default_policy` is not set and
`"default"` is not contained in `disallowed_policies`, the `"default"`
policy will be added to the created token automatically.
</li>
<li>
<span class="param">disallowed_policies</span>
<span class="param-flags">optional</span>
If set, successful token creation via this role will require that no
policies in the given list are requested. The parameter is a
comma-delimited string of policy names. Adding `"default"` to this list
will prevent `"default"` from being added automatically to created
tokens.
</li>
<li>
<span class="param">orphan</span>
<span class="param-flags">optional</span>
If `true`, tokens created against this policy will be orphan tokens
(they will have no parent). As such, they will not be automatically
revoked by the revocation of any other token.
</li>
<li>
<span class="param">period</span>
<span class="param-flags">optional</span>
If set, tokens created against this role will <i>not</i> have a maximum
lifetime. Instead, they will have a fixed TTL that is refreshed with
each renewal. So long as they continue to be renewed, they will never
expire. The parameter is an integer duration of seconds. Tokens issued
track updates to the role value; the new period takes effect upon next
renew. This cannot be used in conjunction with `explicit_max_ttl`.
</li>
<li>
<span class="param">renewable</span>
<span class="param-flags">optional</span>
Set to `false` to disable the ability of token created against this
role to be renewed past their initial TTL. Defaults to `true`, which
allows tokens to be renewed up to the system/mount maximum TTL.
</li>
<li>
<span class="param">path_suffix</span>
<span class="param-flags">optional</span>
If set, tokens created against this role will have the given suffix as
part of their path in addition to the role name. This can be useful in
certain scenarios, such as keeping the same role name in the future but
revoking all tokens created against it before some point in time. The
suffix can be changed, allowing new callers to have the new suffix as
part of their path, and then tokens with the old suffix can be revoked
via `sys/revoke-prefix`.
</li>
<li>
<span class="param">explicit_max_ttl</span>
<span class="param-flags">optional</span>
If set, tokens created with this role have an explicit max TTL set upon
them. This maximum token TTL *cannot* be changed later, and unlike with
normal tokens, updates to the role or the system/mount max TTL value
will have no effect at renewal time -- the token will never be able to
be renewed or used past the value set at issue time. This cannot be
used in conjunction with `period`.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` return code.
</dd>
</dl>
### /auth/token/tidy
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Performs some maintenance tasks to clean up invalid entries that may remain
in the token store. Generally, running this is not needed unless upgrade
notes or support personnel suggest it. This may perform a lot of I/O to the
storage backend so should be used sparingly.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/token/tidy`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
The Token authentication backend has a full HTTP API. Please see the
[Token auth backend API](/api/auth/token/index.html) for more
details.

302
website/source/docs/auth/userpass.html.md
View File

@ -98,303 +98,7 @@ necessary.
## API
### /auth/userpass/users/[username]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Create a new user or update an existing user.
This path honors the distinction between the `create` and `update` capabilities inside ACL policies.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/userpass/users/<username>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">username</span>
<span class="param-flags">required</span>
Username for this user.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">password</span>
<span class="param-flags">required</span>
Password for this user.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
Comma-separated list of policies.
If set to empty string, only the `default` policy will be applicable to the user.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">ttl</span>
<span class="param-flags">optional</span>
The lease duration which decides login expiration.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">max_ttl</span>
<span class="param-flags">optional</span>
Maximum duration after which login should expire.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Reads the properties of an existing username.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/auth/userpass/users/[username]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"max_ttl": 0,
"policies": "default,dev",
"ttl": 0
},
"warnings": null
}
```
</dd>
</dl>
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes an existing username from the backend.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/auth/userpass/users/[username]`</dd>
<dt>Parameters</dt>
<dd>
None.
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/userpass/users/[username]/password
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Update the password for an existing user.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/userpass/users/<username>/password`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">username</span>
<span class="param-flags">required</span>
Username for this user.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">password</span>
<span class="param-flags">required</span>
Password for this user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/userpass/users/[username]/policies
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Update the policies associated with an existing user.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/userpass/users/<username>/policies`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">username</span>
<span class="param-flags">required</span>
Username for this user.
</li>
</ul>
</dd>
<dd>
<ul>
<li>
<span class="param">policies</span>
<span class="param-flags">optional</span>
Comma-separated list of policies.
If this is field is not supplied, the policies will be unchanged.
If set to empty string, only the `default` policy will be applicable to the user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>`204` response code.
</dd>
</dl>
### /auth/userpass/login/[username]
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Login with the username and password.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/auth/userpass/login/<username>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">password</span>
<span class="param-flags">required</span>
Password for this user.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"warnings": null,
"auth": {
"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
"policies": ["default"],
"metadata": {
"username": "vishal"
},
"lease_duration": 7200,
"renewable": true
}
}
```
</dd>
</dl>
### /auth/userpass/users
#### LIST
<dl class="api">
<dt>Description</dt>
<dd>
List the users registered with the backend.
</dd>
<dt>Method</dt>
<dd>LIST/GET</dd>
<dt>URL</dt>
<dd>`/auth/userpass/users` (LIST) `/auth/userpass/users?list=true` (GET)</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
[
"devuser",
"produser"
]
```
</dd>
</dl>
The Username & Password authentication backend has a full HTTP API. Please see the
[Userpass auth backend API](/api/auth/userpass/index.html) for more
details.

81
website/source/layouts/api.erb
View File

@ -10,19 +10,12 @@
<hr>
<!-- <li<%= sidebar_current("docs-http-auth") %>>
<a href="#">Auth Backends</a>
</li> -->
<li<%= sidebar_current("docs-http-secret") %>>
<a href="/api/secret/index.html">Secret Backends</a>
<ul class="nav">
<li<%= sidebar_current("docs-http-secret-aws") %>>
<a href="/api/secret/aws/index.html">AWS</a>
</li>
<li<%= sidebar_current("docs-http-secret-cassandra") %>>
<a href="/api/secret/cassandra/index.html">Cassandra (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-consul") %>>
<a href="/api/secret/consul/index.html">Consul</a>
</li>
@ -31,7 +24,7 @@
</li>
<li<%= sidebar_current("docs-http-secret-databases") %>>
<a href="/api/secret/databases/index.html">Databases (Beta)</a>
<a href="/api/secret/databases/index.html">Databases</a>
<ul class="nav">
<li<%= sidebar_current("docs-http-secret-databases-cassandra") %>>
<a href="/api/secret/databases/cassandra.html">Cassandra</a>
@ -57,21 +50,9 @@
<li<%= sidebar_current("docs-http-secret-identity") %>>
<a href="/api/secret/identity/index.html">Identity</a>
</li>
<li<%= sidebar_current("docs-http-secret-mongodb") %>>
<a href="/api/secret/mongodb/index.html">MongoDB (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-mssql") %>>
<a href="/api/secret/mssql/index.html">MSSQL (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-mysql") %>>
<a href="/api/secret/mysql/index.html">MySQL (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-pki") %>>
<a href="/api/secret/pki/index.html">PKI</a>
</li>
<li<%= sidebar_current("docs-http-secret-postgresql") %>>
<a href="/api/secret/postgresql/index.html">PostgreSQL (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-rabbitmq") %>>
<a href="/api/secret/rabbitmq/index.html">RabbitMQ</a>
</li>
@ -84,6 +65,66 @@
<li<%= sidebar_current("docs-http-secret-transit") %>>
<a href="/api/secret/transit/index.html">Transit</a>
</li>
<hr>
<li<%= sidebar_current("docs-http-secret-cassandra") %>>
<a href="/api/secret/cassandra/index.html">Cassandra <sup>DEPRECATED</sup></a>
</li>
<li<%= sidebar_current("docs-http-secret-mongodb") %>>
<a href="/api/secret/mongodb/index.html">MongoDB <sup>DEPRECATED</sup></a>
</li>
<li<%= sidebar_current("docs-http-secret-mssql") %>>
<a href="/api/secret/mssql/index.html">MSSQL <sup>DEPRECATED</sup></a>
</li>
<li<%= sidebar_current("docs-http-secret-mysql") %>>
<a href="/api/secret/mysql/index.html">MySQL <sup>DEPRECATED</sup></a>
</li>
<li<%= sidebar_current("docs-http-secret-postgresql") %>>
<a href="/api/secret/postgresql/index.html">PostgreSQL <sup>DEPRECATED</sup></a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-auth") %>>
<a href="/api/auth/index.html">Auth Backends</a>
<ul class="nav">
<li<%= sidebar_current("docs-http-auth-approle") %>>
<a href="/api/auth/approle/index.html">AppRole</a>
</li>
<li<%= sidebar_current("docs-http-auth-aws") %>>
<a href="/api/auth/aws/index.html">AWS</a>
</li>
<li<%= sidebar_current("docs-http-auth-github") %>>
<a href="/api/auth/github/index.html">Github</a>
</li>
<li<%= sidebar_current("docs-http-auth-ldap") %>>
<a href="/api/auth/ldap/index.html">LDAP</a>
</li>
<li<%= sidebar_current("docs-http-auth-mfa") %>>
<a href="/api/auth/mfa/index.html">MFA</a>
</li>
<li<%= sidebar_current("docs-http-auth-okta") %>>
<a href="/api/auth/okta/index.html">Okta</a>
</li>
<li<%= sidebar_current("docs-http-auth-radius") %>>
<a href="/api/auth/radius/index.html">RADIUS</a>
</li>
<li<%= sidebar_current("docs-http-auth-cert") %>>
<a href="/api/auth/cert/index.html">TLS Certificates</a>
</li>
<li<%= sidebar_current("docs-http-auth-token") %>>
<a href="/api/auth/token/index.html">Tokens</a>
</li>
<li<%= sidebar_current("docs-http-auth-userpass") %>>
<a href="/api/auth/userpass/index.html">Username & Password</a>
</li>
<hr>
<li<%= sidebar_current("docs-http-auth-appid") %>>
<a href="/api/auth/app-id/index.html">App ID <sup>DEPRECATED</sup></a>
</li>
</ul>
</li>

13
website/source/layouts/docs.erb
View File

@ -184,7 +184,7 @@
</li>
<li<%= sidebar_current("docs-secrets-databases") %>>
<a href="/docs/secrets/databases/index.html">Databases <sup>BETA</sup></a>
<a href="/docs/secrets/databases/index.html">Databases</a>
<ul class="nav">
<li<%= sidebar_current("docs-secrets-databases-cassandra") %>>
<a href="/docs/secrets/databases/cassandra.html">Cassandra</a>
@ -266,10 +266,6 @@
<li<%= sidebar_current("docs-auth") %>>
<a href="/docs/auth/index.html">Auth Backends</a>
<ul class="nav">
<li<%= sidebar_current("docs-auth-appid") %>>
<a href="/docs/auth/app-id.html">App ID</a>
</li>
<li<%= sidebar_current("docs-auth-approle") %>>
<a href="/docs/auth/approle.html">AppRole</a>
</li>
@ -309,6 +305,13 @@
<li<%= sidebar_current("docs-auth-userpass") %>>
<a href="/docs/auth/userpass.html">Username &amp; Password</a>
</li>
<hr>
<li<%= sidebar_current("docs-auth-appid") %>>
<a href="/docs/auth/app-id.html">App ID <sup>DEPRECATED</sup></a>
</li>
</ul>
</li>