Skip to main content

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 (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.
ParameterTypeDescription
namestringMust be set to envoy.filters.http.jwt_authn.
prioritynumberUsed for ordering multiple filters defined in the GVC and Workload.
typed_config."@type"stringMust be set to type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication.
typed_config.providersobjectA map of JWT provider configurations. Keys starting with cpln_ are restricted and will be displayed in the UI.
typed_config.rulesobjectA 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:
ParameterTypeDescription
issuerstringThe URL of the domain that issued the JWT.
audiencesstring[]The audiences that are accepted for the JWT.
claim_to_headersobject[]Specifies which claims should be added to headers.
remote_jwksobjectConfiguration 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.
ParameterTypeDescription
header_namestringThe name of the header to add.
claim_namestringThe name of the claim to extract from the JWT.

​
Remote JWKS

Configuration for JWT public key resolution and cache behavior.
ParameterTypeDescription
http_uriobjectThe HTTP URI configuration for the JWKS public key lookup.
cache_durationstringDuration 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.
ParameterTypeDescription
uristringThe endpoint use to lookup the JWKS public key.
clusterstringThe cluster name used for the JWKS public key. must match the Cluster for this Provider.
timeoutstringTimeout 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.
ParameterTypeDescription
matchstringThe issuer of the JWT.
match.headersstring[]An optional list of headers that must exist in the request for this match
match.prefixstringA required URI prefix for this match.
requires.provider_namestringThe 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