JWT configuration in the IAM file

Learn about the structure of IdPs tables in the IAM configuration file

The IAM configuration file can include information that enables Vault to authenticate JWT tokens to provide access to the REST API. This information is stored in the [idps] table. This page describes the syntax and layout of that table. See Configure JWT authentication for a guide to creating JWT tokens and corresponding [idps] tables, and IAM configuration examples for JWT authentication for examples of [idps] tables for various use cases.

Syntax

JWT authentication configurations are defined with the [idps] heading like this:

[idps]

  [idps.<IdP-name>]
    allowed_roles = [<roles-list>] # optional
    type = "direct-jwt"

  [idps.<IdP-name>.conf]
    aud = "<audience-name>"
    extra_claims = '''<claims-and-values>''' # optional
    iss = "<issuer-name>"
    jwks_uri = <JWK-key-url>
    keys = <JWK-key>
    namespace_top_claim = "<top-namespace>"  # optional
    roles_claim = "<role-name>"  # optional

   [idps.<IdP-name>.conf.bound_claims] # optional
     <bound-claim-key> = <bound-claim-value>
     …

  [idps.<IdP-name>.roles_map] # optional
    "<your-backend-service-account-email>" = "<role-in-vault>"

Where:

• IdP-name is a meaningful identifier for the JWT authentication configuration. This identifier is used to identify audit log records associated with the JWT token.
• roles-list is a list of the Vault IAM roles the JWT tokens can use in the format of an array of strings. If a token evaluates to a role not on the list, the request is not authorized. If not configured, all roles are allowed.
• issuer-name is the issuer (iss claim) of the JWT access token. Vault fails the authentication if the JWT token does not match this value.
• audience-name is the audience (aud claim) of the JWT access token. Vault fails the authentication if the JWT token does not match this value.
• JWK-key is the public key of the key-pair used to sign the JWT access token in JWKS format. Must be used if jwks_uri is not used.
• JWK-key-url is the URL of the JWKS endpoint that contains the public key in JWT format. It is usually in this format: https://<identity-privoder/.well-known/jwks.json. Must be used if keys is not used.
  note

  Using jwks_uri requires Vault to have outbound access to the JWKS endpoint. The response is cached for 24 hours, unless configured otherwise by the HTTP response from the endpoint. On key failure, Vault attempts to refresh the cache to account for key rotation by the provider.

• top-namespace is a claim that contains nested namespace claims. This claim is expected to be an object. It's useful when the platform used to generate the JWTs only allows custom claims nested under a claim that is not under your control. This configuration does not affect bound_claims and roles_claim, which operate at the top level. Defaults to the top level of the JWT ("root").
• roles_name is the name of the claim in the JWT access token containing the user's roles. Vault fails the authentication if the JWT token does not contain the roles_name key. If not set with no value, defaults to "roles".
• claims-and-values are extra claims to be parsed with the claims of the JWT access token. Usually contains extra namespace claims with prop-claim-ref enforcement. If namespace_top_claim is configured, the extra claims are nested under it. See Extra claims for more details.
• bound_claims is a table that provides extra claims validation. See Bound claims for more details.
• roles_map is a table of roles defined in the JWT token (your-backend-service-account-email) mapped to a Vault IAM role (role-in-vault). If this configuration is used, the role in the JWT must match one of the keys in the table. See the Google Cloud Platform example in IAM configuration examples for JWT authentication for more information.

Extra claims

You can configure Vault to parse extra claims by adding a list of claims and values in JSON string format to the extra_claims field.

For example, this configuration uses the namespace claim https://app.piiano.io/any-of to allow a request only if the manipulated item's user_id property is the value of the "myapp_user_id" claim or group_id property is the value of the myapp_group_ids claim in the JWT access token:

[idps]

[idps.app1]
  type = "direct-jwt"

[idps.app1.conf]
  iss = ...
  aud = ...
  jwks_uri = ...
  extra_claims = '''
  {
    "https://app.piiano.io/any-of": {
      "prop-claim-ref/user_id": "myapp_user_id,
      "prop-claim-ref/group_ids": "myapp_group_ids"
    } 
  }
  '''

So, if the JWT access token claims are:

{
  ...
  "myapp_user_id": "user1",
  "myapp_group_ids": ["group-1", "group-2"]
  ...
}

Then the request is allowed if the user_id property is user1 OR the group_id property is either group-1 or group-2 in the object, token, or ciphertext being accessed.

tip

The extra_claims configuration is useful for enforcing property values that are part of the JWT access token. That way, you don't need to change the JWT access token structure.

Bound claims

You use the bound_claims table if additional validation of claims is required.

The bound claims configuration is a map of strings to values or an array of values of the types string, boolean, integer, or float. The keys are the names of the claims, and the values are the expected values of the claims. If the value is an array, the claim must match one of the values in the array.

After the JWT access token is validated, Vault compares the bound claims with the claims in the JWT access token. If any bound claims are absent from the JWT access token or don't match, the authentication fails.

Examples of bound claims

For this bound_claims table:

[idps.app1.conf.bound_claims]
  email_verified = true

A JWT token with this claim is validated when the user has the email_verified property set to true in the JWT; otherwise, validation fails.

For this bound_claims table:

[idps.app1.conf.bound_claims]
  group = ["support", security"]

A JWT token with this claim is validated when the user is a member of the support or security groups; otherwise, validation fails.