github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

[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 <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* 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 <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* Update website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

---------

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
pull/21562/head
John Maguire 4 months ago committed by GitHub
parent
5a74bb6d5a
commit
e601d7e0e9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 314 additions and 23 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 184
      website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx
  2. 153
      website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx

184
website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s.mdx
Unescape View File

@ -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>

153
website/content/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms.mdx
Unescape View File

@ -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>

Write Preview
Loading…
Cancel
Save