Skip to content

Latest commit

 

History

History
746 lines (621 loc) · 16.4 KB

token.html.md

File metadata and controls

746 lines (621 loc) · 16.4 KB
Raw
layout page_title sidebar_current description
docs
Auth Backend: Token
docs-auth-token
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 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

/auth/token/create-orphan

/auth/token/create/[role_name]

POST

Description
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
POST
URLs
`/auth/token/create`
`/auth/token/create-orphan`
`/auth/token/create/`
Parameters
  • id optional The ID of the client token. Can only be specified by a root token. Otherwise, the token ID is a randomly generated UUID.
  • policies optional 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 optional A map of string to string valued metadata. This is passed through to the audit backends.
  • no_parent optional 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 optional If true the `default` policy will not be a part of this token's policy set.
  • lease optional DEPRECATED; use "ttl" instead.
  • ttl optional 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.
  • display_name optional The display name of the token. Defaults to "token".
  • num_uses optional 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.
Returns
```javascript
{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {"user": "armon"},
    "lease_duration": 3600,
    "renewable": true,
  }
}
```

/auth/token/lookup-self

GET

Description
Returns information about the current client token.
Method
GET
Parameters
None
Returns
```javascript
{
  "data": {
    "id": "ClientToken",
    "policies": ["web", "stage"],
    "path": "auth/github/login",
    "meta": {"user": "armon", "organization": "hashicorp"},
    "display_name": "github-armon",
    "num_uses": 0,
  }
}
```

/auth/token/lookup[/token]

GET

Description
Returns information about the client token provided in the request path.
Method
GET
URL
`/auth/token/lookup/`
Parameters
None
Returns
```javascript
{
  "data": {
    "id": "ClientToken",
    "policies": ["web", "stage"],
    "path": "auth/github/login",
    "meta": {"user": "armon", "organization": "hashicorp"},
    "display_name": "github-armon",
    "num_uses": 0,
  }
}
```

POST

Description
Returns information about the client token provided in the request body.
Method
GET
URL
`/auth/token/lookup`
Parameters
  • token required Token to lookup.
Returns
```javascript
{
  "data": {
    "id": "ClientToken",
    "policies": ["web", "stage"],
    "path": "auth/github/login",
    "meta": {"user": "armon", "organization": "hashicorp"},
    "display_name": "github-armon",
    "num_uses": 0,
  }
}
```

/auth/token/renew-self

POST

Description
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
POST
URL
`/auth/token/renew-self`
Parameters
  • increment optional An optional requested lease increment can be provided. This increment may be ignored.
Returns
```javascript
{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {"user": "armon"},
    "lease_duration": 3600,
    "renewable": true,
  }
}
```

/auth/token/renew[/token]

POST

Description
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
POST
URL
`/auth/token/renew`
Parameters
  • token required Token to revoke. This can be part of the URL or the body.
  • increment optional An optional requested lease increment can be provided. This increment may be ignored.
Returns
```javascript
{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {"user": "armon"},
    "lease_duration": 3600,
    "renewable": true,
  }
}
```

/auth/token/revoke[/token]

POST

Description
Revokes a token and all child tokens. When the token is revoked, all secrets generated with it are also revoked.
Method
POST
URL
`/auth/token/revoke`
Parameters
  • token required Token to revoke. This can be part of the URL or the body.
Returns
`204` response code.

/auth/token/revoke-self/

POST

Description
Revokes the token used to call it and all child tokens. When the token is revoked, all secrets generated with it are also revoked.
Method
POST
URL
`/auth/token/revoke-self`
Parameters
None
Returns
`204` response code.

/auth/token/revoke-orphan[/token]

POST

Description
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
POST
URL
`/auth/token/revoke-orphan`
Parameters
  • token required Token to revoke. This can be part of the URL or the body.
Returns
`204` response code.

/auth/token/revoke-prefix[/prefix]

POST

Description
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. This is a root-protected endpoint.
Method
POST
URL
`/auth/token/revoke-prefix`
Parameters
  • token required Token source prefix to revoke. This can be part of the URL or the body.
Returns
`204` response code.

/auth/token/roles/[role_name]

DELETE

Description
Deletes the named role.
Method
GET
URL
`/auth/token/roles/`
Parameters
None
Returns
A `204` response code.

GET

Description
Fetches the named role configuration.
Method
GET
URL
`/auth/token/roles/`
Parameters
None
Returns
```javascript
{
  "data": {
    "period": 3600,
    "allowed_policies": ["web", "stage"],
    "orphan": true,
    "path_suffix": ""
  }
}
```

LIST

Description
Lists available roles.
Method
GET
URL
`/auth/token/roles?list=true`
Parameters
None
Returns
```javascript
{
  "data": {
    "keys": ["role1", "role2"]
  }
}
```

POST

Description
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 `revoke-prefix` endpoint.
Method
POST
URL
`/auth/token/roles/`
Parameters
  • allowed_policies optional 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.
  • orphan optional 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 optional If set, tokens created against this role will not 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 or a duration string (e.g. `"72h"`).
  • path_suffix optional 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 `revoke-prefix`.
Returns
A `204` return code.

/auth/token/lookup-accessor[/accessor]

POST

Description
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.
Method
POST
URL
`/auth/token/lookup-accessor`
Parameters
  • accessor required Accessor of the token to lookup. This can be part of the URL or the body.
Returns
```javascript

{ "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "creation_time": 1457533232, "creation_ttl": 2592000, "display_name": "token", "id": "", "meta": null, "num_uses": 0, "orphan": false, "path": "auth/token/create", "policies": ["default", "web"], "ttl": 2591976 }, "warnings": null, "auth": null } ```

/auth/token/revoke-accessor[/accessor]

POST

Description
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
POST
URL
`/auth/token/revoke-accessor`
Parameters
  • accessor required Accessor of the token. This can be part of the URL or the body.
Returns
`204` response code.