website: documenting token API
This commit is contained in:
Armon Dadgar
parent
a2bd832519
commit
23ab2f6b9d
|
|
@ -9,7 +9,7 @@ description: |-
|
||||||
# Auth Backend: Token
|
# Auth Backend: Token
|
||||||
|
|
||||||
The token backend is the only auth backend that is built-in and
|
The token backend is the only auth backend that is built-in and
|
||||||
automatically available at `auth/token` as well as with first-class
|
automatically available at `/auth/token` as well as with first-class
|
||||||
built-in CLI methods such as `vault token-create`. It allows users to
|
built-in CLI methods such as `vault token-create`. It allows users to
|
||||||
authenticate using a token, as well to create new tokens, revoke
|
authenticate using a token, as well to create new tokens, revoke
|
||||||
secrets by token, and more.
|
secrets by token, and more.
|
||||||
|
|
@ -35,9 +35,287 @@ $ vault auth <token>
|
||||||
|
|
||||||
#### Via the API
|
#### Via the API
|
||||||
|
|
||||||
The token is set directly as a cookie for the HTTP API. See the
|
The token is set directly as a cookie for the HTTP API. The name
|
||||||
[HTTP API](/docs/http/index.html) documentation for more information.
|
of the cookie should be "token" and the value should be the token.
|
||||||
|
|
||||||
## API
|
## API
|
||||||
|
|
||||||
For API documentation on the token store, see `vault help auth/token`.
|
## /auth/token/create
|
||||||
|
### POST
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<dt>Description</dt>
|
||||||
|
<dd>
|
||||||
|
Creates a new token. Certain options are only available to
|
||||||
|
when called by a root token.
|
||||||
|
</dd>
|
||||||
|
|
||||||
|
<dt>Method</dt>
|
||||||
|
<dd>POST</dd>
|
||||||
|
|
||||||
|
<dt>URL</dt>
|
||||||
|
<dd>`/auth/token/create`</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">metadata</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">lease</span>
|
||||||
|
<span class="param-flags">optional</span>
|
||||||
|
The lease period of the token, provided as "1h", where hour is
|
||||||
|
the largest suffix. If not provided, the token is valid indefinitely.
|
||||||
|
</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 number of uses.
|
||||||
|
</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-self
|
||||||
|
### GET
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<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": {
|
||||||
|
"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/
|
||||||
|
### GET
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<dt>Description</dt>
|
||||||
|
<dd>
|
||||||
|
Returns information about the current client token.
|
||||||
|
</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>
|
||||||
|
|
||||||
|
|
||||||
|
## /auth/token/revoke/
|
||||||
|
### POST
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<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/<token>`</dd>
|
||||||
|
|
||||||
|
<dt>Parameters</dt>
|
||||||
|
<dd>
|
||||||
|
None
|
||||||
|
</dd>
|
||||||
|
|
||||||
|
<dt>Returns</dt>
|
||||||
|
<dd>`204` response code.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
|
||||||
|
## /auth/token/revoke-orphan/
|
||||||
|
### POST
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<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 orpahaned, but can be revoked sub-sequently using `/auth/token/revoke/`.
|
||||||
|
</dd>
|
||||||
|
|
||||||
|
<dt>Method</dt>
|
||||||
|
<dd>POST</dd>
|
||||||
|
|
||||||
|
<dt>URL</dt>
|
||||||
|
<dd>`/auth/token/revoke-orphan/<token>`</dd>
|
||||||
|
|
||||||
|
<dt>Parameters</dt>
|
||||||
|
<dd>
|
||||||
|
None
|
||||||
|
</dd>
|
||||||
|
|
||||||
|
<dt>Returns</dt>
|
||||||
|
<dd>`204` response code.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
|
||||||
|
## /auth/token/revoke-prefix/
|
||||||
|
### POST
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<dt>Description</dt>
|
||||||
|
<dd>
|
||||||
|
Revokes all tokens generated at a given prefix, along with child tokens,
|
||||||
|
and all secrets generated using those tokens. Uses include revoking all
|
||||||
|
tokens generated by a credential backend during a suspected compromise.
|
||||||
|
</dd>
|
||||||
|
|
||||||
|
<dt>Method</dt>
|
||||||
|
<dd>POST</dd>
|
||||||
|
|
||||||
|
<dt>URL</dt>
|
||||||
|
<dd>`/auth/token/revoke-prefix/<prefix>`</dd>
|
||||||
|
|
||||||
|
<dt>Parameters</dt>
|
||||||
|
<dd>
|
||||||
|
None
|
||||||
|
</dd>
|
||||||
|
|
||||||
|
<dt>Returns</dt>
|
||||||
|
<dd>`204` response code.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
|
||||||
|
## /auth/token/renew/
|
||||||
|
### POST
|
||||||
|
|
||||||
|
<dl>
|
||||||
|
<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.
|
||||||
|
</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">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>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -128,7 +128,7 @@
|
||||||
<a href="/docs/auth/index.html">Auth Backends</a>
|
<a href="/docs/auth/index.html">Auth Backends</a>
|
||||||
<ul class="nav">
|
<ul class="nav">
|
||||||
<li<%= sidebar_current("docs-auth-token") %>>
|
<li<%= sidebar_current("docs-auth-token") %>>
|
||||||
<a href="/docs/auth/token.html">Tokens</a>
|
<a href="/docs/auth/token.html">Tokens</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("docs-auth-github") %>>
|
<li<%= sidebar_current("docs-auth-github") %>>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue