415 lines
9 KiB
Markdown
415 lines
9 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Auth Backend: Token"
|
|
sidebar_current: "docs-auth-token"
|
|
description: |-
|
|
The token store auth backend is used to authenticate using tokens.
|
|
---
|
|
|
|
# Auth Backend: Token
|
|
|
|
The token backend is the only auth backend that is built-in and
|
|
automatically available at `/auth/token` as well as with first-class
|
|
built-in CLI methods such as `vault token-create`. It allows users to
|
|
authenticate using a token, as well to create new tokens, revoke
|
|
secrets by token, and more.
|
|
|
|
When any other auth backend returns an identity, Vault core invokes the
|
|
token backend to create a new unique token for that identity.
|
|
|
|
The token store can also be used to bypass any other auth backend:
|
|
you can create tokens directly, as well as perform a variety of other
|
|
operations on tokens such as renewal and revocation.
|
|
|
|
Please see the [token concepts](/docs/concepts/tokens.html) page dedicated
|
|
to tokens.
|
|
|
|
## Authentication
|
|
|
|
#### Via the CLI
|
|
|
|
```
|
|
$ vault auth <token>
|
|
...
|
|
```
|
|
|
|
#### 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/create[-orphan]
|
|
#### POST
|
|
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Creates a new token. Certain options are only available to
|
|
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).
|
|
</dd>
|
|
|
|
<dt>Method</dt>
|
|
<dd>POST</dd>
|
|
|
|
<dt>URL</dt>
|
|
<dd>`/auth/token/create[-orphan]`</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_profile</span>
|
|
<span class="param-flags">optional</span>
|
|
If true the `default` profile will not be a part of this token's
|
|
policy set.
|
|
</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/config/index.html), or
|
|
indefinitely if the root policy is used.
|
|
</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 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": {
|
|
"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 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>
|
|
|
|
|
|
### /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/<token>`</dd>
|
|
|
|
<dt>Parameters</dt>
|
|
<dd>
|
|
None
|
|
</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 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/revoke-orphan/
|
|
#### 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/`.
|
|
</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 class="api">
|
|
<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-self
|
|
#### POST
|
|
|
|
<dl class="api">
|
|
<dt>Description</dt>
|
|
<dd>
|
|
Renews a lease associated with the callign 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/renew/
|
|
#### 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">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>
|
|
|