[NET-7787] Update JWT docs for APIGateway (#20800)

* Update k8s docs * Update jwt docs with examples * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update docs to follow style guide, use CodeBlockConfig, remove section to apply the configuration for k8s docs * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> * Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx Co-authored-by: Jeff Boruszak <[email protected]> --------- Co-authored-by: Jeff Boruszak <[email protected]>
hashicorp · Jul 24, 2024 · e601d7e · e601d7e
1 parent 5a74bb6
commit e601d7e
Show file tree

Hide file tree

Showing 2 changed files with 314 additions and 23 deletions.
diff --git a/...te/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx b/...te/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx
@@ -14,16 +14,17 @@ This topic describes how to use JSON web tokens (JWT) to verify requests to API
 
 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 that apply to all routes attached to a listener.
+- 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 that take precedence over default and route-specific configurations. This enables you to set enforceable policies for listeners.
+- 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 policy that specifies default and override settings for API gateway listeners and attach it to the gateway.
-1. Define an HTTP route auth filter that specifies route-specific JWT verification settings.
-1. Attach the auth filter to the HTTP route values file.
+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.
 
 
@@ -33,9 +34,34 @@ Complete the following steps to use JWTs to verify requests:
 - Consul on Kubernetes CLI or Helm chart v1.3.0+
 - JWT details, such as claims and provider
 
-## Define override and default settings
 
-Create a `GatewayPolicy` values file and configure the following fields to define default and override settings for JWT verification. Refer to [`GatewayPolicy` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/gatewaypolicy) for details.
+## 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.
@@ -46,29 +72,155 @@ Create a `GatewayPolicy` values file and configure the following fields to defin
 - `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.
 
-## Define an HTTP route auth filter
+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` values file and configure the following fields. Refer to [`RouteAuthFilter` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routeauthfilter) for details.
+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 HTTP route configuration, add the following fields. Refer to the [`extensionRef` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes#rules-filters-extensionref) for details:
+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.
 
-## Apply the configurations
-
-Run the `kubectl apply` command and specify the values files to apply the configurations. The following example applies the values files stored in the `jwt-routes` directory:
-
-```shell-session
-$ kubectl apply -f jwt-routes
+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>
diff --git a/...te/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx b/...te/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx
@@ -20,6 +20,7 @@ You can configure API gateways to use JWTs to verify incoming requests so that y
 
 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. Configure default and override settings for listeners in the API gateway configuration entry.
 1. Define route-specific JWT verification settings as filters in the HTTP route configuration entries.
 1. Write the configuration entries to Consul to begin verifying requests using JWTs.
@@ -29,17 +30,155 @@ Complete the following steps to use JWTs to verify requests:
 - Consul 1.17 or later
 - JWT details, such as claims and provider
 
-## Configure default and override settings
+## Define a JWTProvider
+
+Create a JWTProvider config entry 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.hcl">
+
+```hcl
+Kind = "jwt-provider"
+Name = "local"
+
+Issuer = "local"
 
-Define default and override settings for JWT verification in the [API gateway configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway). 
+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).
+
+## Configure default and override settings
 
-1. Add a `default.JWT` block to the listener that you want to apply JWT verification to. Consul applies these configurations to routes attached to the listener. Refer to the [`Listeners.default.JWT`](/consul/docs/connect/config-entries/api-gateway#listeners-default-jwt) configuration reference for details. 
-1. Add an `override.JWT` block to the listener that you want to apply JWT verification policies to. Consul applies these configurations to all routes attached to the listener, regardless of the `default` or route-specific settings. Refer to the [`Listeners.override.JWT`](/consul/docs/connect/config-entries/api-gateway#listeners-override-jwt) configuration reference for details. 
-1. Apply the settings in the API gateway configuration entry. You can use the [`/config` API endpoint](/consul/api-docs/config#apply-configuration) or the [`consul config write` command](/consul/commands/config/write). 
+Define default and override settings for JWT verification in the [API gateway configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway).
+
+1. Add a `default.JWT` block to the listener that you want to apply JWT verification to. Consul applies these configurations to routes attached to the listener. Refer to the [`Listeners.default.JWT`](/consul/docs/connect/config-entries/api-gateway#listeners-default-jwt) configuration reference for details.
+1. Add an `override.JWT` block to the listener that you want to apply JWT verification policies to. Consul applies these configurations to all routes attached to the listener, regardless of the `default` or route-specific settings. Refer to the [`Listeners.override.JWT`](/consul/docs/connect/config-entries/api-gateway#listeners-override-jwt) configuration reference for details.
+1. Apply the settings in the API gateway configuration entry. You can use the [`/config` API endpoint](/consul/api-docs/config#apply-configuration) or the [`consul config write` command](/consul/commands/config/write).
+
+The following examples configure a Gateway 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
+
+<CodeBlockConfig filename="gateway.hcl">
+
+```hcl
+Kind = "api-gateway"
+Name = "api-gateway"
+Listeners = [
+  {
+    Name     = "listener-one"
+    Port     = 9001
+    Protocol = "http"
+    Override = {
+      JWT = {
+        Providers = [
+          {
+            Name = "local"
+          }
+        ]
+      }
+    }
+    default = {
+      JWT = {
+        Providers = [
+          {
+            Name = "local"
+            VerifyClaims = [
+              {
+                Path  = ["role"]
+                Value = "pet"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }
+]
+```
+
+</CodeBlockConfig>
 
 ## Configure verification for specific HTTP routes
 
-Define filters to enable route-specific JWT verification settings in the [HTTP route configuration entry](/consul/docs/connect/config-entries/http-route). 
+Define filters to enable route-specific JWT verification settings in the [HTTP route configuration entry](/consul/docs/connect/config-entries/http-route).
 
 1. Add a `JWT` configuration to the `rules.filter` block. Route-specific configurations that overlap the [default settings ](/consul/docs/connect/config-entries/api-gateway#listeners-default-jwt) in the API gateway configuration entry take precedence. Configurations defined in the [listener override settings](/consul/docs/connect/config-entries/api-gateway#listeners-override-jwt) take the highest precedence.
-1. Apply the settings in the API gateway configuration entry. You can use the [`/config` API endpoint](/consul/api-docs/config#apply-configuration) or the [`consul config write` command](/consul/commands/config/write). 
+1. Apply the settings in the API gateway configuration entry. You can use the [`/config` API endpoint](/consul/api-docs/config#apply-configuration) or the [`consul config write` command](/consul/commands/config/write).
+
+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 Gateway listener.
+
+<CodeBlockConfig filename="http-route.hcl">
+
+```hcl
+Kind = "http-route"
+Name = "api-gateway-route"
+Parents = [
+  {
+    SectionName = "listener-one"
+    Name        = "api-gateway"
+    Kind        = "api-gateway"
+  },
+]
+Rules = [
+  {
+    Matches = [
+      {
+        Path = {
+          Match = "prefix"
+          Value = "/admin"
+        }
+      }
+    ]
+    Filters = {
+      JWT = {
+        Providers = [
+          {
+            Name = "local"
+            VerifyClaims = [
+              {
+                Path  = ["role"]
+                Value = "admin"
+              }
+            ]
+          }
+        ]
+      }
+    }
+    Services = [
+      {
+        Name = "admin-service"
+      }
+    ]
+  },
+  {
+    Matches = [
+      {
+        Path = {
+          Match = "prefix"
+          Value = "/"
+        }
+      }
+    ]
+    Services = [
+      {
+        Name = "user-service"
+      }
+    ]
+  },
+]
+```
+
+</CodeBlockConfig>