---
page_title: JWT provider configuration entry reference
description: |-
 JWT provider configuration entries add JSON Web Token token validation to intentions in the service mesh. Learn how to write `jwt-provider` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case.
---

# JWT provider configuration entry reference

This page provides reference information for the JWT provider configuration entry, which configures Consul to use a JSON Web Token (JWT) and JSON Web Key Set (JWKS) in order to add JWT validation to proxies in the service mesh. Refer to [Use JWT authorization with service intentions](/consul/docs/connect/intentions/jwt-authorization) for more information.

## Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in a JWT provider configuration entry. Click on a property name to view additional details, including default values.

<Tabs>

<Tab heading="HCL and JSON" group="hcl">

- [`Kind`](#kind): string | required | must be set to `jwt-provider`
- [`Name`](#name): string | required
- [`Issuer`](#issuer): string
- [`JSONWebKeySet`](#jsonwebkeyset): map
  - [`Local`](#jsonwebkeyset-local): map
    - [`JWKS`](#jsonwebkeyset-local-jwks): string
    - [`Filename`](#jsonwebkeyset-local-filename): string
  - [`Remote`](#jsonwebkeyset-remote): map
    - [`URI`](#jsonwebkeyset-remote-uri): string
    - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms): integer
    - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration): string | `5m`
    - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously): boolean | `false`
    - [`JWKSCluster`](#jsonwebkeyset-remote-jwkscluster): map
      - [`DiscoveryType`](#jsonwebkeyset-remote-jwkscluster-discoverytype): string | `STRICT_DNS`
      - [`ConnectTimeout`](#jsonwebkeyset-remote-jwkscluster-connecttimeout): string | `5s`
      - [`TLSCertificates`](#jsonwebkeyset-remote-jwkscluster-tlscertificates): map
        - [`CaCertificateProviderInstance`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): map
          - [`InstanceName`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string | `default`
          - [`CertificateName`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string
        - [`TrustedCA`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): map
          - [`Filename`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
          - [`EnvironmentVariable`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
          - [`InlineString`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
          - [`InlineBytes`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
    - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy): map
      - [`NumRetries`](#jsonwebkeyset-remote-retrypolicy-numretries): integer | `0`
      - [`RetryPolicyBackoff`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): map
        - [`BaseInterval`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string
        - [`MaxInterval`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string
- [`Audiences`](#audiences): list of strings
- [`Locations`](#locations): list of maps
  - [`Header`](#locations-header): map
    - [`Name`](#locations-header-name): string
    - [`ValuePrefix`](#locations-header-valueprefix): string
    - [`Forward`](#locations-header-forward): boolean | `false`
  - [`QueryParam`](#locations-queryparam): map
    - [`Name`](#locations-queryparam): string
  - [`Cookie`](#locations-cookie): map
    - [`Name`](#locations-cookie): string
- [`Forwarding`](#forwarding): map
  - [`HeaderName`](#forwarding-headername): string
  - [`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader): boolean | `false`
- [`ClockSkewSeconds`](#clockskewseconds): integer | `30`
- [`CacheConfig`](#cacheconfig): map
  - [`Size`](#cacheconfig-size): integer | `0`

</Tab>

<Tab heading="YAML" group="yaml">

- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `JWTProvider`
- [`metadata`](#metadata): map | required
  - [`name`](#metadata-name): string | required
  - [`namespace`](#metadata-namespace): string
- [`spec`](#spec): map | required
  - [`issuer`](#spec-issuer): string
  - [`jsonWebKeySet`](#spec-jsonwebkeyset): map
    - [`local`](#spec-jsonwebkeyset-local): map
      - [`jwks`](#spec-jsonwebkeyset-local-jwks): string
      - [`filename`](#spec-jsonwebkeyset-local-filename): string
    - [`remote`](#spec-jsonwebkeyset-remote): map
      - [`uri`](#spec-jsonwebkeyset-remote-uri): string
      - [`requestTimeoutMs`](#spec-jsonwebkeyset-remote-requesttimeoutms): integer
      - [`cacheDuration`](#spec-jsonwebkeyset-remote-cacheduration): string | `5m`
      - [`fetchAsynchronously`](#spec-jsonwebkeyset-remote-fetchasynchronously): boolean | `false`
      - [`retryPolicy`](#spec-jsonwebkeyset-remote-retrypolicy): map
        - [`numRetries`](#spec-jsonwebkeyset-remote-retrypolicy-numretries): integer | `0`
        - [`retryPolicyBackoff`](#spec-jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): map
          - [`baseInterval`](#spec-jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string
          - [`maxInterval`](#spec-jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string
      - [`jwksCluster`](#spec-jsonwebkeyset-remote-jwkscluster): map
        - [`discoveryType`](#spec-jsonwebkeyset-remote-jwkscluster-discoverytype): string | `STRICT_DNS`
        - [`connectTimeout`](#spec-jsonwebkeyset-remote-jwkscluster-connecttimeout): string | `5s`
        - [`tlsCertificates`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates): map
          - [`caCertificateProviderInstance`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): map
            - [`instanceName`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string | `default`
            - [`certificateName`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string
          - [`trustedCA`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): map
            - [`filename`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
            - [`environmentVariable`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
            - [`inlineString`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
            - [`inlineBytes`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string
  - [`audiences`](#spec-audiences): list of strings
  - [`locations`](#spec-locations): list of maps
    - [`header`](#spec-locations-header): map
      - [`name`](#spec-locations-header-name): string
      - [`valuePrefix`](#spec-locations-header-valueprefix): string
      - [`forward`](#spec-locations-header-forward): boolean | `false`
    - [`queryParam`](#spec-locations-queryparam): map
      - [`name`](#spec-locations-queryparam): string
    - [`cookie`](#spec-locations-cookie): map
      - [`name`](#spec-locations-cookie): string
  - [`forwarding`](#spec-forwarding): map
    - [`headerName`](#spec-forwarding-headername): string
    - [`padForwardPayloadHeader`](#spec-forwarding-padforwardpayloadheader): boolean | `false`
  - [`clockSkewSeconds`](#spec-clockskewseconds): integer | `30`
  - [`cacheConfig`](#spec-cacheconfig): map
    - [`size`](#spec-cacheconfig-size): integer | `0`

</Tab>
</Tabs>

## Complete configuration

When every field is defined, a JWT provider configuration entry has the following form:

<Tabs>

<Tab heading="HCL" group="hcl">

```hcl
Kind = "jwt-provider"                                # required
Name = "<name-of-provider-configuration-entry>"      # required
Issuer = "<jwt-issuer>"                              # required
JSONWebKeySet = {                                    # required
  Local = {                                        # cannot specify with JWKS{}.Remote
    JWKS = "<JWKS-as-base64-string>"             # cannot specify with JWKS{}.Local{}.Filename
    Filename = "<path/to/JWKS/file>"             # cannot specify with JWKS{}.Local{}.String
  }
}
JSONWebKeySet = {
  Remote = {                                   # cannot specify with JWKS{}.Local
    URI = "<uniform-resource-identifier>"
    RequestTimeoutMs = 1500
    CacheDuration = "5m"
    FetchAsynchronously = false
    RetryPolicy = {
      NumRetries = 0
      RetryPolicyBackoff = {
        BaseInterval = "1s"
        MaxInterval = "10s"
      }
    }
    JWKSCluster = {
      DiscoveryType = "STATIC"
      ConnectTimeout = "10s"
      # specify only one child: TrustedCA or CaCertificateProviderInstance
      TLSCertificates = {
        # specify only one child: Filename, EnvironmentVariable, InlineString or InlineBytes
        TrustedCA = {
          Filename = "<path/to/cert/file>"
          EnvironmentVariable = "<env-variable>"
          InlineString = "<inline-string>"
          InlineBytes = "\302\000\302\302\302\302"
        }
      }
      TLSCertificates = {
        CaCertificateProviderInstance = {
          InstanceName = "<instance-name>"
          CertificateName = "<certificate-name>"
        }
      }
    }
  }
}

Audiences = ["<aud-claims>"]
Locations = [
  {
    Header = {
      Name = "<name-of-header-with-token>"
      ValuePrefix = "<prefix-in-header-before-token>"
      Forward = false
    }
  },
  {
    QueryParam = {
      Name = "<name-of-query-parameter-with-token>"
    }
  },
  {
    Cookie = {
      Name = "<name-of-cookie-with-token>"
    }
  }
]
Forwarding = {
  HeaderName = "<name-appended-to-forwarding-header>"
  PadForwardPayloadHeader = false
}
ClockSkewSeconds = 30
CacheConfig = {
  Size = 0
}
```

</Tab>

<Tab heading="JSON" group="json">

```json
{
  "Kind": "jwt-provider",                               // required
  "Name": "<name-of-provider-configuration-entry>",     // required
  "Issuer": "<jwt-issuer>",                             // required
  "JSONWebKeySet": {                                    // required
    "Local": {                                        // cannot specify with JWKS.Remote
      "JWKS": "<JWKS-as-base64-string>",            // cannot specify with JWKS.Local.Filename
      "Filename": "<path/to/JWKS/file>"             // cannot specify with JWKS.Local.String
    }
  },
  "JSONWebKeySet": {
    "Remote": {                                   // cannot specify with JWKS.Local
      "URI": "<uniform-resource-identifier>",
      "RequestTimeoutMs": "1500",
      "CacheDuration": "5m",
      "FetchAsynchronously": "false",
      "RetryPolicy": {
        "NumRetries": "0",
        "RetryPolicyBackOff": {
          "BaseInterval": "1s",
          "MaxInterval": "10s"
        }
      },
      "JWKSCluster": {
        "DiscoveryType": "STATIC",
        "ConnectTimeout": "10s",
        // specify only one child: TrustedCA or CaCertificateProviderInstance
        "TLSCertificates": {
          // specify only one child: Filename, EnvironmentVariable, InlineString or InlineBytes
          "TrustedCA": {
            "Filename": "<path/to/cert/file>",
            "EnvironmentVariable": "<env-variable>",
            "InlineString": "<inline-string>",
            "InlineBytes": "\302\000\302\302\302\302"
          },
        },
        "TLSCertificates": {
          "CaCertificateProviderInstance": {
            "InstanceName": "<instance-name>",
            "CertificateName": "<certificate-name>"
          }
        }
      }
    }
  },
  "Audiences": ["<aud-claims>"],
  "Locations": [
    {
      "Header": {
        "Name": "<name-of-header-with-token>",
        "ValuePrefix": "<prefix-in-header-before-token>",
        "Forward": "false"
      }
    },
    {
      "QueryParam": {
        "Name":"<name-of-query-parameter-with-token>",
      }
    },
    {
      "Cookie": {
        "Name": "<name-of-cookie-with-token>"
      }
    }
  ],
  "Forwarding": {
    "HeaderName": "<name-appended-to-forwarding-header>",
    "PadForwardPayloadHeader": "false"
  },
  "ClockSkewSeconds": "30",
  "CacheConfig": {
    "Size": "0"
  }
}
```

</Tab>

<Tab heading="YAML" group="yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1         # required
kind: JWTProvider                                 # required
metadata:                                         # required
  name: <name-of-provider-configuration-entry>    # required
  namespace: <namespace>
spec:                                             # required
  issuer: <jwt-issuer>
  jsonWebKeySet:
    local:                                        # cannot specify with spec.jsonWebKeySet.remote
     jwks: <jwks-as-base64-string>                # cannot specify with spec.jsonWebKeySet.local.filename
     filename: <path/to/jwks/file>                # cannot specify with spec.jsonWebKeySet.local.string
  jsonWebKeySet:
    remote:                                       # cannot specify with spec.jsonWebKeySet.local
      uri: <uniform-resource-identifier>
      requestTimeoutMs: 1500
      cacheDuration: 5m
      fetchAsynchronously: false
      retryPolicy:
        numRetries: 0
        retryPolicyBackoff:
          baseInterval: 1s
          maxInterval: 10s
      jwksCluster:
        discoveryType: STATIC
        connectTimeout: 10s
        # specify only one child: trustedCA or caCertificateProviderInstance
        tlsCertificates:
          # specify only one child: filename, environmentVariable, inlineString or inlineBytes
          trustedCA:
            filename: <path/to/cert/file>
            environmentVariable: <env-variable>
            inlineString: <inline-string>
            inlineBytes: \302\000\302\302\302\302
        tlsCertificates:
          caCertificateProviderInstance:
            instanceName: <instance-name>
            certificateName: <certificate-name>
  audiences: [<aud-claims>]
  locations:
    header:
      name: <name-of-header-with-token>
      valuePrefix: "<prefix-in-header-before-token>"
      forward: false
    queryParam:
      name: "<name-of-query-parameter-with-token>"
    cookie:
      name: "<name-of-cookie-with-token>"
  forwarding:
    headerName: "<name-appended-to-forwarding-header>"
    padForwardPayloadHeader: false
  clockSkewSeconds: 30
  cacheConfig:
    size: 0
```

</Tab>
</Tabs>

## Specification

This section provides details about the fields you can configure in the JWT provider configuration entry.

<Tabs>

<Tab heading="HCL" group="hcl">

### `Kind`

Specifies the type of configuration entry to implement.

#### Values

- Default: None
- This field is required.
- Data type: String value that must be set to `jwt-provider`.

### `Name`

Specifies a name for the configuration entry. We recommend naming the configuration file after the JWT provider used in the configuration. Refer to the [Okta JWT Provider example](#okta-jwt-provider) for an example configuration.

#### Values

- Default: None
- This field is required.
- Data type: String

### `Issuer`

Specifies the provider that issued the JWT. This value must match the token’s `iss` (issuer) claim.

#### Values

- Default: None
- Data type: String

### `JSONWebKeySet`

Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`JSONWebKeySet{}.Local`](#jsonwebkeyset-local) and [`JSONWebKeySet{}.Remote`](#jsonwebkeyset-remote) in the same map.

#### Values

- Default: None
- Data type: Map that can contain one of the following parameters:

  - [`Local`](#jsonwebkeyset-local)
  - [`Remote`](#jsonwebkeyset-remote)

### `JSONWebKeySet{}.Local`

Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `JWKS` and `Filename` in the same map.

#### Values

- Default: None
- Data type: Map that can contain one of the following parameters:

  - [`JWKS`](#jsonwebkeyset-local-jwks)
  - [`Filename`](#jsonwebkeyset-local-filename)

### `JSONWebKeySet{}.Local{}.JWKS`

Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `JWKS` parameter if [`JWKS{}.Local{}.Filename`](#jsonwebkeyset-local-filename) is also specified in the same map.

#### Values

- Default: None
- Data type: String

### `JSONWebKeySet{}.Local{}.Filename`

Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `Filename` parameter if [`JWKS{}.Local{}.String`](#jsonwebkeyset-local-string) is also specified in the same map.

#### Values

- Default: None
- Data type: String

### `JSONWebKeySet{}.Remote`

Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`URI`](#jsonwebkeyset-remote-uri)
  - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms)
  - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration)
  - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously)
  - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy)
  - [`JWKSCluster`](#jsonwebkeyset-remote-jwkscluster)

### `JSONWebKeySet{}.Remote{}.URI`

Specifies the URI of the server to query for the JSON Key Web Set.

#### Values

- Default: None
- Data type: String

### `JSONWebKeySet{}.Remote{}.RequestTimeoutMs`

Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms).

#### Values

- Default: None
- Data type: Integer

### `JSONWebKeySet{}.Remote{}.CacheDuration`

Specifies the amount of time cached keys are available before they expire.

The default cache duration is 5 minutes.

#### Values

- Default: `5m`
- Data type: String

### `JSONWebKeySet{}.Remote{}.FetchAsynchronously`

Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating.

This parameter is set to `false` by default.

#### Values

- Default: `false`
- Data type: Boolean

### `JSONWebKeySet{}.Remote{}.RetryPolicy`

Defines a retry policy when fetching the JSON Web Key Set from the remote location.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`NumRetries`](#jsonwebkeyset-remote-retrypolicy-numretries)
  - [`RetryPolicyBackoff`](#jsonwebkeyset-remote-retrypolicy-retrypolicybackoff)

### `JSONWebKeySet{}.Remote{}.RetryPolicy{}.NumRetries`

Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails.

#### Values

- Default: `0`
- Data type: Integer

### `JSONWebKeySet{}.Remote{}.RetryPolicy{}.RetryPolicyBackoff`

Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `BaseInterval`| Specifies the base interval to use for the next back off computation. | String | `1s` |
| `MaxInterval` | Specifies the maximum interval between retries. By default, this value is 10 times `BaseInterval`. | String | `10s` |

### `JSONWebKeySet{}.Remote{}.JWKSCluster`

Defines how Envoy fetches the remote JSON Web Key Set URI.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`DiscoveryType`](#jsonwebkeyset-remote-jwkscluster-discoverytype)
  - [`ConnectTimeout`](#jsonwebkeyset-remote-jwkscluster-connecttimeout)
  - [`TLSCertificates`](#jsonwebkeyset-remote-jwkscluster-tlscertificates)


### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.DiscoveryType`

Specifies the service discovery type to use for resolving the cluster.
You can specify the following discovery types:
- `STRICT_DNS`
- `STATIC`
- `LOGICAL_DNS`
- `EDS`
- `ORIGINAL_DST`

#### Values

- Default: `STRICT_DNS`
- Data type: String

### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.ConnectTimeout`

Specifies the duration of time new network connections attempt to connect to hosts in the cluster before they timeout.

#### Values

- Default: `5s`
- Data type: String

### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates`

Specifies the data containing certificate authority certificates to use for verifying a presented peer certificate.
Envoy does not verify certificates that peers present if this field is not configured.

You cannot specify [`TLSCertificates{}.CaCertificateProviderInstance`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance) and [`TLSCertificates{}.TrustedCA`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca) in the same map.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`CaCertificateProviderInstance`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance)
  - [`TrustedCA`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca)

### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.CaCertificateProviderInstance`

Specifies the certificate provider instance for fetching TLS certificates.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `InstanceName`| Refers to the certificate provider instance name. | String | `default` |
| `CertificateName` | Specifies the certificate instances or types. For example, use `ROOTCA` to specify a root-certificate. | String | None |

### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.TrustedCA`

Specifies TLS certificate data containing certificate authority certificates. Specify exactly one of the following data holders:
- `Filename`
- `EnvironmentVariable`
- `InlineString`
- `InlineBytes`

#### Values

- Default: None
- Data type: Map containing one of the following parameters:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `Filename`| The name of the file on the local system to use a data source for trusted CA certificates. | String | None |
| `EnvironmentVariable` | The environment variable on the local system to use a data source for trusted CA certificates. | String | None |
| `InlineString` | A string to inline in the configuration for use as a data source for trusted CA certificates. | String    | None |
| `InlineBytes` | A sequence of bytes to inline in the configuration for use as a data source for trusted CA certificates. | String | None |

### `Audiences`

Specifies a set of audiences that the JWT is allowed to access, formatted as a list of `aud` (audience) claims. When this field is specified, all JWTs verified with the provider must address at least one of the audiences in order to be considered valid.

#### Values

- Default: None
- Data type: List of strings

### `Locations`

Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT.

This field can specify token locations in a header, a query parameter, or a cookie. When no locations are specified, Envoy defaults to the following locations:

1. Authorization header with Bearer schema: `"Authorization: Bearer <token>"`
1. `access_token` query parameter.

#### Values

- Default: None
- Data type: List that can contain maps of the following parameters:

  - [`Header`](#locations-header)
  - [`QueryParam`](#locations-queryparam)
  - [`Cookie`](#locations-cookie)

### `Locations[].Header`

Defines how to extract a JWT from an HTTP request header.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`Name`](#locations-header-name)
  - [`ValuePrefix`](#locations-header-valueprefix)
  - [`Forward`](#locations-header-forward)

### `Locations[].Header{}.Name`

Specifies the name of the HTTP request header containing the token.

#### Values

- Default: None
- Data type: String

### `Locations[].Header{}.ValuePrefix`

Specifies a prefix that must precede the token in the header value.

For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer <token>`. The prefix is not part of the token.

#### Values

- Default: None
- Data type: String

### `Locations[].Header{}.Forward`

Specifies whether the header with the JWT is forwarded after the token is verified. When set to `false`, the header is not forwarded.

The default value is `false`.

#### Values

- Default: `false`
- Data type: Boolean

### `Locations[].QueryParam`

Defines how to extract a JWT from an HTTP request query parameter.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

| Parameter | Description                                                     | Data type | Default value |
| :-------- | :-------------------------------------------------------------- | :-------- | :------------ |
| `Name`    | Specifies the name of the query parameter containing the token. | String    | None          |

### `Locations[].Cookie`

Defines how to extract a JWT from an HTTP request cookie.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `Name`| Specifies the name of the cookie containing the token. | String    | None          |

### `Forwarding`

Defines rules for forwarding JWTs to the backend after they are verified.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`HeaderName`](#forwarding-headername)
  - [`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader)

### `Forwarding{}.HeaderName`

Specifies a header name to use when forwarding a verified JWT to the backend. This field does not assume where the JWT was extracted from, and it can be applied to tokens extracted from headers, query parameters, or cookies.

The header value is base64 URL encoded. It is not padded by default.

#### Values

- Default: None
- Data type: String

### `Forwarding{}.PadForwardPayloadHeader`

Determines whether to add padding to the base64 encoded token specified in [`Forwarding{}.HeaderName`](#forwarding-header-name).

By default, this field is set to `false`.

#### Values

- Default: `false`
- Data type: Boolean

### `ClockSkewSeconds`

Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf`  (not before) claims, measured in seconds.

By default, this parameter is configured to 30 seconds.

#### Values

- Default: `30`
- Data type: Integer

### `CacheConfig`

Defines behavior for caching the validation result of previously encountered JWTs. Caching results can speed up verification when the same tokens are expected to be handled multiple times. By default, the cache can hold 100 JWTs.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `Size`    | Specifies the number of JSON web tokens to cache.  | Integer   | `100`         |

</Tab>

<Tab heading="YAML" group="yaml">

### `apiVersion`

Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`.

#### Values

- Default: None
- This field is required.
- String value that must be set to `consul.hashicorp.com/v1alpha1`.

### `kind`

Specifies the type of configuration entry to implement. Must be set to `jwtProvider`.

#### Values

- Default: None
- This field is required.
- Data type: String value that must be set to `jwtProvider`.

### `metadata`

Map that contains an arbitrary name for the configuration entry and the namespace it applies to.

#### Values

- Default: None
- Data type: Map

### `metadata.name`

Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster. We recommend naming the configuration file after the JWT provider used in the configuration. Refer to the [Okta JWT Provider example](#okta-jwt-provider) for an example configuration.

#### Values

- Default: None
- This field is required.
- Data type: String

### `metadata.namespace` <EnterpriseAlert inline />

Specifies the namespace that the configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.

#### Values

- Default: None
- Data type: String

### `spec`

Map that contains the details about the `jwtProvider` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children.

#### Values

- Default: None
- This field is required.
- Data type: Map

### `spec.issuer`

Specifies the provider that issued the JWT. This value must match the token’s `iss` (issuer) claim.

#### Values

- Default: None
- Data type: String

### `spec.jsonWebKeySet`

Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`spec.jsonWebKeySet.local`](#spec-jsonwebkeyset-local) and [`spec.jsonWebKeySet.remote`](#spec-jsonwebkeyset-remote) in the same map.

#### Values

- Default: None
- Data type: Map that can contain one of the following parameters:

  - [`local`](#spec-jsonwebkeyset-local)
  - [`remote`](#spec-jsonwebkeyset-remote)

### `spec.jsonWebKeySet.local`

Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `string` and `filename` in the same map.

#### Values

- Default: None
- Data type: Map that can contain one of the following parameters:

  - [`jwks`](#spec-jsonwebkeyset-local-jwks)
  - [`filename`](#spec-jsonwebkeyset-local-filename)

### `spec.jsonWebKeySet.local.jwks`

Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `jwks` parameter if [`spec.jsonWebKeySet.local.filename`](#spec-jsonwebkeyset-local-filename) is also specified in the same map.

#### Values

- Default: None
- Data type: String

### `spec.jsonWebKeySet.local.filename`

Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `filename` parameter if [`spec.jsonWebKeySet.local.jwks`](#spec-jsonwebkeyset-local-jwks) is also specified in the same map.

#### Values

- Default: None
- Data type: String

### `spec.jsonWebKeySet.remote`

Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`uri`](#spec-jsonwebkeyset-remote-uri)
  - [`requestTimeoutMs`](#spec-jsonwebkeyset-remote-requesttimeoutms)
  - [`cacheDuration`](#spec-jsonwebkeyset-remote-cacheduration)
  - [`fetchAsynchronously`](#spec-jsonwebkeyset-remote-fetchasynchronously)
  - [`retryPolicy`](#spec-jsonwebkeyset-remote-retrypolicy)

### `spec.jsonWebKeySet.remote.uri`

Specifies the URI of the server to query for the JSON Key Web Set.

#### Values

- Default: None
- Data type: String

### `spec.jsonWebKeySet.remote.requestTimeoutMs`

Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms).

#### Values

- Default: None
- Data type: Integer

### `spec.jsonWebKeySet.remote.cacheDuration`

Specifies the amount of time cached keys are available before they expire.

The default cache duration is 5 minutes.

#### Values

- Default: `5m`
- Data type: String

### `spec.jsonWebKeySet.remote.fetchAsynchronously`

Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating.

This parameter is set to `false` by default.

#### Values

- Default: `false`
- Data type: Boolean

### `spec.jsonWebKeySet.remote.retryPolicy`

Defines a retry policy when fetching the JSON Web Key Set from the remote location.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

  - [`numRetries`](#spec-jsonwebkeyset-remote-retrypolicy-numretries)
  - [`retryPolicyBackoff`](#spec-jsonwebkeyset-remote-retrypolicy-retrypolicybackoff)

### `spec.jsonWebKeySet.remote.retryPolicy.numRetries`

Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails.

#### Values

- Default: `0`
- Data type: Integer

### `spec.jsonWebKeySet.remote.retryPolicy.retryPolicyBackoff`

Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `baseInterval`| Specifies the base interval to use for the next back off computation. | String | `1s` |
| `maxInterval` | Specifies the maximum interval between retries. By default, this value is 10 times `BaseInterval`. | String | `10s` |

### `spec.jsonWebKeySet.remote.jwksCluster`

Defines how Envoy fetches the remote JSON Web Key Set URI.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`discoveryType`](#spec-jsonwebkeyset-remote-jwkscluster-discoverytype)
  - [`connectTimeout`](#spec-jsonwebkeyset-remote-jwkscluster-connecttimeout)
  - [`tlsCertificates`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates)

### `spec.jsonWebKeySet.remote.jwksCluster.discoveryType`

Specifies the service discovery type to use for resolving the cluster.
You can specify the following discovery types:
- `STRICT_DNS`
- `STATIC`
- `LOGICAL_DNS`
- `EDS`
- `ORIGINAL_DST`

String values must be a valid [Cluster DiscoveryType](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-enum-config-cluster-v3-cluster-discoverytype).

#### Values

- Default: `STRICT_DNS`
- Data type: String

### `spec.jsonWebKeySet.remote.jwksCluster.connectTimeout`

Specifies the timeout for new network connections to hosts in the cluster.

#### Values

- Default: `5s`
- Data type: String

### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates`

Specifies the data containing certificate authority certificates to use for verifying a presented peer certificate.
Envoy does not verify certificates that peers present if this field is not configured.

You cannot specify [`spec.tlsCertificates.caCertificateProviderInstance`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance) and [`spec.tlsCertificates.trustedCA`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca) in the same map.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`caCertificateProviderInstance`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance)
  - [`trustedCA`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca)

### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.caCertificateProviderInstance`

Specifies the certificate provider instance for fetching TLS certificates.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `instanceName`| Refers to the certificate provider instance name. | String | `default` |
| `certificateName` | Specifies the certificate instances or types. For example, use `ROOTCA` to specify a root-certificate. | String | None |

### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.trustedCA`

Specifies TLS certificate data containing certificate authority certificates. Specify exactly one of the following data holders:
- `Filename`
- `EnvironmentVariable`
- `InlineString`
- `InlineBytes`

#### Values

- Default: None
- Data type: Map containing one of the following parameters:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `filename`| The name of the file on the local system to use a data source for trusted CA certificates. | String | None  |
| `environmentVariable` | The environment variable on the local system to use a data source for trusted CA certificates. | String | None |
| `inlineString` | A string to inline in the configuration for use as a data source for trusted CA certificates. | String | None |
| `inlineBytes` | A sequence of bytes to inline in the configuration for use as a data source for trusted CA certificates. | String | None |

### `spec.audiences`

Specifies a set of audiences that the JWT is allowed to access, formatted as a list of `aud` (audience) claims. When this field is specified, all JWTs verified with the provider must address at least one of the audiences in order to be considered valid.

#### Values

- Default: None
- Data type: List of strings

### `spec.locations`

Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT.

This field can specify token locations in a header, a query parameter, or a cookie. When no locations are specified, Envoy defaults to the following locations:

1. Authorization header with Bearer schema: `"Authorization: Bearer <token>"`
1. `access_token` query parameter.

#### Values

- Default: None
- Data type: List that can contain maps of the following parameters:

  - [`header`](#spec-locations-header)
  - [`queryParam`](#spec-locations-queryparam)
  - [`cookie`](#spec-locations-cookie)

### `spec.locations[].header`

Defines how to extract a JWT from an HTTP request header.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`name`](#spec-locations-header-name)
  - [`valuePrefix`](#spec-locations-header-valueprefix)
  - [`forward`](#spec-locations-header-forward)

### `spec.locations[].header.name`

Specifies the name of the HTTP request header containing the token.

#### Values

- Default: None
- Data type: String

### `spec.locations[].header.valuePrefix`

Specifies a prefix that must precede the token in the header value.

For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer <token>`. The prefix is not part of the token.

#### Values

- Default: None
- Data type: String

### `spec.locations[].header.forward`

Specifies whether the header with the JWT is forwarded after the token is verified. When set to  `false`, the header is not forwarded.

The default value is `false`.

#### Values

- Default: `false`
- Data type: Boolean

### `spec.locations[].queryParam`

Defines how to extract a JWT from an HTTP request query parameter.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

| Parameter | Description                                                     | Data type | Default value |
| :-------- | :-------------------------------------------------------------- | :-------- | :------------ |
| `name`    | Specifies the name of the query parameter containing the token. | String    | None          |

### `spec.locations[].cookie`

Defines how to extract a JWT from an HTTP request cookie.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `name`| Specifies the name of the cookie containing the token. | String    | None          |

### `spec.forwarding`

Defines rules for forwarding JWTs to the backend after they are verified.

#### Values

- Default: None
- Data type: Map that can contain the following parameters:

  - [`headerName`](#spec-forwarding-headername)
  - [`padForwardPayloadHeader`](#spec-forwarding-padforwardpayloadheader)

### `spec.forwarding.headerName`

Specifies a header name to use when forwarding a verified JWT to the backend. This field does not assume where the JWT was extracted from, and it can be applied to tokens extracted from headers, query parameters, or cookies.

The header value is base64 URL encoded. It is not padded by default.

#### Values

- Default: None
- Data type: String

### `spec.forwarding.padForwardPayloadHeader`

Determines whether to add padding to the base64 encoded token specified in [spec.forwarding.headerName`](#spec-forwarding-header-name).

By default, this field is set to `false`.

#### Values

- Default: `false`
- Data type: Boolean

### `spec.clockSkewSeconds`

Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf`  (not before) claims, measured in seconds.

By default, this parameter is configured to 30 seconds.

#### Values

- Default: `30`
- Data type: Integer

### `spec.cacheConfig`

Defines behavior for caching the validation result of previously encountered JWTs. Caching results can speed up verification when the same tokens are expected to be handled multiple times. By default, the cache can hold 100 JWTs.

#### Values

- Default: None
- Data type: Map that contains the following parameter:

| Parameter | Description                                        | Data type | Default value |
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `size`    | Specifies the number of JSON web tokens to cache.  | Integer   | `100`         |

</Tab>
</Tabs>

## Metrics

Envoy proxies expose metrics that can track JWT authentication details. Use the following Envoy metrics:

```yaml
http.public_listener.jwt_authn.allowed
http.public_listener.jwt_authn.cors_preflight_bypassed
http.public_listener.jwt_authn.denied
http.public_listener.jwt_authn.jwks_fetch_failed
http.public_listener.jwt_authn.jwks_fetch_success
http.public_listener.jwt_authn.jwt_cache_hit
http.public_listener.jwt_authn.jwt_cache_miss
```

~> **Note:** Currently, Envoy does not reference these metrics in their documentation. Refer to [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/) for more information about exposed metrics.

## Examples

The following examples demonstrate common JWT provider configuration patterns for specific use cases.

### Okta JWT provider

The following example configures Consul to fetch a JSON Web Token issued by Okta. Consul fetches the token from the URI and keeps it in its cache for 30 minutes before the token expires. After validation, the token is forwarded to the backend with `user-token` appended to the HTTP header.

<Tabs>

<Tab heading="HCL" group="hcl">

```hcl
Kind = "jwt-provider"
Name = "okta"

Issuer = "okta"

JSONWebKeySet = {
    Remote = {
        URI = "https://<org>.okta.com/oauth2/default/v1/keys"
        CacheDuration = "30m"
    }
}

Forwarding = {
    HeaderName = "user-token"
}
```

</Tab>

<Tab heading="JSON" group="json">

```json
{
  "Kind": "jwt-provider",
  "Name": "okta",
  "Issuer": "okta",
  "JSONWebKeySet": {
    "Remote": {
        "URI": "https://<org>.okta.com/oauth2/default/v1/keys",
        "CacheDuration": "30m"
    }
  },
  "Forwarding": {
    "HeaderName": "user-token"
  }
}
```

</Tab>

<Tab heading="YAML" group="yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: JWTProvider
metadata:
  name: okta
spec:
  issuer: okta
  jsonWebKeySet:
    remote:
      uri: https://<org>.okta.com/oauth2/default/v1/keys
      cacheDuration: 30m
  forwarding:
    headerName: user-token
```

</Tab>
</Tabs>