mirror of https://github.com/hashicorp/consul
227 lines
7.9 KiB
Markdown
227 lines
7.9 KiB
Markdown
---
|
|
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).
|
|
|
|
<EnterpriseAlert> This feature is available in Consul Enterprise. </EnterpriseAlert>
|
|
|
|
## 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.
|
|
|
|
<CodeBlockConfig filename="jwt-provider.yaml">
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: JWTProvider
|
|
metadata:
|
|
name: local
|
|
spec:
|
|
issuer: local
|
|
jsonWebKeySet:
|
|
local:
|
|
jwks: "<JWKS-Key>"
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
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
|
|
|
|
<Tabs>
|
|
<Tab heading="Gateway">
|
|
|
|
<CodeBlockConfig filename="gateway.yaml">
|
|
|
|
```yaml
|
|
apiVersion: gateway.networking.k8s.io/v1beta1
|
|
kind: Gateway
|
|
metadata:
|
|
name: api-gateway
|
|
spec:
|
|
gatewayClassName: consul
|
|
listeners:
|
|
- protocol: HTTP
|
|
port: 30002
|
|
name: listener-one
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
</Tab>
|
|
|
|
<Tab heading="GatewayPolicy">
|
|
|
|
<CodeBlockConfig filename="gateway-policy.yaml">
|
|
|
|
```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
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
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`
|
|
|
|
<CodeBlockConfig filename="route-auth-filter.yaml">
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: RouteAuthFilter
|
|
metadata:
|
|
name: auth-filter
|
|
spec:
|
|
jwt:
|
|
providers:
|
|
- name: local
|
|
verifyClaims:
|
|
- path:
|
|
- role
|
|
value: admin
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
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.
|
|
|
|
<CodeBlockConfig filename="http-route.yaml">
|
|
|
|
```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
|
|
```
|
|
|
|
</CodeBlockConfig>
|