> ## Documentation Index > Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt > Use this file to discover all available pages before exploring further. # JWT Authentication > Configure JWT providers, claim-to-header mappings, and rules to validate and authenticate JSON Web Tokens in HTTP requests to workloads. JWT (JSON Web Token) Authentication is a security feature that allows you to validate and authenticate JSON tokens in HTTP requests. Multiple JWT providers can be configured for use. [Claims](/reference/workload/jwt-auth#claim-to-headers) inside the JWT can be assigned to headers that will be included in the request received by the Workloads. [Rules](/reference/workload/jwt-auth#rules) are used to define which requests must provide valid tokens and from which Provider. ## Configuration JWT Authentication is configured as part of the Workload or GVC `sidecar.envoy` settings, specifically within the `http` filters array. The configuration includes a name, a typed config, and providers for JWT authentication. When configured on the GVC layer, the settings are applied to all Workloads in the GVC. | Parameter | Type | Description | | :----------------------- | :----- | :--------------------------------------------------------------------------------------------------------------- | | `name` | string | Must be set to `envoy.filters.http.jwt_authn`. | | `priority` | number | Used for ordering multiple filters defined in the GVC and Workload. | | `typed_config."@type"` | string | Must be set to `type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication`. | | `typed_config.providers` | object | A map of JWT provider configurations. Keys starting with `cpln_` are restricted and will be displayed in the UI. | | `typed_config.rules` | object | A set of rules to control which paths and headers require a valid JWT and from which provider. | ## JWT Provider Configuration Each JWT Provider is configured using a dictionary key of the provider name and the following parameters: | Parameter | Type | Description | | :----------------- | :-------- | :-------------------------------------------------------------------------------------------- | | `issuer` | string | The URL of the domain that issued the JWT. | | `audiences` | string\[] | The audiences that are accepted for the JWT. | | `claim_to_headers` | object\[] | Specifies which claims should be added to headers. | | `remote_jwks` | object | Configuration for [remote JWKS](/reference/workload/jwt-auth#remote-jwks) (JSON Web Key Set). | ### Claim to Headers Each object represents a mapping between claims in the JWT and the header. It will be mapped to when the request is forwarded to the workload. | Parameter | Type | Description | | :------------ | :----- | :--------------------------------------------- | | `header_name` | string | The name of the header to add. | | `claim_name` | string | The name of the claim to extract from the JWT. | ### Remote JWKS Configuration for JWT public key resolution and cache behavior. | Parameter | Type | Description | | :--------------- | :----- | :------------------------------------------------------------------------------------------------------- | | `http_uri` | object | The [HTTP URI](/reference/workload/jwt-auth#http-uri) configuration for the JWKS public key lookup. | | `cache_duration` | string | Duration to cache the JWKS. Must be in the format "Ns" where N is the number of seconds. Example `300s`. | #### HTTP URI The JWKS public key lookup for this Provider. | Parameter | Type | Description | | :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------- | | `uri` | string | The endpoint use to lookup the JWKS public key. | | `cluster` | string | The cluster name used for the JWKS public key. must match the [Cluster](/reference/workload/jwt-auth#clusters) for this Provider. | | `timeout` | string | Timeout for the JWKS request. Must be in the format "Ns" where N is the number of seconds. Example `10s`. | ## Rules Rules are evaluated in order using details from the request. The first matching rule will be used. | Parameter | Type | Description | | :----------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------- | | `match` | string | The issuer of the JWT. | | `match.headers` | string\[] | An optional list of headers that must exist in the request for this match | | `match.prefix` | string | A required URI prefix for this match. | | `requires.provider_name` | string | The optional JWT Provider to use for JWT Verification of this match. All requests are allowed when not specified. | ## Clusters A Cluster for each provider is required to detail out how the request will be made to the JWT Provider. Since most providers must use `https` the cluster configuration will be similar to the following. Replace `${providerName}` with the name of the provider. Replace `${providerEndpoint}` with the endpoint of the provider, ex `mydomain.auth.us-east-1.amazoncognito.com`. ```yaml theme={null} clusters: - name: cpln_${providerName} type: STRICT_DNS load_assignment: cluster_name: cpln_${providerName} endpoints: - lb_endpoints: - endpoint: address: socket_address: address: ${providerEndpoint} port_value: 443 transport_socket: name: envoy.transport_sockets.tls ``` ## Notes * Provider names starting with "cpln\_" are configured by the UI and will have more restricted configurations. * The `cache_duration` and `http_uri.timeout` must be equal when configured using the UI. * All settings are available from envoyproxy [JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto) when configured manually, contact support for details. ## Example Configuration ```yaml theme={null} sidecar: envoy: clusters: - name: cpln_foo type: STRICT_DNS load_assignment: cluster_name: cpln_foo endpoints: - lb_endpoints: - endpoint: address: socket_address: address: foo.com port_value: 443 transport_socket: name: envoy.transport_sockets.tls http: - name: envoy.filters.http.jwt_authn priority: 50 typed_config: '@type': >- type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication providers: cpln_foo: audiences: - myaudience claim_to_headers: - claim_name: user.special header_name: X_SPECIAL_USER issuer: https://foo.com/auth remote_jwks: cache_duration: 5s http_uri: cluster: cpln_foo timeout: 5s uri: https://foo.com/auth rules: - match: headers: [] prefix: /metric - match: headers: [] prefix: / requires: provider_name: cpln_foo ```