f3df55ad58
* Adding check-legacy-links-format workflow * Adding test-link-rewrites workflow * Updating docs-content-check-legacy-links-format hash * Migrating links to new format Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
197 lines
10 KiB
Plaintext
197 lines
10 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Identity Tokens
|
|
description: Details and best practices for identity tokens.
|
|
---
|
|
|
|
# Identity Tokens
|
|
|
|
## Introduction
|
|
|
|
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 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 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.
|
|
|
|
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. Keys 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,
|
|
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
|
|
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.
|
|
|
|
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.
|
|
|
|
### 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
|
|
- `iat` - 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](/vault/docs/concepts/policies).
|
|
|
|
For example:
|
|
|
|
```jsx
|
|
{
|
|
"color": {{identity.entity.metadata.color}},
|
|
"userinfo": {
|
|
"username": {{identity.entity.aliases.usermap_123.metadata.username}},
|
|
"groups": {{identity.entity.groups.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",
|
|
"iat": 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.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 |
|
|
| `time.now.plus.<duration>` | Current time plus a [duration format string](/vault/docs/concepts/duration-format) |
|
|
| `time.now.minus.<duration>` | Current time minus a [duration format string](/vault/docs/concepts/duration-format) |
|
|
|
|
### Token Generation
|
|
|
|
An authenticated client may request a token using the [token generation
|
|
endpoint](/vault/api-docs/secret/identity/tokens#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](/vault/api-docs/secret/identity/tokens#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](/vault/docs/enterprise/replication).
|
|
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`](/vault/docs/configuration#api_addr). This means that tokens
|
|
issued in a given cluster should be validated within that same cluster.
|
|
Alternatively, the [`issuer`](/vault/api-docs/secret/identity/tokens#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
|
|
|
|
The Identity secrets engine has a full HTTP API. Please see the
|
|
[Identity secrets engine API](/vault/api-docs/secret/identity) for more
|
|
details.
|