2017-07-25 22:33:17 +00:00
---
2020-01-18 00:18:09 +00:00
layout: docs
2021-11-16 02:02:36 +00:00
page_title: Identity Tokens
description: Details and best practices for identity tokens.
2017-07-25 22:33:17 +00:00
---
2021-11-16 02:02:36 +00:00
# Identity Tokens
2017-07-25 22:33:17 +00:00
2021-11-16 02:02:36 +00:00
## Introduction
2019-06-26 14:31:10 +00:00
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
2021-07-14 19:35:10 +00:00
should be directly usable by JWT/OIDC libraries. An introspection endpoint is
2019-06-26 14:31:10 +00:00
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
2020-02-21 18:59:09 +00:00
controls the expiration time of the token, after which verification libraries will
consider the token invalid. All roles have an associated `client_id` that will be
added to the token's `aud` parameter. JWT/OIDC libraries will usually require this
value. The parameter may be set by the operator to a chosen value, or a
Vault-generated value will be used if left unconfigured.
2019-06-26 14:31:10 +00:00
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
2021-07-14 19:35:10 +00:00
verify the signature. Keys are regularly rotated, whereby a new key pair is
2019-06-26 14:31:10 +00:00
generated and the previous _public_ key is retained for a limited time for
verification purposes.
2019-07-26 16:59:38 +00:00
A named key's configuration specifies a rotation period, a verification ttl,
signing algorithm and allowed client IDs. 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
2021-07-14 19:35:10 +00:00
retained for verification after being rotated. By default, keys are rotated
2019-07-26 16:59:38 +00:00
every 24 hours, and continue to be available for verification for 24 hours after
their rotation.
A key's list of allowed client IDs limits which roles may reference the key. The
parameter may be set to `*` to allow all roles. The validity evaluation is made
when a token is requested, not during configuration.
2019-06-26 14:31:10 +00:00
### Token Contents and Templates
Identity tokens will always contain, at a minimum, the claims required by OIDC:
2020-01-18 00:18:09 +00:00
- `iss` - Issuer URL
- `sub` - Requester's entity ID
- `aud` - `client_id` for the role
2021-06-23 16:04:23 +00:00
- `iat` - Time of issue
2020-01-18 00:18:09 +00:00
- `exp` - Expiration time for the token
2019-06-26 14:31:10 +00:00
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
2020-01-22 20:05:41 +00:00
as that used for [ACL Path Templating](/docs/concepts/policies).
2019-06-26 14:31:10 +00:00
For example:
2020-01-22 20:05:41 +00:00
```jsx
2019-06-26 14:31:10 +00:00
{
"color": {{identity.entity.metadata.color}},
"userinfo": {
"username": {{identity.entity.aliases.usermap_123.metadata.username}},
2021-11-17 16:25:37 +00:00
"groups": {{identity.entity.groups.names}}
2021-06-23 16:04:23 +00:00
},
"nbf": {{time.now}}
2019-06-26 14:31:10 +00:00
}
```
When a token is requested, the resulting template might be populated as:
```json
{
"color": "green",
"userinfo": {
"username": "bob",
2019-07-31 22:23:00 +00:00
"groups": ["web", "engr", "default"]
2021-06-23 16:04:23 +00:00
},
"nbf": 1561411915
2019-06-26 14:31:10 +00:00
}
```
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",
2021-06-23 16:04:23 +00:00
"iat": 1561411915,
2019-06-26 14:31:10 +00:00
"exp": 1561412215,
"color": "green",
"userinfo": {
2020-01-18 00:18:09 +00:00
"username": "bob",
"groups": ["web", "engr", "default"]
2019-06-26 14:31:10 +00:00
},
2020-01-18 00:18:09 +00:00
"nbf": 1561411915
2019-06-26 14:31:10 +00:00
}
```
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:
2021-11-02 20:23:29 +00:00
| Name | Description |
| :------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `identity.entity.id` | The entity's ID |
| `identity.entity.name` | The entity's name |
| `identity.entity.groups.ids` | The IDs of the groups the entity is a member of |
| `identity.entity.groups.names` | The names of the groups the entity is a member of |
| `identity.entity.metadata` | Metadata associated with the entity |
| `identity.entity.metadata.<metadata key>` | Metadata associated with the entity for the given key |
| `identity.entity.aliases.<mount accessor>.id` | Entity alias ID for the given mount |
| `identity.entity.aliases.<mount accessor>.name` | Entity alias name for the given mount |
| `identity.entity.aliases.<mount accessor>.metadata` | Metadata associated with the alias for the given mount |
| `identity.entity.aliases.<mount accessor>.metadata.<metadata key>` | Metadata associated with the alias for the given mount and metadata key |
| `identity.entity.aliases.<mount accessor>.custom_metadata` | Custom metadata associated with the alias for the given mount |
| `identity.entity.aliases.<mount accessor>.custom_metadata.<custom_metadata key>` | Custom metadata associated with the alias for the given mount and custom metadata key |
| `time.now` | Current time as integral seconds since the Epoch |
2022-06-13 12:51:07 +00:00
| `time.now.plus.<duration>` | Current time plus a [duration format string](/docs/concepts/duration-format) |
| `time.now.minus.<duration>` | Current time minus a [duration format string](/docs/concepts/duration-format) |
2019-06-26 14:31:10 +00:00
### Token Generation
2020-01-18 00:18:09 +00:00
2019-06-26 14:31:10 +00:00
An authenticated client may request a token using the [token generation
2022-03-18 01:14:48 +00:00
endpoint](/api-docs/secret/identity/tokens#generate-a-signed-id-token). The token
2019-06-26 14:31:10 +00:00
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
2022-03-18 01:14:48 +00:00
[introspection endpoint](/api-docs/secret/identity/tokens#introspect-a-signed-id-token).
2019-06-26 14:31:10 +00:00
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
2020-01-22 20:05:41 +00:00
with [performance replication](/docs/enterprise/replication).
2019-06-26 14:31:10 +00:00
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
2020-01-22 20:05:41 +00:00
[`api_addr`](/docs/configuration#api_addr). This means that tokens
2019-06-26 14:31:10 +00:00
issued in a given cluster should be validated within that same cluster.
2022-03-18 01:14:48 +00:00
Alternatively, the [`issuer`](/api-docs/secret/identity/tokens#issuer) parameter
2019-06-26 14:31:10 +00:00
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.
2018-04-01 17:59:43 +00:00
2017-07-25 22:33:17 +00:00
## API
2017-09-20 20:05:00 +00:00
The Identity secrets engine has a full HTTP API. Please see the
2022-03-18 01:14:48 +00:00
[Identity secrets engine API](/api-docs/secret/identity) for more
2017-07-25 22:33:17 +00:00
details.
