From 33cede6ea5c96b12561fba7d98a201eb50aaf2c7 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 13:59:52 -0700 Subject: [PATCH] Usage + fixes --- .../connect/config-entries/jwt-provider.mdx | 16 +++-- .../connect/intentions/jwt-authorization.mdx | 65 ++++++++++++++++--- 2 files changed, 64 insertions(+), 17 deletions(-) diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index a3c7369c4c..273ebf16f1 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -1,12 +1,12 @@ --- page_title: JWT provider configuration entry reference description: |- - + JWT provider configuration entries add JSON Web Token token validation to intentions in the service mesh. Learn how to write `jwt-provider` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case. --- # JWT provider configuration entry reference -This page provides reference information for the JWT provider configuration entry, which configures a JSON Web Token (JWT) and JSON Web Key Set (JWKS) for Consul. JWT provider configuration entries are used to add JWT validation to proxies in the service mesh. Refer to [Use JWT authorization with service intentions](/consul/docs/connect/intentions/jwt-authorization) for more information. +This page provides reference information for the JWT provider configuration entry, which configures Consul to use a JSON Web Token (JWT) and JSON Web Key Set (JWKS) in order to add JWT validation to proxies in the service mesh. Refer to [Use JWT authorization with service intentions](/consul/docs/connect/intentions/jwt-authorization) for more information. ## Configuration model @@ -173,7 +173,7 @@ CacheConfig = { "NumRetries": "0" } } -} +}, "Audiences": [""], "Locations": [ { @@ -193,7 +193,7 @@ CacheConfig = { "Name": "" } } -] +], "Forwarding": { "HeaderName": "", "PadForwardPayloadHeader": "false" @@ -205,6 +205,8 @@ CacheConfig = { } ``` + + ```yaml @@ -403,7 +405,7 @@ Specifies a set of audiences that the JWT is allowed to access, formatted as a l - Default: None - Data type: List of strings -- + ### `Locations` Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT. @@ -459,7 +461,7 @@ For example, `Bearer` is a standard value prefix for a header named "Authorizati Specifies whether the header with the JWT is forwarded after the token is verified. When set to false, the header is not forwarded. -- Default value is false. +The default value is false. #### Values @@ -517,7 +519,7 @@ The header value is base64 URL encoded. It is not padded by default. ### `Forwarding{}.PadForwardPayloadHeader` -Determines whether to add padding to the base64 encoded token specified in [Forwarding{}.HeaderName`](#forwarding-header-name). +Determines whether to add padding to the base64 encoded token specified in [`Forwarding{}.HeaderName`](#forwarding-header-name). By default, this field is set to `false`. diff --git a/website/content/docs/connect/intentions/jwt-authorization.mdx b/website/content/docs/connect/intentions/jwt-authorization.mdx index e4e11e0961..9cf98c63cb 100644 --- a/website/content/docs/connect/intentions/jwt-authorization.mdx +++ b/website/content/docs/connect/intentions/jwt-authorization.mdx @@ -6,23 +6,17 @@ description: |- # Use JWT authorization with service intentions -JSON Web Tokens (JWT) are a method for identity-based access to services for both humans and machines. The JWT authorization configuration entry enables you to define JWTs as part of a JSON Web Token Set (JWTS), which contains the information necessary for Consul to validate access and configure behavior for requests with JWTs. +JSON Web Tokens (JWT) are a method for identity-based access to services for both humans and machines. The [JWT provider configuration entry](/consul/docs/connect/config-entries/jwt-provider) enables you to define JWTs as part of a JSON Web Key Set (JWKS), which contains the information necessary for Consul to validate access and configure behavior for requests that include JWTs. -By defining a JSON Web Key Set (JWKS) in the configuration entry and referencing the key set in a service intention, Consul can enforce service intentions based on the presence of a JWT. This security configuration is not related to the [JSON Web Token Auth Method](/consul/docs/security/acl/auth-methods/jwt), which associates JWTs with the Consul ACLs instead of service intentions. - -## Background +By specifying a JSON Web Key Set (JWKS) in the configuration entry and referencing the key set in a service intention, Consul can enforce service intentions based on the presence of a JWT. This security configuration is not related to the [JSON Web Token Auth Method](/consul/docs/security/acl/auth-methods/jwt), which associates JWTs with the Consul ACLs instead of service intentions. ## Workflow The process to configure your network to enforce service intentions based on JSON web tokens consists of the following steps: -Create a JWT provider configuration entry. This configuration entry defines rules and behaviors for verifying the token. These configurations apply at the level of the admin partition in Consul Enterprise, which is functionally equivalent to a datacenter in Consul OSS. +1. Create a JWT provider configuration entry. This configuration entry defines rules and behaviors for verifying tokens. These configurations apply at the level of the admin partition in Consul Enterprise, which is functionally equivalent to a datacenter in Consul OSS. Then, write the `jwt-provider` configuration entry to Consul. The ACL policy requirement to read and modify this configuration entry is `mesh:write`. -Write the `jwt-provider` configuration entry to Consul. The ACL policy requirement to read and modify this configuration entry is `mesh:write`. - -Create or update a service intentions configuration entry to reference the JWT provider. This configuration invokes the name of the `jwt-provider` configuration entry you created, causing the Envoy proxy to verify the token and the permissions it authorizes before the incoming request is accepted. - -Write the `service-intentions` configuration entry that references the JWT to Consul. The ACL policy requirement to read and modify this configuration entry is `mesh:write`. +1. Create or update a service intentions configuration entry to reference the JWT provider. This configuration invokes the name of the `jwt-provider` configuration entry you created, which causes the Envoy proxy to verify the token and the permissions it authorizes before the incoming request is accepted. Then, write the `service-intentions` configuration entry that references the JWT to Consul. The ACL policy requirement to read and modify this configuration entry is `mesh:write`. ### Wildcards and intention defaults @@ -33,3 +27,54 @@ When configuring your deployment to enforce service intentions with JSON Web Tok When you set the `JWT{}.Providers` field in a service intentions configuration entry to the wildcard `*`, you can configure default behavior for all services that present a token that matches an existing JWT provider configuration entry. In this configuration, services that have a valid token but do not have a more specific matching intention default to the behavior defined in the wildcard intention. ## Usage + +To configure Envoy proxies in the service mesh to validate JWTs before forwarding requests to servers, complete the following steps: + +### Create a JWT provider configuration entry + +The `jwt-provider` configuration requires the following fields: + +- `Kind`: This field must be set to `"jwt-provider"` +- `Name`: We recommend naming the configuration file after the JWT provider used in the configuration. +- `Issuer`: This field must match the token's `iss` claim + +You must also specify a JSON Web Key Set in the `JWKS` field. You can specify the JWKS as one of the following: + +- A local string +- A path to a local file +- A remote location specified with a URI + +A JWKS can be made available locally or remotely, but not both. In addition, a local JWKS must be specified as either a string or a path to the file containing the token. + +You can also specify where the JWT is located, a retry policy, and text to append to the header when forwarding the request after token validation. + +The following example configures Consul to fetch a JSON Web Token issued by Okta. Consul fetches the token from the URI and keeps it in its cache for 30 minutes before the token expires. After validation, the token is forwarded to the backend with `user-token` appended to the HTTP header. + +```hcl +Kind = "jwt-provider" +Name = "okta" + +Issuer = "okta" + +JWKS = { + Remote = { + URI = "https://dev-850216.okta.com/oauth2/default/v1/keys" + CacheDuration = "30m" + } +} + +Forwarding = { + HeaderName = "user-token" +} +``` + +Refer to [JWT provider configuration entry](/consul/docs/connect/config-entries/jwt-provider) for more information about the fields you can configure. + +To write the configuration entry to Consul, use the [`consul config write` command](/consul/commands/config/write): + +```shell-session +$ consul config write okta.hcl +``` + +### Update service intentions +