mirror of https://github.com/status-im/consul.git
[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>
This commit is contained in:
John Maguire
GitHub
parent
5a74bb6d5a
commit
e601d7e0e9
|
|
@ -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:
|
||||
|
||||
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.
|
||||
- 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 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
|
||||
The following example configures an HTTPRoute so that every request to `api-gateway-fqdn:3002/admin` must meet these conditions:
|
||||
|
||||
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:
|
||||
- The request be signed by the `local` provider.
|
||||
- The request must have a `role` claim.
|
||||
- The value of the claim must be `admin`.
|
||||
|
||||
```shell-session
|
||||
$ kubectl apply -f jwt-routes
|
||||
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>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
## 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"
|
||||
|
||||
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
|
||||
|
||||
Define default and override settings for JWT verification in the [API gateway configuration entry](/consul/docs/connect/gateways/api-gateway/configuration/api-gateway).
|
||||
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).
|
||||
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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue