JSON Web Token (JWT) Auth Method

Use the jwt auth method to authenticate with Nomad by providing a JWT directly. The JWT is cryptographically verified using locally-provided keys, or, if configured, you may use an OIDC Discovery service to fetch the appropriate keys.

Refer to auth-method create for the parameters required to create a JWT auth-method with a given verification method.

JWT Verification

Nomad verifies JWT signatures against public keys from the issuer. This process uses one of these methods:

Static Keys - A set of public keys is stored directly in the configuration.
JWKS - Configure a JSON Web Key Set (JWKS) URL and optional certificate chain. Nomad fetches keys from this endpoint during authentication.
OIDC Discovery - Configure an OIDC Discovery URL and optional certificate chain. Nomad fetches keys from this URL during authentication. When you use OIDC Discovery, Nomad applies OIDC validation criteria such as iss and aud.

If you need multiple methods, create another auth method of this type with a different name.

Trusted Identity Attributes via Claim Mappings

The authentication step can return data from JWT claims as trusted identity attributes for use in binding rule selectors and bind name interpolation.

The ClaimMappings and ListClaimMappings attributes control how Nomad maps claims to identity attributes. Both are maps of items to copy, with elements of the form "<JWT claim>":"<attribute suffix>".

Use ClaimMappings to map singular values and ListClaimMappings to map lists of values.

This examples contains ClaimMappings and ListClaimMappings. The configuration instructs Nomad to copy the values in the JWT claims "givenName" and "surname" to attributes named "value.first_name" and "value.last_name" respectively. Additionally, Nomad should copy the list of values in the JWT claim "groups" to an attribute named "list.roles".

{
  "Name": "example-auth-method",
  "Type": "<jwt|oidc>",
  "Description": "Example auth method",
  "Config": {
    "ClaimMappings": {
      "givenName": "first_name",
      "surname": "last_name"
    },
    "ListClaimMappings": {
      "groups": "roles"
    }
  }
}

The following table shows the resulting attributes and the ways they may be used in rule bindings:

Attributes	Supported selector operations	Can be interpolated
`value.first_name`	Equal, Not Equal, In, Not In, Matches, Not Matches	yes
`value.last_name`	Equal, Not Equal, In, Not In, Matches, Not Matches	yes
`list.groups`	In, Not In, Is Empty, Is Not Empty	no

Refer to the binding-rule documentation for more examples on using selectors.

Claim Specifications and JSON Pointer

Use the ClaimMappings and ListClaimMappings fields to point to data within the JWT. If the desired key is at the top of level of the JWT, you may provide the name directly. If it is nested at a lower level, you may use a JSON Pointer.

This example shows decoded JWT claims.

{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  },
  "iss": "https://my-corp-app-name.auth0.com/",
  "sub": "auth0|eiw7OWoh5ieSh7ieyahC3ief0uyuraphaengae9d",
  "aud": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
  "iat": 1589224148,
  "exp": 1589260148,
  "nonce": "eKiihooH3Fah8Ieshah4leeti6ien3"
}

Use the following syntax to reference data:

Top-level key: Use direct reference. For example, "division" refers to "North America".
Nested key: Use JSON Pointer syntax. For example, "/groups/primary" refers to "Engineering".

You may use any valid JSON Pointer as a selector. Refer to the JSON Pointer RFC for a full description of the syntax.