---
layout: docs
page_title: Use JWTs to verify requests to API gateways on Kubernetes
description: Learn how to use JSON web tokens (JWT) to verify requests from external clients to listeners on an API gateway on Kubernetes-orchestrated networks.
---
# Use JWTs to verify requests to API gateways on Kubernetes
This topic describes how to use JSON web tokens (JWT) to verify requests to API gateways deployed to Kubernetes-orchestrated containers. If your API gateway is deployed to virtual machines, refer to [Use JWTs to verify requests to API gateways on VMs](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms).
This feature is available in Consul Enterprise.
## Overview
You can configure API gateways to use JWTs to verify incoming requests so that you can stop unverified traffic at the gateway. You can configure JWT verification at different levels:
- Listener defaults: Define basic defaults in a GatewayPolicy resource to apply them to all routes attached to a listener.
- HTTP route-specific settings: You can define JWT authentication settings for specific HTTP routes. Route-specific JWT settings override default listener configurations.
- Listener overrides: Define override settings in a GatewayPolicy resource that take precedence over default and route-specific configurations. Use override settings to set enforceable policies for listeners.
Complete the following steps to use JWTs to verify requests:
1. Define a JWTProvider that specifies the JWT provider and claims used to verify requests to the gateway.
1. Define a GatewayPolicy that specifies default and override settings for API gateway listeners and attach it to the gateway.
1. Define a RouteAuthFilter that specifies route-specific JWT verification settings.
1. Reference the RouteAuthFilter from the HTTPRoute.
1. Apply the configurations.
## Requirements
- Consul v1.17+
- Consul on Kubernetes CLI or Helm chart v1.3.0+
- JWT details, such as claims and provider
## Define a JWTProvider
Create a `JWTProvider` CRD that defines the JWT provider to verify claims against.
In the following example, the JWTProvider CRD contains a local JWKS. In production environments, use a production-grade JWKs endpoint instead.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: JWTProvider
metadata:
name: local
spec:
issuer: local
jsonWebKeySet:
local:
jwks: ""
```
For more information about the fields you can configure in this CRD, refer to [`JWTProvider` configuration reference](/consul/docs/connect/config-entries/jwtprovider).
## Define a GatewayPolicy
Create a `GatewayPolicy` CRD that defines default and override settings for JWT verification.
- `kind`: Must be set to `GatewayPolicy`
- `metadata.name`: Specifies a name for the policy.
- `spec.targetRef.name`: Specifies the name of the API gateway to attach the policy to.
- `spec.targetRef.kind`: Specifies the kind of resource to attach to the policy to. Must be set to `Gateway`.
- `spec.targetRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.k8s.io/v1beta1`.
- `spec.targetRef.sectionName`: Specifies a part of the gateway that the policy applies to.
- `spec.targetRef.override.jwt.providers`: Specifies a list of providers and claims used to verify requests to the gateway. The override settings take precedence over the default and route-specific JWT verification settings.
- `spec.targetRef.default.jwt.providers`: Specifies a list of default providers and claims used to verify requests to the gateway.
The following examples configure a Gateway and the GatewayPolicy being attached to it so that every request coming through the listener must meet these conditions:
- The request must be signed by the `local` provider
- The request must have a claim of `role` with a value of `user` unless the HTTPRoute attached to the listener overrides it
```yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
name: api-gateway
spec:
gatewayClassName: consul
listeners:
- protocol: HTTP
port: 30002
name: listener-one
```
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: GatewayPolicy
metadata:
name: gw-policy
spec:
targetRef:
name: api-gateway
sectionName: listener-one
group: gateway.networking.k8s.io/v1beta1
kind: Gateway
override:
jwt:
providers:
- name: "local"
default:
jwt:
providers:
- name: "local"
verifyClaims:
- path:
- role
value: user
```
For more information about the fields you can configure, refer to [`GatewayPolicy` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/gatewaypolicy).
## Define a RouteAuthFilter
Create an `RouteAuthFilter` CRD that defines overrides for the default JWT verification configured in the GatewayPolicy.
- `kind`: Must be set to `RouteAuthFilter`
- `metadata.name`: Specifies a name for the filter.
- `metadata.namespace`: Specifies the Consul namespace the filter applies to.
- `spec.jwt.providers`: Specifies a list of providers and claims used to verify requests to the gateway. The override settings take precedence over the default and route-specific JWT verification settings.
In the following example, the RouteAuthFilter overrides default settings set in the GatewayPolicy so that every request coming through the listener must meet these conditions:
- The request must be signed by the `local` provider
- The request must have a `role` claim
- The value of the claim must be `admin`
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteAuthFilter
metadata:
name: auth-filter
spec:
jwt:
providers:
- name: local
verifyClaims:
- path:
- role
value: admin
```
For more information about the fields you can configure, refer to [`RouteAuthFilter` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routeauthfilter).
## Attach the auth filter to your HTTP routes
In the `filters` field of your HTTPRoute configuration, define the filter behavior that results from JWT verification.
- `type: extensionRef`: Declare list of extension references.
- `extensionRef.group`: Specifies the resource group. Unless you have created a custom group, this should be set to `gateway.networking.k8s.io/v1beta1`.
- `extensionRef.kind`: Specifies the type of extension reference to attach to the route. Must be `RouteAuthFilter`
- `extensionRef.name`: Specifies the name of the auth filter.
The following example configures an HTTPRoute so that every request to `api-gateway-fqdn:3002/admin` must meet these conditions:
- The request be signed by the `local` provider.
- The request must have a `role` claim.
- The value of the claim must be `admin`.
Every other request must be signed by the `local` provider and have a claim of `role` with a value of `user`, as defined in the GatewayPolicy.
```yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: http-route
spec:
parentRefs:
- name: api-gateway
rules:
- matches:
- path:
type: PathPrefix
value: /admin
filters:
- type: ExtensionRef
extensionRef:
group: consul.hashicorp.com
kind: RouteAuthFilter
name: auth-filter
backendRefs:
- kind: Service
name: admin
port: 8080
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- kind: Service
name: user-service
port: 8081
```