From 8e52b132f2bedcbedefe9b62d93f016f1ca90302 Mon Sep 17 00:00:00 2001 From: Lexman Date: Wed, 26 Jun 2019 07:31:10 -0700 Subject: [PATCH] Identity tokens documentation (#6971) --- .../secret/identity/identity-groups.html.md | 267 ---------- .../source/api/secret/identity/index.html.md | 1 + .../source/api/secret/identity/tokens.html.md | 495 ++++++++++++++++++ .../docs/secrets/identity/index.html.md | 177 +++++++ website/source/layouts/api.erb | 1 + 5 files changed, 674 insertions(+), 267 deletions(-) delete mode 100644 website/source/api/secret/identity/identity-groups.html.md create mode 100644 website/source/api/secret/identity/tokens.html.md diff --git a/website/source/api/secret/identity/identity-groups.html.md b/website/source/api/secret/identity/identity-groups.html.md deleted file mode 100644 index 2a36be3863..0000000000 --- a/website/source/api/secret/identity/identity-groups.html.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -layout: "api" -page_title: "/identity/groups - HTTP API" -sidebar_current: "api-http-secret-identity-groups" -description: |- - This is the API documentation for the identity groups. ---- - -## Create/Update Group - -This endpoint creates or updates a group. - -| Method | Path | -| :------------------ | :----------------------| -| `POST` | `/identity/group` | - -### Parameters - -- `name` `(string: group-)` – Name of the group. - -- `id` `(string: "")` - ID of the group. If this is set, this endpoint will - update the corresponding group. - -- `metadata` `(list of strings: [])` – Metadata to be associated with the group. Format should be a list of `key=value` pairs. - -- `policies` `(list of strings: [])` – Policies to be tied to the group. Comma separated list of strings. - -- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as group members. - -- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as group members. - -### Sample Payload - -```json -{ - "name": "engineering-group", - "metadata": ["organization=hashicorp", "team=vault"], - "policies": ["eng-dev", "infra-dev"] -} -``` - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/identity/group -``` - -### Sample Response - -```json -{ - "data": { - "id": "454ceeb5-76d7-a131-b92a-7ecfb15523e8", - "name": "engineering-group" - } -} -``` - -## Update Group by ID - -This endpoint updates the group by its ID. - -| Method | Path | -| :------------------------- | :----------------------| -| `POST` | `/identity/group/id/:id` | - -### Parameters - -- `id` `(string: "")` - ID of the group. - -- `name` `(string: group-)` – Name of the group. - -- `metadata` `(list of strings: [])` – Metadata to be associated with the group. Format should be a list of `key=value` pairs. - -- `policies` `(list of strings: [])` – Policies to be tied to the group. Comma separated list of strings. - -- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as group members. - -- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as group members. - -### Sample Payload - -```json -{ - "metadata": ["organization=updatedorg", "team=updatedteam"], - "policies": ["updatedpolicy"] -} -``` - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/identity/group/id/454ceeb5-76d7-a131-b92a-7ecfb15523e8 -``` - -### Sample Response - -```json -{ - "data": { - "id": "454ceeb5-76d7-a131-b92a-7ecfb15523e8", - "name": "engineering-group" - } -} -``` - -## Read Group by ID - -This endpoint reads the group by its ID. - -| Method | Path | -| :------------------------- | :--------------------- | -| `GET` | `/identity/group/id/:id` | - -### Parameters - -- `id` `(string: "")` - ID of the group. - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - http://127.0.0.1:8200/v1/identity/group/id/454ceeb5-76d7-a131-b92a-7ecfb15523e8 -``` - -### Sample Response - -```json -{ - "data": { - "creation_time": "2017-09-13T01:17:26.755474204Z", - "id": "454ceeb5-76d7-a131-b92a-7ecfb15523e8", - "last_update_time": "2017-09-13T01:17:26.755474204Z", - "member_entity_ids": [], - "member_group_ids": null, - "metadata": { - "organization": "hashicorp", - "team": "vault" - }, - "modify_index": 1, - "name": "engineering-group", - "policies": [ - "dev-policy" - ] - } -} -``` - -## Delete Group by ID - -This endpoint deleted the group by its ID. - -| Method | Path | -| :------------------------- | :----------------------| -| `DELETE` | `/identity/group/id/:id` | - -### Parameters - -- `id` `(string: "")` - ID of the group. - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request DELETE \ - http://127.0.0.1:8200/v1/identity/group/id/454ceeb5-76d7-a131-b92a-7ecfb15523e8 -``` - - -## List Groups by ID - -This endpoint lists all the groups by their ID. - -| Method | Path | -| :----------------------------- | :--------------------- | -| `LIST` | `/identity/group/id` | -| `GET` | `/identity/group/id?list=true` | - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request LIST \ - http://127.0.0.1:8200/v1/identity/group/id -``` - -### Sample Response - -```json -{ - "data": { - "keys": [ - "454ceeb5-76d7-a131-b92a-7ecfb15523e8", - "7b2fb80c-9516-68d1-35fc-11450f6477ab" - ] - } -} -``` - -## Lookup Group by ID - -This endpoint queries the group by its ID. - -| Method | Path | -| :------------------------- | :----------------------| -| `POST` | `/identity/lookup/group` | - -### Parameters - -- `type` `(string: "")` - Type of query. Supported values are `by_id` and `by_name`. - -- `group_name` `(string: "")` - Name of the group. - -- `group_id` `(string: "")` - ID of the group. - -### Sample Payload - -```json -{ - "type": "by_id", - "group_id": "454ceeb5-76d7-a131-b92a-7ecfb15523e8" -} -``` - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/identity/lookup/group -``` - -### Sample Response - -```json -{ - "data": { - "creation_time": "2017-09-13T01:17:26.755474204Z", - "id": "454ceeb5-76d7-a131-b92a-7ecfb15523e8", - "last_update_time": "2017-09-13T01:17:26.755474204Z", - "member_entity_ids": [], - "member_group_ids": null, - "metadata": { - "organization": "hashicorp", - "team": "vault" - }, - "modify_index": 1, - "name": "engineering-group", - "policies": [ - "dev-policy" - ] - } -} -``` diff --git a/website/source/api/secret/identity/index.html.md b/website/source/api/secret/identity/index.html.md index 3b806d53db..ec650dfa79 100644 --- a/website/source/api/secret/identity/index.html.md +++ b/website/source/api/secret/identity/index.html.md @@ -19,4 +19,5 @@ see the [Vault Identity documentation](/docs/secrets/identity/index.html). * [Entity Alias](entity-alias.html) * [Group](group.html) * [Group Alias](group-alias.html) + * [Identity Tokens](tokens.html) * [Lookup](lookup.html) diff --git a/website/source/api/secret/identity/tokens.html.md b/website/source/api/secret/identity/tokens.html.md new file mode 100644 index 0000000000..d32ec2e5b6 --- /dev/null +++ b/website/source/api/secret/identity/tokens.html.md @@ -0,0 +1,495 @@ +--- +layout: "api" +page_title: "Identity Secret Backend: Identity Tokens - HTTP API" +sidebar_title: "Identity Tokens" +sidebar_current: "api-http-secret-identity-tokens" +description: |- + This is the API documentation for configuring, acquiring, and validating vault issued identity tokens. +--- + +## Configure the Identity Tokens Backend + +This endpoint updates configurations for OIDC-compliant identity tokens issued by Vault. + +| Method | Path | +| :------------------ | :----------------------| +| `POST` | `identity/oidc/config` | + +### Parameters + +- `issuer` `(string: "")` – Issuer URL to be used in the iss claim of the token. If not set, Vault's api_addr will be used. The issuer is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components, but no query or fragment components. + +### Sample Payload + +```json +{ + "issuer": "https://example.com:1234" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/config +``` + +### Sample Response + +```json +{ + "data": null, + "warnings": [ + "If \"issuer\" is set explicitly, all tokens must be validated against that address, including those issued by secondary clusters. Setting issuer to \"\" will restore the default behavior of using the cluster's api_addr as the issuer." + ], +} +``` + +## Read Configurations for the Identity Tokens Backend + +This endpoint queries vault identity tokens configurations. + +| Method | Path | +| :------------------ | :----------------------| +| `GET` | `identity/oidc/config` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/config +``` + +### Sample Response + +```json +{ + "data": { + "issuer": "https://example.com:1234" + }, +} +``` + +## Create a Named Key + +This endpoint creates or updates a named key which is used by a role to sign tokens. + +| Method | Path | +| :------------------ | :----------------------| +| `POST` | `identity/oidc/key/:name` | + +### Parameters + +- `name` `(string)` – Name of the named key. + +- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Can be specified as a number of seconds or as a time string like "30m" or "6h". + +- `verification_ttl` `(int or time string: "24h")` - Controls how long the public portion of a signing key will be available for verification after being rotated. + +- `algorithm` `(string: "RS256")` - Signing algorithm to use. This will default to `"RS256"`, and is currently the only allowed value. + +### Sample Payload + +```json +{ + "rotation_period":"12h", + "verification_ttl":43200, +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 +``` + +## Read a Named Key + +This endpoint queries a named key and returns its configurations. + +| Method | Path | +| :------------------ | :----------------------| +| `GET` | `identity/oidc/key/:name` | + +### Parameters + +- `name` `(string)` – Name of the key. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 +``` + +### Sample Response + +```json +{ + "data": { + "algorithm": "RS256", + "rotation_period": 43200, + "verification_ttl": 43200 + }, +} +``` + +## Delete a Named Key + +This endpoint deletes a named key. + +| Method | Path | +| :------------------ | :----------------------| +| `DELETE` | `identity/oidc/key/:name` | + +### Parameters + +- `name` `(string)` – Name of the key. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 +``` + +## List Named Keys + +This endpoint will List all named keys. + +| Method | Path | +| :------------------ | :----------------------| +| `LIST` | `identity/oidc/key` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/key +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "named-key-001", + "named-key-002" + ] + }, +} +``` + +## Rotate a Named Key + +This endpoint rotates a named key. + +| Method | Path | +| :------------------ | :----------------------| +| `POST` | `identity/oidc/key/:name/rotate` | + +### Parameters + +- `name` `(string)` – Name of the key to be rotated. + +- `verification_ttl` `(string: )` - Controls how long the public portion of the key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key. + +### Sample Payload + +```json +{ + "verification_ttl": 0 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001/rotate +``` + +## Create or Update a Role + +Create or update a role. ID tokens are generated against a role and signed against a named key. + +| Method | Path | +| :------------------ | :----------------------| +| `POST` | `identity/oidc/role/:name` | + +### Parameters + +- `name` `(string)` – Name of the role. + +- `key` `(string)` – A configured named key, the key must already exist. + +- `template` `(string: )` - The template string to use for generating tokens. This may be in string-ified JSON or base64 format. + +- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Can be specified as a number of seconds or as a time string like "30m" or "6h". + +### Sample Payload + +```json +{ + "key": "named-key-001", + "ttl":"12h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/role/role-001 +``` + +## Read a Role + +This endpoint queries a role and returs its configuration. + +| Method | Path | +| :------------------ | :----------------------| +| `GET` | `identity/oidc/role/:name` | + +### Parameters + +- `name` `(string)` – Name of the role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/role/role-001 +``` + +### Sample Response + +```json +{ + "data": { + "client_id": "PGE8tf4RmJkDwvjI1FgARkXEmH", + "key": "named-key-001", + "template": "", + "ttl": 43200 + }, +} +``` + +## Delete a Role + +This endpoint deletes a role. + +| Method | Path | +| :------------------ | :----------------------| +| `DELETE` | `identity/oidc/role/:name` | + +### Parameters + +- `name` `(string)` – Name of the role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/role/role-001 +``` + +## List Roles + +This endpoint will list all signing keys. + +| Method | Path | +| :------------------ | :----------------------| +| `LIST` | `identity/oidc/role` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/role +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "role-001", + "role-002", + "testrole" + ] + }, +} +``` + +## Generate a Signed ID Token + +Use this endpoint to generate a signed ID (OIDC) token. + +| Method | Path | +| :------------------ | :----------------------| +| `POST` | `identity/oidc/token/:name` | + +### Parameters + +- `name` `(string: "")` – The name of the role against which to generate a signed ID token + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/token/role-001 +``` + +### Sample Response + +```json +{ + "data": { + "client_id": "P6CfCzyHsQY4pMcA6kWAOCItA7", + "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJkMGI4YjlkLWYwNGQtNzFlYy1iNjc0LWM3MzU4NDMyYmM1YiJ9.eyJhdWQiOiJQNkNmQ3p5SHNRWTRwTWNBNmtXQU9DSXRBNyIsImV4cCI6MTU2MTQ4ODQxMiwiaWF0IjoxNTYxNDAyMDEyLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tOjEyMzQiLCJzdWIiOiI2YzY1ZWFmNy1kNGY0LTEzMzMtMDJiYy0xYzc1MjE5YzMxMDIifQ.IcbWTmks7P5eVtwmIBl5rL1B88MI55a9JJuYVLIlwE9aP_ilXpX5fE38CDm5PixDDVJb8TI2Q_FO4GMMH0ymHDO25ZvA917WcyHCSBGaQlgcS-WUL2fYTqFjSh-pezszaYBgPuGvH7hJjlTZO6g0LPCyUWat3zcRIjIQdXZum-OyhWAelQlveEL8sOG_ldyZ8v7fy7GXDxfJOK1kpw5AX9DXJKylbwZTBS8tLb-7edq8uZ0lNQyWy9VPEW_EEIZvGWy0AHua-Loa2l59GRRP8mPxuMYxH_c88x1lsSw0vH9E3rU8AXLyF3n4d40PASXEjZ-7dnIf4w4hf2P4L0xs_g", + "ttl": 86400 + }, +} +``` + +## Introspect a signed ID Token + +This endpoint can verify the authenticity and active state of a signed ID token. + +| Method | Path | +| :------------------ | :----------------------| +| `POST` | `identity/oidc/introspect` | + +### Parameters + +- `token` `(string)` – A signed OIDC compliant ID token + +- `client_id` `(string: )` - Specifying the client ID optimizes validation time + +### Sample Payload + +```json +{ + "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/introspect +``` + +### Sample Response + + +```json + +{ + "active": true +} +``` + +## Read .well-known Configurations + +Query this path to retrieve a set of claims about the identity tokens' configuration. The response is a compliant [OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). + +| Method | Path | +| :------------------ | :----------------------| +| `GET` | `identity/oidc/.well-known/openid-configuration` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration +``` + +### Sample Response + +```json +{ + "issuer": "https://example.com:1234", + "authorization_endpoint": "", + "token_endpoint": "", + "jwks_uri": "https://example.com:1234/.well-known/keys", + "response_types_supported": null, + "subject_types_supported": [ + "public" + ], + "id_token_signing_alg_values_supported": [ + "RS256" + ], + "scopes_supported": null, + "token_endpoint_auth_methods_supported": null, + "claims_supported": null +} +``` + +## Read Active Public Keys +Query this path to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys +``` + +### Sample Response + +```json +{ + "keys": [ + { + "use": "sig", + "kty": "RSA", + "kid": "94178020-55b5-e18d-b32b-1010ba5a35b4", + "alg": "RS256", + "n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw", + "e": "AQAB" + } + ] +} +``` diff --git a/website/source/docs/secrets/identity/index.html.md b/website/source/docs/secrets/identity/index.html.md index 176e776f12..295f08c218 100644 --- a/website/source/docs/secrets/identity/index.html.md +++ b/website/source/docs/secrets/identity/index.html.md @@ -134,6 +134,183 @@ group and has an alias that maps to the group in LDAP. If the user is removed from the group in LDAP, that change gets reflected in Vault only upon the subsequent login or renewal operation. +## Identity Tokens + +Identity information is used throughout Vault, but it can also be exported for +use by other applications. An authorized user/application can request a token +that encapsulates identity information for their associated entity. These +tokens are signed JWTs following the [OIDC ID +token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) structure. +The public keys used to authenticate the tokens are published by Vault on an +unauthenticated endpoint following OIDC discovery and JWKS conventions, which +should be a directly usable by JWT/OIDC libraries. An introspection endpoint is +also provided by Vault for token verification. + +### Roles and Keys + +OIDC-compliant ID tokens are generated against a role which allows configuration +of token claims via a templating system, token ttl, and a way to specify which +"key" will be used to sign the token. The role template is an optional parameter +to customize the token contents and is described in the next section. Token TTL +controls the expiration time of the token, after which verification library will +consider the token invalid. All roles have a Vault-generated `client_id` +attribute that is returned when the role is read. This value cannot be changed +and will be added to the token's `aud` parameter. JWT/OIDC libraries will often +require this value. + +A role's `key` parameter links a role to an existing named key (multiple roles +may refer to the same key). It is not possible to generate an unsigned ID token. + +A named key is a public/private key pair generated by Vault. The private key is +used to sign the identity tokens, and the public key is used by clients to +verify the signature. Key are regularly rotated, whereby a new key pair is +generated and the previous _public_ key is retained for a limited time for +verification purposes. + +A named key's configuration specifies a rotation period, a verification ttl, and +signing algorithm. Rotation period specifies the frequency at which a new +signing key is generated and the private portion of the previous signing key is +deleted. Verification ttl is the time a public key is retained for verification, +after being rotated. By default, keys are rotated every 24 hours, and continue +to be available for verification for 24 hours after their rotation. + + +### Token Contents and Templates + +Identity tokens will always contain, at a minimum, the claims required by OIDC: + +* `iss` - Issuer URL +* `sub` - Requester's entity ID +* `aud` - `client_id` for the role +* `iss` - Time of issue +* `exp` - Expiration time for the token + +In addition, the operator may configure per-role templates that allow a variety +of other entity information to be added to the token. The templates are +structured as JSON with replaceable parameters. The parameter syntax is the same +as that used for [ACL Path Templating](/docs/concepts/policies.html). + +For example: + +```json +{ + "color": {{identity.entity.metadata.color}}, + "userinfo": { + "username": {{identity.entity.aliases.usermap_123.metadata.username}}, + "groups": {{identity.entity.group_names}} + + "nbf": {{time.now}}, +} +``` + +When a token is requested, the resulting template might be populated as: + +```json +{ + "color": "green", + "userinfo": { + "username": "bob", + "groups": ["web", "engr", "default] + + "nbf": 1561411915, +} +``` + +which would be merged with the base OIDC claims into the final token: + +```json +{ + "iss": "https://10.1.1.45:8200/v1/identity/oidc", + "sub": "a2cd63d3-5364-406f-980e-8d71bb0692f5", + "aud": "SxSouteCYPBoaTFy94hFghmekos", + "iss": 1561411915, + "exp": 1561412215, + "color": "green", + "userinfo": { + "username": "bob", + "groups": ["web", "engr", "default] + }, + "nbf": 1561411915, +} +``` + +Note how the template is merged, with top level template keys becoming top level +token keys. For this reason, templates may not contain top level keys that +overwrite the standard OIDC claims. + +Template parameters that are not present for an entity, such as a metadata that +isn't present, or an alias accessor which doesn't exist, are simply empty +strings or objects, depending on the data type. + +Templates are configured on the role and may be optionally encoded as base64. + +The full list of template parameters is shown below: + +| Name | Description | +| :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | +| `identity.entity.id` | The entity's ID | +| `identity.entity.name` | The entity's name | +| `identity.entity.group_ids` | The IDs of the groups the entity is a member of | +| `identity.entity.group_names` | The names of the groups the entity is a member of | +| `identity.entity.metadata` | Metadata associated with the entity | +| `identity.entity.metadata.<>` | Metadata associated with the entity for the given key | +| `identity.entity.aliases.<>.id` | Entity alias ID for the given mount | +| `identity.entity.aliases.<>.name` | Entity alias name for the given mount | +| `identity.entity.aliases.<>.metadata` | Metadata associated with the alias for the given mount | +| `identity.entity.aliases.<>.metadata.<>` | Metadata associated with the alias for the given mount and metadata key | +| `time.now` | Current time as integral seconds since the Epoch | +| `time.now.plus.<>` | Current time plus a Go-parsable [duration](https://golang.org/pkg/time/#ParseDuration) | | +| `time.now.minus.<>` | Current time minus a Go-parsable [duration](https://golang.org/pkg/time/#ParseDuration) | | + +### Token Generation + +An authenticated client may request a token using the [token generation +endpoint](api/secret/identity/tokens.html#generate-a-signed-id-token). The token +will be generated per the requested role's specifications, for the requester's +entity. It is not possible to generate tokens for an arbitrary entity. + +### Verifying Authenticity of ID Tokens Generated by Vault + +An identity token may be verified by the client party using the public keys +published by Vault, or via a Vault-provided introspection endpoint. + +Vault will serve standard "[.well-known](https://tools.ietf.org/html/rfc5785)" +endpoints that allow easy integration with OIDC verification libraries. +Configuring the libraries will typically involve providing an issuer URL and +client ID. The library will then handle key requests and can validate the +signature and claims requirements on tokens. This approach has the advantage of +only requiring _access_ to Vault, not _authorization_, as the .well-known +endpoints are unauthenticated. + +Alternatively, the token may be sent to Vault for verification via an +[introspection endpoint](api/secret/identity/tokens.html#introspect-a-signed-id-token). +The response will indicate whether the token is "active" or not, as well as any +errors that occurred during validation. Beyond simply allowing the client to +delegate verification to Vault, using this endpoint incorporates the additional +check of whether the entity is still active or not, which is something that +cannot be determined from the token alone. Unlike the .well-known endpoint, accessing the +introspection endpoint does require a valid Vault token and sufficient +authorization. + + +### Issuer Considerations + +The identity token system has one configurable parameter: issuer. The issuer +`iss` claim is particularly important for proper validation of the token by +clients, and special consideration should be given when using Identity Tokens +with [performance replication](docs/enterprise/replication/index.html). +Consumers of the token will request public keys from Vault using the issuer URL, +so it must be network reachable. Furthermore, the returned set of keys will include +an issuer that must match the request. + +By default Vault will set the issuer to the Vault instance's +[`api_addr`](docs/configuration/index.html#api_addr). This means that tokens +issued in a given cluster should be validated within that same cluster. +Alternatively, the [`issuer`](api/secret/identity/tokens.html#issuer) parameter +may be configured explicitly. This address must point to the identity/oidc path +for the Vault instance (e.g. +`https://vault-1.example.com:8200/v1/identity/oidc`) and should be +reachable by any client trying to validate identity tokens. ## API diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 018af7e4ee..8974fd83d1 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -47,6 +47,7 @@ 'entity-alias', 'group', 'group-alias', + 'tokens', 'lookup' ] },