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
  - JWKS: string
  - Filename: string
- 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
      - TrustedCA: map
        Filename: string
        EnvironmentVariable: string
        InlineString: string
        InlineBytes: string
  - RetryPolicy: map
    - NumRetries: integer | 0
    - RetryPolicyBackoff: map
      - BaseInterval: string
      - MaxInterval: 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
Forwarding: map
- HeaderName: string
- PadForwardPayloadHeader: boolean | false
ClockSkewSeconds: integer | 30
CacheConfig: map
- Size: integer | 0

apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1
kind: string | required | must be set to JWTProvider
metadata: map | required
- name: string | required
- namespace: string
spec: map | required
- issuer: string
- jsonWebKeySet: map
  - local: map
    - jwks: string
    - filename: string
  - remote: map
    - uri: string
    - requestTimeoutMs: integer
    - cacheDuration: string | 5m
    - fetchAsynchronously: boolean | false
    - retryPolicy: map
      - numRetries: integer | 0
      - retryPolicyBackoff: map
        baseInterval: string
        maxInterval: string
    - jwksCluster: map
      - discoveryType: string | STRICT_DNS
      - connectTimeout: string | 5s
      - tlsCertificates: map
        caCertificateProviderInstance: map
        instanceName: string | default
        certificateName: string
        trustedCA: map
        filename: string
        environmentVariable: string
        inlineString: string
        inlineBytes: 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
- forwarding: map
  - headerName: string
  - padForwardPayloadHeader: boolean | false
- clockSkewSeconds: integer | 30
- cacheConfig: map
  - size: integer | 0

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

Default: None
Data type: Map that can contain one of the following parameters:
- Local
- 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
- 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 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:
- NumRetries
- 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:

`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:
- CaCertificateProviderInstance
- 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:

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:
- HeaderName
- 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.

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` Enterprise

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

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

`spec.jsonWebKeySet.local`

Values

Default: None
Data type: Map that can contain one of the following parameters:
- jwks
- 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 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`

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
- 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:

`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`

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:
- caCertificateProviderInstance
- 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:

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`

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:
- headerName
- padForwardPayloadHeader

`spec.forwarding.headerName`

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`

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