- JWT provider configuration entry reference
- Configuration model
- Complete configuration
- Specification
Kind
Name
Issuer
JSONWebKeySet
JSONWebKeySet{}.Local
JSONWebKeySet{}.Local{}.JWKS
JSONWebKeySet{}.Local{}.Filename
JSONWebKeySet{}.Remote
JSONWebKeySet{}.Remote{}.URI
JSONWebKeySet{}.Remote{}.RequestTimeoutMs
JSONWebKeySet{}.Remote{}.CacheDuration
JSONWebKeySet{}.Remote{}.FetchAsynchronously
JSONWebKeySet{}.Remote{}.RetryPolicy
JSONWebKeySet{}.Remote{}.RetryPolicy{}.NumRetries
JSONWebKeySet{}.Remote{}.RetryPolicy{}.RetryPolicyBackoff
JSONWebKeySet{}.Remote{}.JWKSCluster
JSONWebKeySet{}.Remote{}.JWKSCluster{}.DiscoveryType
JSONWebKeySet{}.Remote{}.JWKSCluster{}.ConnectTimeout
JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates
JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.CaCertificateProviderInstance
JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.TrustedCA
Audiences
Locations
Locations[].Header
Locations[].Header{}.Name
Locations[].Header{}.ValuePrefix
Locations[].Header{}.Forward
Locations[].QueryParam
Locations[].Cookie
Forwarding
Forwarding{}.HeaderName
Forwarding{}.PadForwardPayloadHeader
ClockSkewSeconds
CacheConfig
apiVersion
kind
metadata
metadata.name
metadata.namespace
EnterpriseEnterprisespec
spec.issuer
spec.jsonWebKeySet
spec.jsonWebKeySet.local
spec.jsonWebKeySet.local.jwks
spec.jsonWebKeySet.local.filename
spec.jsonWebKeySet.remote
spec.jsonWebKeySet.remote.uri
spec.jsonWebKeySet.remote.requestTimeoutMs
spec.jsonWebKeySet.remote.cacheDuration
spec.jsonWebKeySet.remote.fetchAsynchronously
spec.jsonWebKeySet.remote.retryPolicy
spec.jsonWebKeySet.remote.retryPolicy.numRetries
spec.jsonWebKeySet.remote.retryPolicy.retryPolicyBackoff
spec.jsonWebKeySet.remote.jwksCluster
spec.jsonWebKeySet.remote.jwksCluster.discoveryType
spec.jsonWebKeySet.remote.jwksCluster.connectTimeout
spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates
spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.caCertificateProviderInstance
spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.trustedCA
spec.audiences
spec.locations
spec.locations[].header
spec.locations[].header.name
spec.locations[].header.valuePrefix
spec.locations[].header.forward
spec.locations[].queryParam
spec.locations[].cookie
spec.forwarding
spec.forwarding.headerName
spec.forwarding.padForwardPayloadHeader
spec.clockSkewSeconds
spec.cacheConfig
- Metrics
- Examples
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 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.
- Kind: string | required | must be set to
jwt-provider
- Name: string | required
- Issuer: string
- JSONWebKeySet: map
- Local: map
- Remote: map
- URI: string
- RequestTimeoutMs: integer
- CacheDuration: string |
5m
- FetchAsynchronously: boolean |
false
- JWKSCluster: map
- DiscoveryType: string |
STRICT_DNS
- ConnectTimeout: string |
5s
- TLSCertificates: map
- CaCertificateProviderInstance: map
- InstanceName: string |
default
- CertificateName: string
- InstanceName: string |
- TrustedCA: map
- Filename: string
- EnvironmentVariable: string
- InlineString: string
- InlineBytes: string
- CaCertificateProviderInstance: map
- DiscoveryType: string |
- RetryPolicy: map
- NumRetries: integer |
0
- RetryPolicyBackoff: map
- BaseInterval: string
- MaxInterval: string
- NumRetries: integer |
- Audiences: list of strings
- Locations: list of maps
- Header: map
- Name: string
- ValuePrefix: string
- Forward: boolean |
false
- QueryParam: map
- Name: string
- Cookie: map
- Name: string
- Header: map
- Forwarding: map
- HeaderName: string
- PadForwardPayloadHeader: boolean |
false
- ClockSkewSeconds: integer |
30
CacheConfig: map
- Size: integer |
0
- Size: integer |
apiVersion: string | required | must be set to
consul.hashicorp.com/v1alpha1
- kind: string | required | must be set to
JWTProvider
- metadata: map | required
- spec: map | required
- issuer: string
- jsonWebKeySet: map
- local: map
- remote: map
- uri: string
- requestTimeoutMs: integer
- cacheDuration: string |
5m
- fetchAsynchronously: boolean |
false
- retryPolicy: map
- numRetries: integer |
0
- retryPolicyBackoff: map
- baseInterval: string
- maxInterval: string
- numRetries: integer |
- jwksCluster: map
- discoveryType: string |
STRICT_DNS
- connectTimeout: string |
5s
- tlsCertificates: map
- caCertificateProviderInstance: map
- instanceName: string |
default
- certificateName: string
- instanceName: string |
- trustedCA: map
- filename: string
- environmentVariable: string
- inlineString: string
- inlineBytes: string
- caCertificateProviderInstance: map
- discoveryType: string |
- audiences: list of strings
- locations: list of maps
- header: map
- name: string
- valuePrefix: string
- forward: boolean |
false
- queryParam: map
- name: string
- cookie: map
- name: string
- header: map
- forwarding: map
- headerName: string
- padForwardPayloadHeader: boolean |
false
- clockSkewSeconds: integer |
30
- cacheConfig: map
- size: integer |
0
- size: integer |
Complete configuration
When every field is defined, a JWT provider configuration entry has the following form:
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
}
{
"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"
}
}
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
Specification
This section provides details about the fields you can configure in the JWT provider configuration entry.
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 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 and JSONWebKeySet{}.Remote in the same map.
Values
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
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 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 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:
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:
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:
JSONWebKeySet{}.Remote{}.JWKSCluster{}.DiscoveryType
Specifies the service discovery type to use for resolving the cluster. You can specify the following discovery types:
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 and TLSCertificates{}.TrustedCA in the same map.
Values
Default: None
Data type: Map that can contain the following parameters:
JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.CaCertificateProviderInstance
Speficies 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:
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:
- Authorization header with Bearer schema:
"Authorization: Bearer <token>"
- access_token query parameter.
Values
Default: None
Data type: List that can contain maps of the following parameters:
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:
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:
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.
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 |
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 for an example configuration.
Values
- Default: None
- This field is required.
- Data type: String
metadata.namespace
EnterpriseEnterprise
Specifies the namespace that the configuration applies to. Refer to 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 and spec.jsonWebKeySet.remote in the same map.
Values
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
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 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 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:
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:
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:
spec.jsonWebKeySet.remote.jwksCluster.discoveryType
Specifies the service discovery type to use for resolving the cluster. You can specify the following discovery types:
String values must be a valid 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 and spec.tlsCertificates.trustedCA in the same map.
Values
Default: None
Data type: Map that can contain the following parameters:
spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.caCertificateProviderInstance
Speficies 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:
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:
- Authorization header with Bearer schema:
"Authorization: Bearer <token>"
- access_token query parameter.
Values
Default: None
Data type: List that can contain maps of the following parameters:
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:
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:
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`.
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 |
Metrics
Envoy proxies expose metrics that can track JWT authentication details. Use the following Envoy metrics:
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 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.
Kind = "jwt-provider"
Name = "okta"
Issuer = "okta"
JSONWebKeySet = {
Remote = {
URI = "https://<org>.okta.com/oauth2/default/v1/keys"
CacheDuration = "30m"
}
}
Forwarding = {
HeaderName = "user-token"
}
{
"Kind": "jwt-provider",
"Name": "okta",
"Issuer": "okta",
"JSONWebKeySet": {
"Remote": {
"URI": "https://<org>.okta.com/oauth2/default/v1/keys",
"CacheDuration": "30m"
}
},
"Forwarding": {
"HeaderName": "user-token"
}
}
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