JWT Authentication

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 inside the JWT can be assigned to headers that will be included in the request received by the Workloads. 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 (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 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 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.

      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 when configured manually, contact support for details.

Example Configuration

  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

Documentation

Quickstart

Concepts

Core

Reference

Configuration

JWT Provider Configuration

Claim to Headers

Remote JWKS

HTTP URI

Rules

Clusters

Notes

Example Configuration

​Configuration

​JWT Provider Configuration

​Claim to Headers

​Remote JWKS

​HTTP URI

​Rules

​Clusters

​Notes

​Example Configuration

Configuration

JWT Provider Configuration

Claim to Headers

Remote JWKS

HTTP URI

Rules

Clusters

Notes

Example Configuration