--- 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.kubernetes.io`. - `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.kubernetes.io`. - `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 ```