Identity tokens

Introduction

Identity information is used throughout OpenBao, 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 structure. The public keys used to authenticate the tokens are published by OpenBao 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 OpenBao 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 OpenBao-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 OpenBao. 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.

For example:

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

{
  "color": "green",
  "userinfo": {
     "username": "bob",
     "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

which would be merged with the base OIDC claims into the final token:

{
  "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
time.now.minus.<duration>	Current time minus a duration format string

Token generation

An authenticated client may request a token using the token generation endpoint. 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 OpenBao

An identity token may be verified by the client party using the public keys published by OpenBao, or via an OpenBao-provided introspection endpoint.

OpenBao will serve standard ".well-known" 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 OpenBao, not authorization, as the .well-known endpoints are unauthenticated.

Alternatively, the token may be sent to OpenBao for verification via an introspection endpoint. 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 OpenBao, 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 OpenBao 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. Consumers of the token will request public keys from OpenBao 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 OpenBao will set the issuer to the OpenBao instance's api_addr. This means that tokens issued in a given cluster should be validated within that same cluster. Alternatively, the issuer parameter may be configured explicitly. This address must point to the identity/oidc path for the OpenBao instance (e.g. https://openbao-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 for more details.