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`
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:
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:
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` |
### `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 |
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.
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:
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:
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:
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.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:
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 |
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 |
~> **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.
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"
