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.

    Attention

    ES256, ES384, ES512, HS256, HS384, HS512, RS256, RS384 and RS512 are supported for the JWT alg.

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

    This HTTP filter config 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.

    • from_headers: extract JWT from HTTP headers.

    • from_params: extract JWT from query parameters.

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

    Default Extract Location

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

    If fails to extract a JWT from above header, then check query parameter key access_token as in this example:

    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_api_msg_config.filter.http.jwt_authn.v2alpha.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.

    1. providers:
    2.   provider_name1:
    3.     issuer: https://example.com
    4.     audiences:
    5.     - bookstore_android.apps.googleusercontent.com
    6.     - bookstore_web.apps.googleusercontent.com
    7.     remote_jwks:
    8.       http_uri:
    9.         uri: https://example.com/jwks.json
    10.         cluster: example_jwks_cluster
    11.       cache_duration:

    Above example fetches JWSK from a remote server with URL https://example.com/jwks.json. 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.

    Following cluster example_jwks_cluster is needed to fetch JWKS.

    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

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

    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 the matched rule has empty requires field, JWT verification is not required.

    • 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:
    5.       audience1
    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.         api_audience
    17. - match:
    18.     prefix: /
    19.   requires:
    20.     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.

    2.   provider1:
    3.     issuer: https://provider1.com
    4.     local_jwks:
    5.       inline_string: PUBLIC-KEY
    6.   provider2:
    7.     issuer: https://provider2.com
    8.     local_jwks:
    9.       inline_string: PUBLIC-KEY
    10. rules:
    11. - match:
    12.     prefix: /any
    13.   requires:
    14.     requires_any:
    15.       requirements:
    16.       - provider_name: provider1
    17.       - provider_name: provider2
    18. - match:
    19.     prefix: /all
    20.   requires:
    21.     requires_all:
    22.       requirements:
    24.       - provider_name: provider2

    Above config uses more complex group requirements:

    • The first rule specifies requires_any; if any of provider1 or provider2 requirement is satisfied, the request is OK to proceed.