JWT Authentication

    JWKS is needed to verify JWT signatures. They can be specified in the filter config or can be fetched remotely from a JWKS server.

    Following are supported JWT alg:

    This filter should be configured with the name envoy.filters.http.jwt_authn.

    This HTTP has two fields:

    • Field providers specifies how a JWT should be verified, such as where to extract the token, where to fetch the public key (JWKS) and where to output its payload.

    • Field rules specifies matching rules and their requirements. If a request matches a rule, its requirement applies. The requirement specifies which JWT providers should be used.

    specifies how a JWT should be verified. It has the following fields:

    • issuer: the principal that issued the JWT, usually a URL or an email address.

    • audiences: a list of JWT audiences allowed to access. A JWT containing any of these audiences will be accepted. If not specified, the audiences in JWT will not be checked.

    • local_jwks: fetch JWKS in local data source, either in a local file or embedded in the inline string.

    • remote_jwks: fetch JWKS from a remote HTTP server, also specify cache duration.

    • forward: if true, JWT will be forwarded to the upstream.

    • from_params: extract JWT from query parameters.

    • from_cookies: extract JWT from HTTP request cookies.

    • forward_payload_header: forward the JWT payload in the specified HTTP header.

    • jwt_cache_config: Enables JWT cache, its size can be specified by jwt_cache_size. Only valid JWT tokens are cached.

    Default Extract Location

    If from_headers and from_params is empty, the default location to extract JWT is from HTTP header:

    and query parameter key access_token as:

    1. /path?access_token=<JWT>

    If a request has two tokens, one from the header and the other from the query parameter, all of them must be valid.

    In the , providers is a map, to map provider_name to a JwtProvider. The provider_name must be unique, it is referred in the JwtRequirement <envoy_v3_api_msg_extensions.filters.http.jwt_authn.v3.JwtRequirement> in its provider_name field.

    Important

    For remote_jwks, a jwks_cluster cluster is required.

    Due to above requirement, is not supported since the URL to fetch JWKS is in the response of the discovery. It is not easy to setup a cluster config for a dynamic URL.

    Above example fetches JWKS from a remote server with URL . The token will be extracted from the default extract locations. The token will not be forwarded to upstream. JWT payload will not be added to the request header.

    1. cluster:
    2.   name: example_jwks_cluster
    3.   load_assignment:
    4.     cluster_name: example_jwks_cluster
    5.     endpoints:
    6.     - lb_endpoints:
    7.       - endpoint:
    8.           address:
    9.             socket_address:
    10.               address: example.com
    11.               port_value: 443
    12.   transport_socket:

    Inline JWKS config example

    Another config example using inline JWKS:

    1. providers:
    2.   provider_name2:
    3.     issuer: https://example2.com
    4.     local_jwks:
    5.       inline_string: PUBLIC-KEY
    6.     from_headers:
    7.     - name: jwt-assertion
    8.     forward: true
    9.     forward_payload_header: x-jwt-payload

    Above example uses config inline string to specify JWKS. The JWT token will be extracted from HTTP headers as:

    JWT payload will be added to the request header as following format:

    1. x-jwt-payload: base64url_encoded(jwt_payload_in_JSON)

    RequirementRule has two fields:

    • Field match specifies how a request can be matched; e.g. by HTTP headers, or by query parameters, or by path prefixes.

    • Field requires specifies the JWT requirement, e.g. which provider is required.

    Important

    • If a request matches multiple rules, the first matched rule will apply.

    • If a request doesn’t match any rules, JWT verification is not required.

    Single requirement config example

    1. providers:
    2.   jwt_provider1:
    3.     issuer: https://example.com
    4.     audiences:
    6.     local_jwks:
    7.       inline_string: PUBLIC-KEY
    8. rules:
    9. - match:
    10.     prefix: /health
    11. - match:
    12.     prefix: /api
    13.   requires:
    14.     provider_and_audiences:
    15.       provider_name: jwt_provider1
    16.       audiences:
    17.         api_audience
    18. - match:
    19.     prefix: /
    21.     provider_name: jwt_provider1

    Above config uses single requirement rule, each rule may have either an empty requirement or a single requirement with one provider name.

    Above config uses more complex group requirements:

    • The second rule specifies requires_all; only if both provider1 and provider2 requirements are satisfied, the request is OK to proceed.