luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/source/docs/auth/token.html.md
Seth Vargo 6931bbd091
Links
2017-03-17 14:27:32 -04:00

20 KiB
Raw Blame History

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/accessors

LIST

Description
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.
Method
LIST/GET
URL
`/auth/token/accessors` (LIST) or `/auth/token/accessors?list=true` (GET)
Parameters
None
Returns
```javascript
{
  "data": {
    "keys": ["476ea048-ded5-4d07-eeea-938c6b4e43ec", "bb00c093-b7d3-b0e9-69cc-c4d85081165b"]
  }
}
```

/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 contained in this token's policy set.
  • renewable optional 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.
  • 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/configuration/index.html), or indefinitely if the root policy is used.
  • explicit_max_ttl optional 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 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.
  • period optional 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.
Returns
```javascript
{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {"user": "armon"},
    "lease_duration": 3600,
    "renewable": true,
  }
}
```

/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
POST
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/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": 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
}
```

/auth/token/lookup-self

GET

Description
Returns information about the current client token.
Method
GET
Parameters
None
Returns
```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
  }
}
```

/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 renew. 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/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/revoke

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.
Returns
`204` response code.

/auth/token/revoke-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.
Returns
A `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-self/

POST

Description
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
POST
URL
`/auth/token/revoke-self`
Parameters
None
Returns
`204` response code.

/auth/token/roles/[role_name]

DELETE

Description
Deletes the named role.
Method
DELETE
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

{ "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

Description
Lists available roles.
Method
LIST/GET
URL
`/auth/token/roles` (LIST) or `/auth/token/roles?list=true` (GET)
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 `sys/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. 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 optional 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 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. 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`.
  • renewable optional 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.
  • 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 `sys/revoke-prefix`.
  • explicit_max_ttl optional 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`.
Returns
A `204` return code.

/auth/token/tidy

POST

Description
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
POST
URL
`/auth/token/tidy`
Parameters
None
Returns
`204` response code.