open-consul/website/content/docs/security/acl/auth-methods/jwt.mdx

---
layout: docs
page_title: JWT Auth Method
description: >-
  The JWT auth method can be used to authenticate with Consul by providing a
  JWT directly. The JWT is cryptographically verified using locally-provided
  keys, or, if configured, an OIDC Discovery service can be used to fetch the
  appropriate keys.
---

# JWT Auth Method

-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.

The `jwt` auth method can be used to authenticate with Consul by providing a
[JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) directly. The JWT is
cryptographically verified using locally-provided keys, or, if configured, an
OIDC Discovery service can be used to fetch the appropriate keys.

This page assumes general knowledge of JWTs and the concepts described in the
main [auth method documentation](/docs/security/acl/auth-methods).

Both the [`jwt`](/docs/security/acl/auth-methods/jwt) and the
[`oidc`](/docs/security/acl/auth-methods/oidc) auth method types allow additional
processing of the claims data in the JWT.

@include 'jwt_or_oidc.mdx'

## Config Parameters

The following auth method [`Config`](/api-docs/acl/auth-methods#config)
parameters are required to properly configure an auth method of type
`jwt`:

- `JWTValidationPubKeys` `(array<string>)` - A list of PEM-encoded public keys
  to use to authenticate signatures locally.

  Exactly one of `JWKSURL` `JWTValidationPubKeys`, or `OIDCDiscoveryURL` is required.

- `OIDCDiscoveryURL` `(string: "")` - The OIDC Discovery URL, without any
  .well-known component (base path).

  Exactly one of `JWKSURL` `JWTValidationPubKeys`, or `OIDCDiscoveryURL` is required.

- `OIDCDiscoveryCACert` `(string: "")` - PEM encoded CA cert for use by the TLS
  client used to talk with the OIDC Discovery URL. NOTE: Every line must end
  with a newline (`\n`). If not set, system certificates are used.

- `JWKSURL` `(string: "")` - The JWKS URL to use to authenticate signatures.

  Exactly one of `JWKSURL` `JWTValidationPubKeys`, or `OIDCDiscoveryURL` is required.

- `JWKSCACert` `(string: "")` - PEM encoded CA cert for use by the TLS client
  used to talk with the JWKS URL. NOTE: Every line must end with a newline
  (`\n`). If not set, system certificates are used.

- `ClaimMappings` `(map[string]string)` - Mappings of claims (key) that
  [will be copied to a metadata field](#trusted-identity-attributes-via-claim-mappings)
  (value). Use this if the claim you are capturing is singular (such as an attribute).

  When mapped, the values can be any of a number, string, or boolean and will
  all be stringified when returned.

- `ListClaimMappings` `(map[string]string)` - Mappings of claims (key)
  [will be copied to a metadata field](#trusted-identity-attributes-via-claim-mappings)
  (value). Use this if the claim you are capturing is list-like (such as groups).

  When mapped, the values in each list can be any of a number, string, or
  boolean and will all be stringified when returned.

- `JWTSupportedAlgs` `(array<string>)` - JWTSupportedAlgs is a list of
  supported signing algorithms. Defaults to `RS256`.

- `BoundAudiences` `(array<string>)` - List of `aud` claims that are valid for
  login; any match is sufficient.

- `BoundIssuer` `(string: "")` - The value against which to match the `iss`
  claim in a JWT.

- `ExpirationLeeway` `(duration: 0s)` - Duration in seconds of leeway when
  validating expiration of a token to account for clock skew. Defaults to 150
  (2.5 minutes) if set to 0 and can be disabled if set to -1.

- `NotBeforeLeeway` `(duration: 0s)` - Duration in seconds of leeway when
  validating not before values of a token to account for clock skew. Defaults
  to 150 (2.5 minutes) if set to 0 and can be disabled if set to -1.

- `ClockSkewLeeway` `(duration: 0s)` - Duration in seconds of leeway when
  validating all claims to account for clock skew. Defaults to 60 (1 minute)
  if set to 0 and can be disabled if set to -1.

### Sample Configs

#### Static Keys

```json
{
    ...other fields...
    "Config": {
        "BoundIssuer": "corp-issuer",
        "JWTValidationPubKeys": [
            "<public key PEM>"
        ],
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}
```

#### JWKS

```json
{
    ...other fields...
    "Config": {
        "JWKSURL": "https://my-corp-jwks-url.example.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}
```

#### OIDC Discovery

```json
{
    ...other fields...
    "Config": {
        "BoundAudiences": [
            "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}
```

## JWT Verification

JWT signatures will be verified against public keys from the issuer. This
process can be done one of three ways:

- **Static Keys** - A set of public keys is stored directly in the
  configuration.

- **JWKS** - A JSON Web Key Set ([JWKS](https://tools.ietf.org/html/rfc7517))
  URL (and optional certificate chain) is configured. Keys will be fetched from
  this endpoint during authentication.

- **OIDC Discovery** - An OIDC Discovery URL (and optional certificate chain)
  is configured. Keys will be fetched from this URL during authentication. When
  OIDC Discovery is used, OIDC validation criteria (e.g. `iss`, `aud`, etc.)
  will be applied.

If multiple methods are needed, another auth method of this type may be created
with a different name.

@include 'jwt_claim_mapping_details.mdx'