From 6e8033b5bd44c79d99f35a375e7b60008a02e55d Mon Sep 17 00:00:00 2001 From: Jeff Mitchell Date: Tue, 1 Mar 2016 14:00:52 -0500 Subject: [PATCH] Update token documentation --- website/source/docs/auth/token.html.md | 282 ++++++++++++++++++++----- 1 file changed, 227 insertions(+), 55 deletions(-) diff --git a/website/source/docs/auth/token.html.md b/website/source/docs/auth/token.html.md index 0f7df70ab9..c8050592cb 100644 --- a/website/source/docs/auth/token.html.md +++ b/website/source/docs/auth/token.html.md @@ -40,24 +40,29 @@ of the header should be "X-Vault-Token" and the value should be the token. ## API -### /auth/token/create[-orphan] +### /auth/token/create +### /auth/token/create-orphan +### /auth/token/create/[role_name] #### POST
Description
- 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). + 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
-
URL
-
`/auth/token/create[-orphan]`
+
URLs
+
`/auth/token/create`
+
`/auth/token/create-orphan`
+
`/auth/token/create/`
Parameters
@@ -116,7 +121,7 @@ of the header should be "X-Vault-Token" and the value should be the token. 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 number of uses. + no limit to the number of uses.
@@ -124,7 +129,7 @@ of the header should be "X-Vault-Token" and the value should be the token.
Returns
- ```javascript + ```javascript { "auth": { "client_token": "ABCD", @@ -209,9 +214,103 @@ of the header should be "X-Vault-Token" and the value should be the token. } } ``` +
+### /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/ +#### 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
+
+
    +
  • + 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 @@ -272,9 +371,10 @@ of the header should be "X-Vault-Token" and the value should be the token.
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/`. + 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
@@ -302,6 +402,7 @@ of the header should be "X-Vault-Token" and the value should be the token. 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
@@ -320,33 +421,50 @@ of the header should be "X-Vault-Token" and the value should be the token.
-### /auth/token/renew-self -#### POST +### /auth/token/roles/[role_name] + +#### DELETE
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. + Deletes the named role.
Method
-
POST
+
GET
URL
-
`/auth/token/renew-self`
+
`/auth/token/roles/`
Parameters
-
    -
  • - increment - optional - An optional requested lease increment can be provided. This - increment may be ignored. -
    • -
+ None +
+ +
Returns
+
+ A `204` response code. +
+
+ +#### GET + +
+
Description
+
+ Fetches the named role configuration. +
+ +
Method
+
GET
+ +
URL
+
`/auth/token/roles/`
+ +
Parameters
+
+ None
Returns
@@ -354,45 +472,35 @@ of the header should be "X-Vault-Token" and the value should be the token. ```javascript { - "auth": { - "client_token": "ABCD", - "policies": ["web", "stage"], - "metadata": {"user": "armon"}, - "lease_duration": 3600, - "renewable": true, + "data": { + "period": 3600, + "allowed_policies": ["web", "stage"], + "orphan": true, + "prefix": "" } } ``` +
-### /auth/token/renew/ -#### POST +#### LIST
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. + Lists available roles.
Method
-
POST
+
GET
URL
-
`/auth/token/renew/`
+
`/auth/token/roles?list=true`
Parameters
-
    -
  • - increment - optional - An optional requested lease increment can be provided. This - increment may be ignored. -
    • -
+ None
Returns
@@ -400,15 +508,79 @@ of the header should be "X-Vault-Token" and the value should be the token. ```javascript { - "auth": { - "client_token": "ABCD", - "policies": ["web", "stage"], - "metadata": {"user": "armon"}, - "lease_duration": 3600, - "renewable": true, + "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"`). +
    • +
  • + prefix + optional + If set, tokens created against this role will have the given prefix 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 + prefix can be changed, allowing new callers to have the new prefix as + part of their path, and then tokens with the old prefix can be revoked + via `revoke-prefix`. +
    • +
+
+ +
Returns
+
+ A `204` return code.