github.com/projectcontour/contour@v1.28.2/site/content/docs/1.27/config/jwt-verification.md (about)

     1  # JWT Verification
     2  
     3  Contour supports verifying JSON Web Tokens (JWTs) on incoming requests, using Envoy's [jwt_authn HTTP filter][1].
     4  Specifically, the following properties can be checked:
     5  - issuer field
     6  - audiences field
     7  - signature, using a configured JSON Web Key Store (JWKS)
     8  - time restrictions (e.g. expiration, not before time)
     9  
    10  If verification succeeds, the request will be proxied to the appropriate upstream.
    11  If verification fails, an HTTP 401 (Unauthorized) will be returned to the client.
    12  
    13  JWT verification is only supported on TLS-terminating virtual hosts.
    14  
    15  ## Configuring providers and rules
    16  
    17  A JWT provider is configured for an HTTPProxy's virtual host, and defines how to verify JWTs:
    18  
    19  ```yaml
    20  apiVersion: projectcontour.io/v1
    21  kind: HTTPProxy
    22  metadata:
    23    name: jwt-verification
    24    namespace: default
    25  spec:
    26    virtualhost:
    27      fqdn: example.com
    28      tls:
    29        secretName: example-com-tls-cert
    30      jwtProviders:
    31        - name: provider-1
    32          issuer: example.com
    33          audiences:
    34            - audience-1
    35            - audience-2
    36          remoteJWKS:
    37            uri: https://example.com/jwks.json
    38            timeout: 1s
    39            cacheDuration: 5m
    40          forwardJWT: true
    41    routes:
    42      ...
    43  ```
    44  
    45  The provider above requires JWTs to have an issuer of example.com, an audience of either audience-1 or audience-2, and a signature that can be verified using the configured JWKS.
    46  It also forwards the JWT to the backend via the `Authorization` header after successful verification.
    47  
    48  To apply a JWT provider as a requirement to a given route, specify a `jwtVerificationPolicy` for the route:
    49  
    50  ```yaml
    51  apiVersion: projectcontour.io/v1
    52  kind: HTTPProxy
    53  metadata:
    54    name: jwt-verification
    55    namespace: default
    56  spec:
    57    virtualhost:
    58      fqdn: example.com
    59      tls:
    60        secretName: example-com-tls-cert
    61      jwtProviders:
    62        - name: provider-1
    63          ...
    64    routes:
    65      - conditions:
    66          - prefix: /
    67        jwtVerificationPolicy:
    68          require: provider-1
    69        services:
    70          - name: s1
    71            port: 80
    72      - conditions:
    73          - prefix: /css
    74        services:
    75          - name: s1
    76            port: 80
    77  ```
    78  
    79  In the above example, the default route requires requests to carry JWTs that can be verified using provider-1.
    80  The second route _excludes_ requests to paths starting with `/css` from JWT verification, because it does not have a JWT verification policy.
    81  
    82  ### Configuring TLS validation for the JWKS server
    83  
    84  By default, the JWKS server's TLS certificate will not be validated, but validation can be requested by setting the `spec.virtualhost.jwtProviders[].remoteJWKS.validation` field.
    85  This field has mandatory `caSecret` and `subjectName` fields, which specify the trusted root certificates with which to validate the server certificate and the expected server name.
    86  The `caSecret` can be a namespaced name of the form `<namespace>/<secret-name>`.
    87  If the CA secret's namespace is not the same namespace as the `HTTPProxy` resource, [TLS Certificate Delegation][5] must be used to allow the owner of the CA certificate secret to delegate, for the purposes of referencing the CA certificate in a different namespace, permission to Contour to read the Secret object from another namespace.
    88  
    89  **Note:** If `spec.virtualhost.jwtProviders[].remoteJWKS.validation` is present, `spec.virtualhost.jwtProviders[].remoteJWKS.uri` must have a scheme of `https`.
    90  
    91  ## Setting a default provider
    92  
    93  The previous section showed how to explicitly require JWT providers for specific routes.
    94  An alternate approach is to define a JWT provider as the default by specifying `default: true` for it, in which case it is automatically applied to all routes unless they disable JWT verification.
    95  The example from the previous section could alternately be configured as follows:
    96  
    97  ```yaml
    98  apiVersion: projectcontour.io/v1
    99  kind: HTTPProxy
   100  metadata:
   101    name: jwt-verification
   102    namespace: default
   103  spec:
   104    virtualhost:
   105      fqdn: example.com
   106      tls:
   107        secretName: example-com-tls-cert
   108      jwtProviders:
   109        - name: provider-1
   110          default: true
   111          ...
   112    routes:
   113      - conditions:
   114          - prefix: /
   115        services:
   116          - name: s1
   117            port: 80
   118      - conditions:
   119          - prefix: /css
   120        jwtVerificationPolicy:
   121          disabled: true
   122        services:
   123          - name: s1
   124            port: 80
   125  ```
   126  
   127  In this case, the default route automatically has provider-1 applied, while the `/css` route explicitly disables JWT verification.
   128  
   129  One scenario where setting a default provider can be particularly useful is when using [HTTPProxy inclusion][2].
   130  Setting a default provider in the root HTTPProxy allows all routes in the child HTTPProxies to automatically have JWT verification applied.
   131  For example:
   132  
   133  ```yaml
   134  apiVersion: projectcontour.io/v1
   135  kind: HTTPProxy
   136  metadata:
   137    name: jwt-verification-root
   138    namespace: default
   139  spec:
   140    virtualhost:
   141      fqdn: example.com
   142      tls:
   143        secretName: example-com-tls-cert
   144      jwtProviders:
   145        - name: provider-1
   146          default: true
   147          ...
   148    includes:
   149      - name: jwt-verification-child
   150        namespace: default
   151        conditions:
   152          - prefix: /blog
   153  ---
   154  apiVersion: projectcontour.io/v1
   155  kind: HTTPProxy
   156  metadata:
   157    name: jwt-verification-child
   158    namespace: default
   159  spec:
   160    routes:
   161      - conditions:
   162          - prefix: /
   163        services:
   164          - name: s1
   165            port: 80
   166  ```
   167  
   168  In this case, all routes in the child HTTPProxy will automatically have JWT verification applied, without the owner of this HTTPProxy needing to configure it explicitly.
   169  
   170  ## API documentation
   171  
   172  For more information on the HTTPProxy API for JWT verification, see:
   173  
   174  - [JWTProvider][3]
   175  - [JWTVerificationPolicy][4]
   176  
   177  
   178  [1]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter
   179  [2]: /docs/{{< param version >}}/config/inclusion-delegation/
   180  [3]: /docs/{{< param version >}}/config/api/#projectcontour.io/v1.JWTProvider
   181  [4]: /docs/{{< param version >}}/config/api/#projectcontour.io/v1.JWTVerificationPolicy
   182  [5]: tls-delegation.md