From 65561996d7207e5bdc1cd17c6b0e72c8a967269a Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 10:41:38 -0700 Subject: [PATCH 01/12] Initial page/nav creation --- .../connect/config-entries/jwt-provider.mdx | 329 ++++++++++++++++++ .../connect/intentions/jwt-authorization.mdx | 35 ++ website/data/docs-nav-data.json | 8 + 3 files changed, 372 insertions(+) create mode 100644 website/content/docs/connect/config-entries/jwt-provider.mdx create mode 100644 website/content/docs/connect/intentions/jwt-authorization.mdx diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx new file mode 100644 index 00000000000..6f25b0ef92a --- /dev/null +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -0,0 +1,329 @@ +--- +page_title: JWT authorization configuration entry reference +description: |- + +--- + +# JWT authorization configuration entry reference +[Description] + +## Configuration model + +The following list outlines field hierarchy, language-specific data types, and requirements in a JWT provider configuration entry. Click on a property name to view additional details, including default values. + + +[`Kind`](#kind): string | required | must be set to `jwt-provider` +[`Name`](#name): string | required +[`Issuer`](#issuer): string +[`JWKS`](#jwks): map +[`Local`](#jwks-local): map +[`String`](#jwks-local-string): string +[`Filename`](#jwks-local-filename): string +[`Remote`](#jwks-remote): map +[`URI`](#jwks-remote-uri): string +[`RequestTimeoutMs`](#jwks-remote-requesttimeoutms): integer | +[`CacheDuration`](#jwks-remote-cacheduration): string | `5m` +[`FetchAsynchronously`](#jwks-remote-fetchasynchronously): boolean | `false` +[`RetryPolicy`](#jwks-remote-retrypolicy): map +[`NumRetries`](#jwks-remote-retrypolicy): integer | `0` +[`Audiences`](#audiences): list of strings +[`Locations`](#locations): list of maps +[`Header`](#locations-header): map +[`Name`](#locations-header-name): string +[`ValuePrefix`](#locations-header-valueprefix): string +[`Forward`](#locations-header-forward): boolean | `false` +[`QueryParam`](#locations-queryparam): map +[`Name`](#locations-queryparam): string +[`Cookie`](#locations-cookie): map +[`Name`](#locations-cookie): string +[`Forwarding`](#forwarding): map +[`HeaderName`](#forwarding-headername): string +[`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader): boolean | `false` +[`ClockSkewSeconds`](#clockskewseconds): integer | `30` +[`CacheConfig`](#cacheconfig): map +[`Size`](#cacheconfig-size): integer | `0` + + +## Complete configuration + +When every field is defined, a JWT provider configuration entry has the following form: + +Kind = "jwt-provider" +Name = "" +Issuer = "" +JWKS = { + Remote = { + URI = "" + CacheDuration = "30m" + } +} + +Forwarding = { + HeaderName = "user-token" +} + + +## Specification + +This section provides details about the fields you can configure in the JWT provider configuration entry. + +### `Kind` + +Specifies the type of configuration entry to implement. +#### `Values` + +Default: None +This field is required. +Data type: String value that must be set to `jwt-provider`. +### `Name` + +Specifies a name for the configuration entry. We recommend naming the configuration file after the JWT provider used in the configuration. Refer to the [Okta JWT Provider example](#okta-jwt-provider) for an example configuration. +#### `Values` + +Default: None +This field is required. +Data type: String +### `Issuer` + +Specifies the provider that issued the JWT. This value must match the token’s `iss` (issuer) claim. + +#### `Values` + +Default: None +Data type: String +### `Audiences` + +Specifies a set of audiences that the JWT is allowed to access, formatted as a list of `aud` (audience) claims. When this field is specified, all JWTs verified with the provider must address at least one of the audiences in order to be considered valid. +#### `Values` + +Default: None +Data type: List of strings +### `JWKS` + +Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`JWKS{}.Local`](#jwks-local) and [`JWKS{}.Remote`](#jwks-remote) in the same map. + +#### `Values` + +Default: None +Data type: Map that can contain one of the following parameters: +[`Local`](#jwks-local) +[`Remote`](#jwks-remote) + +### `JWKS{}.Local` +Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `String` and `Filename` in the same map. +#### `Values` + +Default: None +Data type: Map that can contain one of the following parameters: +[`String`](#jwks-local-string) +[`Filename`](#jwks-local-filename) +### `JWKS{}.Local{}.String` +Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `String` parameter if [`JWKS{}.Local{}.Filename`](#jwks-local-filename) is also specified in the same map. +#### `Values` + +Default: None +Data type: String +### `JWKS{}.Local{}.Filename` +Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `Filename` parameter if [`JWKS{}.Local{}.String`](#jwks-local-string) is also specified in the same map. + +#### `Values` + +Default: None +Data type: String +### `JWKS{}.Remote` +Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set. +#### `Values` + +Default: None +Data type: Map that can contain the following parameters: +[`URI`](#jwks-remote-uri) +[`RequestTimeoutMs`](#jwks-remote-requesttimeoutms) +[`CacheDuration`](#jwks-remote-cacheduration) +[`FetchAsynchronously`](#jwks-remote-fetchasynchronously) +[`RetryPolicy`](#jwks-remote-retrypolicy) +### `JWKS.Remote{}.URI` +Specifies the URI of the server to query for the JSON Key Web Set. +#### `Values` + +Default: None +Data type: String +### `JWKS.Remote{}.RequestTimeoutMs` +Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms). +#### `Values` + +Default: None +Data type: Integer +### `JWKS.Remote{}.CacheDuration` +Specifies the amount of time cached keys are available before they expire. + +The default cache duration is 5 minutes. +#### `Values` + +Default: `5m` +Data type: String +### `JWKS.Remote{}.FetchAsynchronously` +Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating. + +This parameter is set to `false` by default. + +#### `Values` + +Default: `false` +Data type: Boolean +### `JWKS.Remote{}.RetryPolicy` +Defines a retry policy when fetching the JSON Web Key Set from the remote location. + +#### `Values` + +Default: None +Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value| +| -------------- | --------------- | ------------- | ---------------- | +| `NumRetries`| Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. | Integer | `0` | +### `Locations` +Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT. + +This field can specify token locations in a header, a query parameter, or a cookie. When no locations are specified, Envoy defaults to the following locations: + + 1. Authorization header with Bearer schema: `"Authorization: Bearer "` + 1. `access_token` query parameter. +#### `Values` + +Default: None +Data type: List that can contain maps of the following parameters: +[`Header`](#locations-header) +[`QueryParam`](#locations-queryparam) +[`Cookie`](#locations-cookie) + +### `Locations[].Header` +Defines how to extract a JWT from an HTTP request header. +#### `Values` + +Default: None +Data type: Map that can contain the following parameters: +[`Name`](#locations-header-name) +[`ValuePrefix`](#locations-header-valueprefix) +[`Forward`](#locations-header-forward) +### `Locations[].Header{}.Name` +Specifies the name of the HTTP request header containing the token. +#### `Values` + +Default: None +Data type: String +### `Locations[].Header{}.ValuePrefix` +Specifies a prefix that must precede the token in the header value. + +For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token itself. + +#### `Values` + +Default: None +Data type: String + +### `Locations[].Header{}.Forward` +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. +#### `Values` + +Default: `false` +Data type: Boolean + +### `Locations[].QueryParam` +Defines how to extract a JWT from an HTTP request query parameter. + + +#### `Values` + +Default: None +Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value| +| -------------- | --------------- | ------------- | ---------------- | +| `Name`| Specifies the name of the query parameter containing the token. | String | None | + +### `Locations[].Cookie` +Defines how to extract a JWT from an HTTP request cookie. +#### `Values` + +Default: None +Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value| +| -------------- | --------------- | ------------- | ---------------- | +| `Name`| Specifies the name of the cookie containing the token. | String | None + +### `Forwarding` + +Defines rules for forwarding JWTs to the backend after they are verified. +#### `Values` + +Default: None +Data type: Map that can contain the following parameters: +[`HeaderName`](#forwarding-headername) +[`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader) + +### `Forwarding{}.HeaderName` +Specifies a header name to use when forwarding a verified JWT to the backend. This field does not assume where the JWT was extracted from, and it can be applied to tokens extracted from headers, query parameters, or cookies. + +The header value is base64 URL encoded. It is not padded by default. +#### `Values` + +Default: None +Data type: String + +### `Forwarding{}.PadForwardPayloadHeader` +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`. +#### `Values` + +Default: `false` +Data type: Boolean + +### `ClockSkewSeconds` + +Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf` (not before) claims, measured in seconds. + +By default, this parameter is configured to 30 seconds. + +#### `Values` + +Default: `30` +Data type: Integer + +### `CacheConfig` +Defines behavior for caching the validation result of previously encountered JWTs. Caching results can speed up verification when the same tokens are expected to be handled multiple times. By default, the cache can hold 100 JWTs. + +#### `Values` + +Default: None +Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value| +| -------------- | --------------- | ------------- | ---------------- | +| `Size`| Specifies the number of JSON web tokens to cache. | Integer | `100` | +## Examples + +The following examples demonstrate common JWT provider configuration patterns for specific use cases. + +### Okta JWT provider + +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. + +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" +} \ No newline at end of file diff --git a/website/content/docs/connect/intentions/jwt-authorization.mdx b/website/content/docs/connect/intentions/jwt-authorization.mdx new file mode 100644 index 00000000000..e4e11e09616 --- /dev/null +++ b/website/content/docs/connect/intentions/jwt-authorization.mdx @@ -0,0 +1,35 @@ +--- +page_title: JWT authorization overview +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. + +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 + +## 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. + +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`. + +### Wildcards and intention defaults + +Because intentions without tokens are authorized when they arrive at the destination proxy, a [common pattern for the service-intentions configuration entry](/consul/docs/connect/config-entries/service-intentions#l4-intentions-for-all-destinations) sets the entry’s `Name` field as a wildcard, `*`. This pattern enables you to apply incoming requests from specific services to every service in the datacenter. + +When configuring your deployment to enforce service intentions with JSON Web Tokens, it is possible for multiple tokens with different permissions to apply to a single service’s incoming request based on attributes such as HTTP path or the request method. Because the `service-intentions` configuration entry applies the intention that is the most exact match for the request, using the `Name` wildcard with specific JWT authorization configurations can lead to unintended results. + +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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e8f3ce7d597..9f0a2a8e9f7 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -440,6 +440,10 @@ "title": "Ingress Gateway", "path": "connect/config-entries/ingress-gateway" }, + { + "title": "JWT Provider", + "path": "connect/config-entries/jwt-provider" + }, { "title": "Mesh", "path": "connect/config-entries/mesh" @@ -549,6 +553,10 @@ "title": "Create and manage service intentions", "path": "connect/intentions/create-manage-intentions" }, + { + "title": "JWT authorization for intentions", + "path": "connect/intentions/jwt-authorization" + }, { "title": "Service intentions legacy mode", "path": "connect/intentions/legacy" From 08204fec0837c389ca489e13714afa2bfa4308d1 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 13:29:04 -0700 Subject: [PATCH 02/12] configuration entry reference page --- .../connect/config-entries/jwt-provider.mdx | 958 +++++++++++++++--- 1 file changed, 796 insertions(+), 162 deletions(-) diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index 6f25b0ef92a..a3c7369c4c7 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -1,286 +1,530 @@ --- -page_title: JWT authorization configuration entry reference +page_title: JWT provider configuration entry reference description: |- --- -# JWT authorization configuration entry reference -[Description] +# 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. ## Configuration model The following list outlines field hierarchy, language-specific data types, and requirements in a JWT provider configuration entry. Click on a property name to view additional details, including default values. - -[`Kind`](#kind): string | required | must be set to `jwt-provider` -[`Name`](#name): string | required -[`Issuer`](#issuer): string -[`JWKS`](#jwks): map -[`Local`](#jwks-local): map -[`String`](#jwks-local-string): string -[`Filename`](#jwks-local-filename): string -[`Remote`](#jwks-remote): map -[`URI`](#jwks-remote-uri): string -[`RequestTimeoutMs`](#jwks-remote-requesttimeoutms): integer | -[`CacheDuration`](#jwks-remote-cacheduration): string | `5m` -[`FetchAsynchronously`](#jwks-remote-fetchasynchronously): boolean | `false` -[`RetryPolicy`](#jwks-remote-retrypolicy): map -[`NumRetries`](#jwks-remote-retrypolicy): integer | `0` -[`Audiences`](#audiences): list of strings -[`Locations`](#locations): list of maps -[`Header`](#locations-header): map -[`Name`](#locations-header-name): string -[`ValuePrefix`](#locations-header-valueprefix): string -[`Forward`](#locations-header-forward): boolean | `false` -[`QueryParam`](#locations-queryparam): map -[`Name`](#locations-queryparam): string -[`Cookie`](#locations-cookie): map -[`Name`](#locations-cookie): string -[`Forwarding`](#forwarding): map -[`HeaderName`](#forwarding-headername): string -[`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader): boolean | `false` -[`ClockSkewSeconds`](#clockskewseconds): integer | `30` -[`CacheConfig`](#cacheconfig): map -[`Size`](#cacheconfig-size): integer | `0` - + + + + +- [`Kind`](#kind): string | required | must be set to `jwt-provider` +- [`Name`](#name): string | required +- [`Issuer`](#issuer): string +- [`JWKS`](#jwks): map + - [`Local`](#jwks-local): map + - [`String`](#jwks-local-string): string + - [`Filename`](#jwks-local-filename): string + - [`Remote`](#jwks-remote): map + - [`URI`](#jwks-remote-uri): string + - [`RequestTimeoutMs`](#jwks-remote-requesttimeoutms): integer + - [`CacheDuration`](#jwks-remote-cacheduration): string | `5m` + - [`FetchAsynchronously`](#jwks-remote-fetchasynchronously): boolean | `false` + - [`RetryPolicy`](#jwks-remote-retrypolicy): map + - [`NumRetries`](#jwks-remote-retrypolicy): integer | `0` +- [`Audiences`](#audiences): list of strings +- [`Locations`](#locations): list of maps + - [`Header`](#locations-header): map + - [`Name`](#locations-header-name): string + - [`ValuePrefix`](#locations-header-valueprefix): string + - [`Forward`](#locations-header-forward): boolean | `false` + - [`QueryParam`](#locations-queryparam): map + - [`Name`](#locations-queryparam): string + - [`Cookie`](#locations-cookie): map + - [`Name`](#locations-cookie): string +- [`Forwarding`](#forwarding): map + - [`HeaderName`](#forwarding-headername): string + - [`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader): boolean | `false` +- [`ClockSkewSeconds`](#clockskewseconds): integer | `30` +- [`CacheConfig`](#cacheconfig): map + - [`Size`](#cacheconfig-size): integer | `0` + + + + + +- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | required | must be set to `jwtProvider` +- [`metadata`](#metadata): map | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string +- [`spec`](#spec): map | required + - [`issuer`](#spec-issuer): string + - [`jwks`](#spec-jwks): map + - [`local`](#spec-jwks-local): map + - [`string`](#spec-jwks-local-string): string + - [`filename`](#spec-jwks-local-filename): string + - [`remote`](#spec-jwks-remote): map + - [`uri`](#spec-jwks-remote-uri): string + - [`requestTimeoutMs`](#spec-jwks-remote-requesttimeoutms): integer + - [`cacheDuration`](#spec-jwks-remote-cacheduration): string | `5m` + - [`fetchAsynchronously`](#spec-jwks-remote-fetchasynchronously): boolean | `false` + - [`retryPolicy`](#spec-jwks-remote-retrypolicy): map + - [`numRetries`](#spec-jwks-remote-retrypolicy): integer | `0` + - [`audiences`](#spec-audiences): list of strings + - [`locations`](#spec-locations): list of maps + - [`header`](#spec-locations-header): map + - [`name`](#spec-locations-header-name): string + - [`valuePrefix`](#spec-locations-header-valueprefix): string + - [`forward`](#spec-locations-header-forward): boolean | `false` + - [`queryParam`](#spec-locations-queryparam): map + - [`name`](#spec-locations-queryparam): string + - [`cookie`](#spec-locations-cookie): map + - [`name`](#spec-locations-cookie): string + - [`forwarding`](#spec-forwarding): map + - [`headerName`](#spec-forwarding-headername): string + - [`padForwardPayloadHeader`](#spec-forwarding-padforwardpayloadheader): boolean | `false` + - [`clockSkewSeconds`](#spec-clockskewseconds): integer | `30` + - [`cacheConfig`](#spec-cacheconfig): map + - [`size`](#spec-cacheconfig-size): integer | `0` + + + ## Complete configuration When every field is defined, a JWT provider configuration entry has the following form: -Kind = "jwt-provider" -Name = "" -Issuer = "" -JWKS = { - Remote = { - URI = "" - CacheDuration = "30m" + + + + +```hcl +Kind = "jwt-provider" # required +Name = "" # required +Issuer = "" # required +JWKS = { # required + Local = { # cannot specify with JWKS{}.Remote + String = "" # cannot specify with JWKS{}.Remote{}.Filename + Filename = "" # cannot specify with JWKS{}.Remote{}.String } } - +JWKS = { + Remote = { # cannot specify with JWKS{}.Local + URI = "" + RequestTimeoutMs = 1500 + CacheDuration = "5m" + FetchAsynchronously = false + RetryPolicy = { + NumRetries = 0 + } + } + } +Audiences = [""] +Locations = [ + { + Header = { + Name = "" + ValuePrefix = "" + Forward = false + } + }, + { + QueryParam = { + Name = "" + } + }, + { + Cookie = { + Name = "" + } + } +] Forwarding = { - HeaderName = "user-token" + HeaderName = "" + PadForwardPayloadHeader = false } +ClockSkewSeconds = 30 +CacheConfig = { + Size = 0 +} +``` + + + + +```json +{ +"Kind": "jwt-provider", // required +"Name": "", // required +"Issuer": "", // required +"JWKS": { // required + "Local": { // cannot specify with JWKS.Remote + "String": "", // cannot specify with JWKS.Local.Filename + "Filename": "" // cannot specify with JWKS.Local.String + } +}, +"JWKS": { + "Remote": { // cannot specify with JWKS.Local + "URI": "", + "RequestTimeoutMs": "1500", + "CacheDuration": "5m", + "FetchAsynchronously": "false", + "RetryPolicy": { + "NumRetries": "0" + } + } +} +"Audiences": [""], +"Locations": [ + { + "Header": { + "Name": "", + "ValuePrefix": "", + "Forward": "false" + } + }, + { + "QueryParam": { + "Name":"", + } + }, + { + "Cookie": { + "Name": "" + } + } +] +"Forwarding": { + "HeaderName": "", + "PadForwardPayloadHeader": "false" +}, +"ClockSkewSeconds": "30", +"CacheConfig": { + "Size": "0" +} +} +``` + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 # required +kind: jwtProvider # required +metadata: # required + name: # required + namespace: +spec: # required + issuer: + jwks: + local: # cannot specify with spec.jwks.remote + string: # cannot specify with spec.jwks.local.filename + filename: # cannot specify with spec.jwks.local.string + jwks: + remote: # cannot specify with spec.jwks.local + uri: + requestTimeoutMs: 1500 + cacheDuration: 5m + fetchAsynchronously: false + retryPolicy: + numRetries: 0 + audiences: [] + locations: + header: + name: + valuePrefix: "" + forward: false + queryParam: + name: "" + cookie: + name: "" + forwarding: + headerName: "" + padForwardPayloadHeader: false + clockSkewSeconds: 30 + cacheConfig: + size: 0 +``` + + + ## Specification This section provides details about the fields you can configure in the JWT provider configuration entry. + + + + ### `Kind` Specifies the type of configuration entry to implement. -#### `Values` -Default: None -This field is required. -Data type: String value that must be set to `jwt-provider`. +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `jwt-provider`. + ### `Name` Specifies a name for the configuration entry. We recommend naming the configuration file after the JWT provider used in the configuration. Refer to the [Okta JWT Provider example](#okta-jwt-provider) for an example configuration. -#### `Values` -Default: None -This field is required. -Data type: String +#### Values + +- Default: None +- This field is required. +- Data type: String + ### `Issuer` Specifies the provider that issued the JWT. This value must match the token’s `iss` (issuer) claim. -#### `Values` +#### Values -Default: None -Data type: String -### `Audiences` +- Default: None +- Data type: String -Specifies a set of audiences that the JWT is allowed to access, formatted as a list of `aud` (audience) claims. When this field is specified, all JWTs verified with the provider must address at least one of the audiences in order to be considered valid. -#### `Values` - -Default: None -Data type: List of strings ### `JWKS` Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`JWKS{}.Local`](#jwks-local) and [`JWKS{}.Remote`](#jwks-remote) in the same map. -#### `Values` +#### Values -Default: None -Data type: Map that can contain one of the following parameters: -[`Local`](#jwks-local) -[`Remote`](#jwks-remote) +- Default: None +- Data type: Map that can contain one of the following parameters: + + - [`Local`](#jwks-local) + - [`Remote`](#jwks-remote) ### `JWKS{}.Local` + Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `String` and `Filename` in the same map. -#### `Values` -Default: None -Data type: Map that can contain one of the following parameters: -[`String`](#jwks-local-string) -[`Filename`](#jwks-local-filename) +#### Values + +- Default: None +- Data type: Map that can contain one of the following parameters: + + - [`String`](#jwks-local-string) + - [`Filename`](#jwks-local-filename) + ### `JWKS{}.Local{}.String` + Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `String` parameter if [`JWKS{}.Local{}.Filename`](#jwks-local-filename) is also specified in the same map. -#### `Values` -Default: None -Data type: String +#### Values + +- Default: None +- Data type: String + ### `JWKS{}.Local{}.Filename` + Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `Filename` parameter if [`JWKS{}.Local{}.String`](#jwks-local-string) is also specified in the same map. -#### `Values` +#### Values + +- Default: None +- Data type: String -Default: None -Data type: String ### `JWKS{}.Remote` -Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set. -#### `Values` - -Default: None -Data type: Map that can contain the following parameters: -[`URI`](#jwks-remote-uri) -[`RequestTimeoutMs`](#jwks-remote-requesttimeoutms) -[`CacheDuration`](#jwks-remote-cacheduration) -[`FetchAsynchronously`](#jwks-remote-fetchasynchronously) -[`RetryPolicy`](#jwks-remote-retrypolicy) + +Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`URI`](#jwks-remote-uri) + - [`RequestTimeoutMs`](#jwks-remote-requesttimeoutms) + - [`CacheDuration`](#jwks-remote-cacheduration) + - [`FetchAsynchronously`](#jwks-remote-fetchasynchronously) + - [`RetryPolicy`](#jwks-remote-retrypolicy) + ### `JWKS.Remote{}.URI` + Specifies the URI of the server to query for the JSON Key Web Set. -#### `Values` -Default: None -Data type: String +#### Values + +- Default: None +- Data type: String + ### `JWKS.Remote{}.RequestTimeoutMs` + Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms). -#### `Values` -Default: None -Data type: Integer +#### Values + +- Default: None +- Data type: Integer + ### `JWKS.Remote{}.CacheDuration` + Specifies the amount of time cached keys are available before they expire. The default cache duration is 5 minutes. -#### `Values` -Default: `5m` -Data type: String +#### Values + +- Default: `5m` +- Data type: String + ### `JWKS.Remote{}.FetchAsynchronously` + Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating. This parameter is set to `false` by default. -#### `Values` +#### Values + +- Default: `false` +- Data type: Boolean -Default: `false` -Data type: Boolean ### `JWKS.Remote{}.RetryPolicy` + Defines a retry policy when fetching the JSON Web Key Set from the remote location. -#### `Values` +#### Values -Default: None -Data type: Map that contains the following parameter: +- Default: None +- Data type: Map that contains the following parameter: | Parameter | Description | Data type | Default value| | -------------- | --------------- | ------------- | ---------------- | | `NumRetries`| Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. | Integer | `0` | + +### `Audiences` + +Specifies a set of audiences that the JWT is allowed to access, formatted as a list of `aud` (audience) claims. When this field is specified, all JWTs verified with the provider must address at least one of the audiences in order to be considered valid. + +#### Values + +- 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. This field can specify token locations in a header, a query parameter, or a cookie. When no locations are specified, Envoy defaults to the following locations: - 1. Authorization header with Bearer schema: `"Authorization: Bearer "` - 1. `access_token` query parameter. -#### `Values` +1. Authorization header with Bearer schema: `"Authorization: Bearer "` +1. `access_token` query parameter. + +#### Values -Default: None -Data type: List that can contain maps of the following parameters: -[`Header`](#locations-header) -[`QueryParam`](#locations-queryparam) -[`Cookie`](#locations-cookie) +- Default: None +- Data type: List that can contain maps of the following parameters: + + - [`Header`](#locations-header) + - [`QueryParam`](#locations-queryparam) + - [`Cookie`](#locations-cookie) ### `Locations[].Header` + Defines how to extract a JWT from an HTTP request header. -#### `Values` -Default: None -Data type: Map that can contain the following parameters: -[`Name`](#locations-header-name) -[`ValuePrefix`](#locations-header-valueprefix) -[`Forward`](#locations-header-forward) +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`Name`](#locations-header-name) + - [`ValuePrefix`](#locations-header-valueprefix) + - [`Forward`](#locations-header-forward) + ### `Locations[].Header{}.Name` + Specifies the name of the HTTP request header containing the token. -#### `Values` -Default: None -Data type: String +#### Values + +- Default: None +- Data type: String + ### `Locations[].Header{}.ValuePrefix` + Specifies a prefix that must precede the token in the header value. - + For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token itself. -#### `Values` +#### Values -Default: None -Data type: String +- Default: None +- Data type: String ### `Locations[].Header{}.Forward` -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. -#### `Values` +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. + +#### Values -Default: `false` -Data type: Boolean +- Default: `false` +- Data type: Boolean ### `Locations[].QueryParam` -Defines how to extract a JWT from an HTTP request query parameter. +Defines how to extract a JWT from an HTTP request query parameter. -#### `Values` +#### Values -Default: None -Data type: Map that contains the following parameter: +- Default: None +- Data type: Map that contains the following parameter: -| Parameter | Description | Data type | Default value| -| -------------- | --------------- | ------------- | ---------------- | -| `Name`| Specifies the name of the query parameter containing the token. | String | None | +| Parameter | Description | Data type | Default value | +| :-------- | :-------------------------------------------------------------- | :-------- | :------------ | +| `Name` | Specifies the name of the query parameter containing the token. | String | None | ### `Locations[].Cookie` + Defines how to extract a JWT from an HTTP request cookie. -#### `Values` -Default: None -Data type: Map that contains the following parameter: +#### Values -| Parameter | Description | Data type | Default value| -| -------------- | --------------- | ------------- | ---------------- | -| `Name`| Specifies the name of the cookie containing the token. | String | None +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `Name`| Specifies the name of the cookie containing the token. | String | None | ### `Forwarding` Defines rules for forwarding JWTs to the backend after they are verified. -#### `Values` -Default: None -Data type: Map that can contain the following parameters: -[`HeaderName`](#forwarding-headername) -[`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader) +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`HeaderName`](#forwarding-headername) + - [`PadForwardPayloadHeader`](#forwarding-padforwardpayloadheader) ### `Forwarding{}.HeaderName` + Specifies a header name to use when forwarding a verified JWT to the backend. This field does not assume where the JWT was extracted from, and it can be applied to tokens extracted from headers, query parameters, or cookies. The header value is base64 URL encoded. It is not padded by default. -#### `Values` -Default: None -Data type: String +#### Values + +- Default: None +- Data type: String ### `Forwarding{}.PadForwardPayloadHeader` + 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`. -#### `Values` -Default: `false` -Data type: Boolean +#### Values + +- Default: `false` +- Data type: Boolean ### `ClockSkewSeconds` @@ -288,22 +532,363 @@ Specifies the maximum allowable time difference from clock skew when validating By default, this parameter is configured to 30 seconds. -#### `Values` +#### Values -Default: `30` -Data type: Integer +- Default: `30` +- Data type: Integer ### `CacheConfig` + Defines behavior for caching the validation result of previously encountered JWTs. Caching results can speed up verification when the same tokens are expected to be handled multiple times. By default, the cache can hold 100 JWTs. -#### `Values` +#### Values -Default: None -Data type: Map that contains the following parameter: +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `Size` | Specifies the number of JSON web tokens to cache. | Integer | `100` | + + + + + +### `apiVersion` + +Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`. + +#### Values + +- Default: None +- This field is required. +- String value that must be set to `consul.hashicorp.com/v1alpha1`. + +### `kind` + +Specifies the type of configuration entry to implement. Must be set to `jwtProvider`. + +#### Values + +- Default: None +- This field is required. +- Data type: String value that must be set to `jwtProvider`. + +## `metadata` + +Map that contains an arbitrary name for the configuration entry and the namespace it applies to. + +#### Values + +- Default: None +- Data type: Map + +### `metadata.name` + +Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster. We recommend naming the configuration file after the JWT provider used in the configuration. Refer to the [Okta JWT Provider example](#okta-jwt-provider) for an example configuration. + +#### Values + +- Default: None +- This field is required. +- Data type: String + +### `metadata.namespace` + +Specifies the namespace that the configuration applies to. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information. + +#### Values + +- Default: None +- Data type: String + +### `spec` + +Map that contains the details about the `jwtProvider` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. + +#### Values + +- Default: None +- This field is required. +- Data type: Map + +### `spec.issuer` + +Specifies the provider that issued the JWT. This value must match the token’s `iss` (issuer) claim. + +#### Values + +- Default: None +- Data type: String + +### `spec.jwks` + +Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`spec.jwks.local`](#spec-jwks-local) and [`spec.jwks.remote`](#spec-jwks-remote) in the same map. + +#### Values + +- Default: None +- Data type: Map that can contain one of the following parameters: + + - [`local`](#spec-jwks-local) + - [`remote`](#spec-jwks-remote) + +### `spec.jwks.local` + +Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `string` and `filename` in the same map. + +#### Values + +- Default: None +- Data type: Map that can contain one of the following parameters: + + - [`string`](#spec-jwks-local-string) + - [`filename`](#spec-jwks-local-filename) + +### `spec.jwks.local.string` + +Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `string` parameter if [`spec.jwks.local.filename`](#spec-jwks-local-filename) is also specified in the same map. + +#### Values + +- Default: None +- Data type: String + +### `spec.jwks.local.filename` + +Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `filename` parameter if [`spec.jwks.local.string`](#spec-jwks-local-string) is also specified in the same map. + +#### Values + +- Default: None +- Data type: String + +### `spec.jwks.remote` + +Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`uri`](#spec-jwks-remote-uri) + - [`requestTimeoutMs`](#spec-jwks-remote-requesttimeoutms) + - [`cacheDuration`](#spec-jwks-remote-cacheduration) + - [`fetchAsynchronously`](#spec-jwks-remote-fetchasynchronously) + - [`retryPolicy`](#spec-jwks-remote-retrypolicy) + +### `spec.jwks.remote.uri` + +Specifies the URI of the server to query for the JSON Key Web Set. + +#### Values + +- Default: None +- Data type: String + +### `spec.jwks.remote.requestTimeoutMs` + +Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms). + +#### Values + +- Default: None +- Data type: Integer + +### `spec.jwks.remote.cacheDuration` + +Specifies the amount of time cached keys are available before they expire. + +The default cache duration is 5 minutes. + +#### Values + +- Default: `5m` +- Data type: String + +### `spec.jwks.remote.fetchAsynchronously` + +Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating. + +This parameter is set to `false` by default. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.jwks.remote.retryPolicy` + +Defines a retry policy when fetching the JSON Web Key Set from the remote location. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value | +| :---------- | :------------------------------------------------------------------------------------------------------ | :-------- | :------------ | +| `numRetries`| Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. | Integer | `0` | + +### `spec.audiences` + +Specifies a set of audiences that the JWT is allowed to access, formatted as a list of `aud` (audience) claims. When this field is specified, all JWTs verified with the provider must address at least one of the audiences in order to be considered valid. + +#### Values + +- Default: None +- Data type: List of strings + +### `spec.locations` + +Specifies the locations in requests where the JWT can be found. Envoy checks all of these locations to extract a JWT. + +This field can specify token locations in a header, a query parameter, or a cookie. When no locations are specified, Envoy defaults to the following locations: + +1. Authorization header with Bearer schema: `"Authorization: Bearer "` +1. `access_token` query parameter. + +#### Values + +- Default: None +- Data type: List that can contain maps of the following parameters: + + - [`header`](#spec-locations-header) + - [`queryParam`](#spec-locations-queryparam) + - [`cookie`](#spec-locations-cookie) + +### `spec.locations[].header` + +Defines how to extract a JWT from an HTTP request header. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`name`](#spec-locations-header-name) + - [`valuePrefix`](#spec-locations-header-valueprefix) + - [`forward`](#spec-locations-header-forward) + +### `spec.locations[].header.name` + +Specifies the name of the HTTP request header containing the token. + +#### Values + +- Default: None +- Data type: String + +### `spec.locations[].header.valuePrefix` + +Specifies a prefix that must precede the token in the header value. + +For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token itself. + +#### Values + +- Default: None +- Data type: String + +### `spec.locations[].header.forward` + +Specifies whether the header with the JWT is forwarded after the token is verified. When set to false, the header is not forwarded. + +The default value is false. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.locations[].queryParam` + +Defines how to extract a JWT from an HTTP request query parameter. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value | +| :-------- | :-------------------------------------------------------------- | :-------- | :------------ | +| `name` | Specifies the name of the query parameter containing the token. | String | None | + +### `spec.locations[].cookie` + +Defines how to extract a JWT from an HTTP request cookie. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `name`| Specifies the name of the cookie containing the token. | String | None | + +### `spec.forwarding` + +Defines rules for forwarding JWTs to the backend after they are verified. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`headerName`](#spec-forwarding-headername) + - [`padForwardPayloadHeader`](#spec-forwarding-padforwardpayloadheader) + +### `spec.forwarding.headerName` + +Specifies a header name to use when forwarding a verified JWT to the backend. This field does not assume where the JWT was extracted from, and it can be applied to tokens extracted from headers, query parameters, or cookies. + +The header value is base64 URL encoded. It is not padded by default. + +#### Values + +- Default: None +- Data type: String + +### `spec.forwarding.padForwardPayloadHeader` + +Determines whether to add padding to the base64 encoded token specified in [spec.forwarding.headerName`](#spec-forwarding-header-name). + +By default, this field is set to `false`. + +#### Values + +- Default: `false` +- Data type: Boolean + +### `spec.clockSkewSeconds` + +Specifies the maximum allowable time difference from clock skew when validating the JSON web token’s `exp` (expiration) and `nbf` (not before) claims, measured in seconds. + +By default, this parameter is configured to 30 seconds. + +#### Values + +- Default: `30` +- Data type: Integer + +### `spec.cacheConfig` + +Defines behavior for caching the validation result of previously encountered JWTs. Caching results can speed up verification when the same tokens are expected to be handled multiple times. By default, the cache can hold 100 JWTs. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `size` | Specifies the number of JSON web tokens to cache. | Integer | `100` | + + + -| Parameter | Description | Data type | Default value| -| -------------- | --------------- | ------------- | ---------------- | -| `Size`| Specifies the number of JSON web tokens to cache. | Integer | `100` | ## Examples The following examples demonstrate common JWT provider configuration patterns for specific use cases. @@ -312,6 +897,11 @@ The following examples demonstrate common JWT provider configuration patterns fo 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" @@ -326,4 +916,48 @@ JWKS = { Forwarding = { HeaderName = "user-token" -} \ No newline at end of file +} +``` + + + + + +```json +{ + "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" + } +} +``` + + + + + +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 +kind: jwtProvider +metadata: + name: okta +spec: + issuer: okta + jwks: + remote: + uri: https://dev-850216.okta.com/oauth2/default/v1/keys + cacheDuration: 30m + forwarding: + headerName: user-token +``` + + + \ No newline at end of file From 33cede6ea5c96b12561fba7d98a201eb50aaf2c7 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 13:59:52 -0700 Subject: [PATCH 03/12] 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 a3c7369c4c7..273ebf16f14 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 e4e11e09616..9cf98c63cb1 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. - -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. +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 `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 + From f6b129588bfc01332aa441bddc93b5d3d77b819b Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 14:58:10 -0700 Subject: [PATCH 04/12] service intentions page --- .../config-entries/service-intentions.mdx | 335 ++++++++++++++++-- 1 file changed, 303 insertions(+), 32 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 321b7f16058..a5440b02ca8 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -21,38 +21,44 @@ The following outline shows how to format the service intentions configuration e - [`Name`](#name): string | required - [`Namespace`](#namespace): string | `default` | - [`Partition`](#partition): string | `default` | -- [`Meta`](#meta): map | no default -- [`Sources`](#sources): list | no default - - [`Name`](#sources-name): string | no default - - [`Peer`](#sources-peer): string | no default - - [`Namespace`](#sources-namespace): string | no default | - - [`Partition`](#sources-partition): string | no default | - - [`Action`](#sources-action): string | no default | required for L4 intentions - - [`Permissions`](#sources-permissions): list | no default - - [`Action`](#sources-permissions-action): string | no default | required +- [`Meta`](#meta): map +- [`JWT`](#jwt): map + - [`Providers`](#jwt-providers): list of maps + - [`Provider`](#jwt-providers-provider): string + - [`VerifyClaims`](#jwt-provider-verifyclaims): list of maps + - [`Path`](#jwt-provider-verifyclaims-path): list of strings + - [`Value`](#jwt-provider-verifyclaims-value): string +- [`Sources`](#sources): list + - [`Name`](#sources-name): string + - [`Peer`](#sources-peer): string + - [`Namespace`](#sources-namespace): string | + - [`Partition`](#sources-partition): string | + - [`Action`](#sources-action): string | required for L4 intentions + - [`Permissions`](#sources-permissions): list + - [`Action`](#sources-permissions-action): string | required - [`HTTP`](#sources-permissions-http): map | required - - [`PathExact`](#sources-permissions-http): string | no default - - [`PathPrefix`](#sources-permissions-http): string | no default - - [`PathRegex`](#sources-permissions-http): string | no default - - [`Methods`](#sources-permissions-http): list | no default - - [`Header`](#sources-permissions-http-header): list of maps |no default + - [`PathExact`](#sources-permissions-http): string + - [`PathPrefix`](#sources-permissions-http): string + - [`PathRegex`](#sources-permissions-http): string + - [`Methods`](#sources-permissions-http): list | no default + - [`Header`](#sources-permissions-http-header): list of maps - [`Name`](#sources-permissions-http-header): string | required - - [`Present`](#sources-permissions-http-header): boolean | `false` - - [`Exact`](#sources-permissions-http-header): string | no default - - [`Prefix`](#sources-permissions-http-header): string | no default - - [`Suffix`](#sources-permissions-http-header): string | no default - - [`Regex`](#sources-permissions-http-header): string | no default - - [`Invert`](#sources-permissions-http-header): boolean | `false` - - [`Precedence`](#sources-precedence): number | no default | _read-only_ - - [`Type`](#sources-type): string | `consul` - - [`Description`](#sources-description): string - - [`LegacyID`](#sources-legacyid): string | no default | _read-only_ - - [`LegacyMeta`](#sources-legacymeta): map | no default | _read-only_ - - [`LegacyCreateTime`](#sources-legacycreatetime): string | no default | _read-only_ - - [`LegacyUpdateTime`](#sources-legacyupdatetime): string | no default | _read-only_ + - [`Present`](#sources-permissions-http-header): boolean | `false` + - [`Exact`](#sources-permissions-http-header): string + - [`Prefix`](#sources-permissions-http-header): string + - [`Suffix`](#sources-permissions-http-header): string + - [`Regex`](#sources-permissions-http-header): string + - [`Invert`](#sources-permissions-http-header): boolean | `false` + - [`Precedence`](#sources-precedence): number + - [`Type`](#sources-type): string | `consul` + - [`Description`](#sources-description): string + - [`LegacyID`](#sources-legacyid): string + - [`LegacyMeta`](#sources-legacymeta): map + - [`LegacyCreateTime`](#sources-legacycreatetime): string + - [`LegacyUpdateTime`](#sources-legacyupdatetime): string - + - [`apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1` - [`kind`](#kind): string | must be set to `ServiceIntentions` @@ -63,6 +69,12 @@ The following outline shows how to format the service intentions configuration e - [`destination`](#spec-destination): map | no default - [`name`](#spec-destination-name): string | required - [`namespace`](#metadata-namespace): string | `default` | + - [`jwt`](#spec-jwt): map + - [`providers`](#spec-jwt-providers): list of maps + - [`provider`](#spec-jwt-providers-provider): string + - [`verifyClaims`](#spec-jwt-provider-verifyclaims): list of maps + - [`path`](#spec-jwt-provider-verifyclaims-path): list of strings + - [`value`](#spec-jwt-provider-verifyclaims-value): string - [`sources`](#spec-sources): list | no default - [`name`](#spec-sources-name): string | no default - [`peer`](#spec-sources-peer): string | no default @@ -107,6 +119,19 @@ Meta = { "" = "" "" = "" } +JWT = { + Providers = [ + { + Provider = "" + VerifyClaims = [ + { + Path = [""] + Value = "" + } + ] + } + ] +} Sources = [ { Name = "" # string @@ -176,6 +201,12 @@ spec: destination: name: namespace: + jwt: + providers: + provider: + verifyClaims: + path: [] + value: sources: name: peer: @@ -220,6 +251,19 @@ spec: "key-1":"", "key-2":"" }, + "JWT": { + "Providers": [ + { + "Provider": "", + "VerifyClaims": [ + { + "Path": [""], + "Value": "" + } + ] + } + ] + }, "Sources":[ { "Name":"", @@ -341,6 +385,71 @@ Specifies key-value pairs to add to the KV store when the configuration entry is - keys: String - values: String, integer, or float +### `JWT` + +Specifies a JSON Web Token provider configured in a [JWT provider configuration entry](/consul/docs/connect/config-entries/jwt-provider), as well as additional configurations for verifying a service's JWT before authorizing communication between services + +#### Values + +- Default: None +- Data type: Map that contains [`JWT{}.Providers`](#jwt-providers) + +### `JWT{}.Providers` + +Specifies the names of one or more previously configured [JWT provider configuration entries](/consul/docs/connect/config-entries/jwt-provider), which include the information necessary to calidate a JSON web token. + +#### Values + +- Default: None +- Data type: List of maps + +### `JWT{}.Providers[].Provider` + +Specifies the name of a JWT provider defined in the `Name` field of the [`jwt-provider` configuration entry](/consul/docs/connect/config-entries/jwt-provider). You must write the JWT Provider to Consul before referencing it in a service intention. + +#### Values + +- Default: None +- Data type: String + +### `JWT{}.Providers[].VerifyClaims` + +Specifies additional token information to verify beyond what is configured in the JWT provider configuration entry. This map takes the form of a JSON web token claim and a value to match for verification. + +#### Values + +- Default: None +- Data type: List of maps that can contain the following parameters: +- + - [`Path`](#jwt-providers-verifyclaims-path) + - [`Value`](#jwt-providers-verifyclaims-value) + +### `JWT{}.Providers[].VerifyClaims[].Path` + +Specifies the path to the claim in the JSON web token. For more information about JWT claims, refer to the [IETF standards documentation](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1). + +#### Values + +- Default: None +- Data type: List of strings that can contain one of the following values: + + - `iss`: Issuer claim + - `sub`: Subject claim + - `aud`: Audience claim + - `exp`: Expiration Time claim + - `nbf`: Not Before claim + - `iat`: Issued At claim + - `jti`: JWT ID claim + +### `JWT{}.Providers[].VerifyClaims.Value` + +Specifies the value to match on when verifying the the claim designated in [`JWT{}.Providers[].VerifyClaims[].Path`](#jwt-providers-verifyclaims-path). + +#### Values + +- Default: None +- Data type: String + ### `Sources[]` List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime. Refer to [`Precedence`](#sources-precedence) for additional information. @@ -621,17 +730,71 @@ You can also specify a wildcard character (`*`) to match all services that are m - This field is required. - Data type: String -### `spec.metadata.namespace` +### `spec.jwt` -Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configuration entry applies to. You can also specify a wildcard character (`*`) to match all namespaces. Intentions that are applied with a wildcard, however, are not supported when defining L7 [`permissions`](#spec-sources-permissions). +Specifies a JSON Web Token provider configured in a [JWT provider configuration entry](/consul/docs/connect/config-entries/jwt-provider), as well as additional configurations for verifying a service's JWT before authorizing communication between services -Refer to [Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for information about how Consul namespaces map to Kubernetes Namespaces. Open source Consul distributions (Consul OSS) ignore the `metadata.namespace` configuration. +#### Values + +- Default: None +- Data type: Map that contains [`spec.jwt.providers`](#spec-jwt-providers) + +### `spec.jwt.providers` + +Specifies the names of one or more previously configured [JWT provider configuration entries](/consul/docs/connect/config-entries/jwt-provider), which include the information necessary to calidate a JSON web token. #### Values -- Default: If not set, destination service namespace is inherited from the `connectInject.consulNamespaces` configuration. Refer to [ServiceIntentions Special Case (Enterprise)](/consul/docs/k8s/crds#serviceintentions-special-case-enterprise) for details. +- Default: None +- Data type: List of maps + +### `spec.jwt.providers[].provider` + +Specifies the name of a JWT provider defined in the `metadata.name` field of the [JWT provider configuration entry](/consul/docs/connect/config-entries/jwt-provider). You must write the JWT Provider to Consul before referencing it in a service intention. + +#### Values + +- Default: None - Data type: String +### `spec.jwt.providers[].verifyClaims` + +Specifies additional token information to verify beyond what is configured in the JWT provider configuration entry. This map takes the form of a JSON web token claim and a value to match for verification. + +#### Values + +- Default: None +- Data type: List of maps that can contain the following parameters: +- + - [`path`](#spec-jwt-providers-verifyclaims-path) + - [`value`](#spec-jwt-providers-verifyclaims-value) + +### `spec.jwt.providers[].verifyClaims[].path` + +Specifies the path to the claim in the JSON web token. For more information about JWT claims, refer to the [IETF standards documentation](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1). + +#### Values + +- Default: None +- Data type: List of strings that can contain one of the following values: + + - `iss`: Issuer claim + - `sub`: Subject claim + - `aud`: Audience claim + - `exp`: Expiration Time claim + - `nbf`: Not Before claim + - `iat`: Issued At claim + - `jti`: JWT ID claim + +### `spec.jwt.providers[].verifyClaims[].value` + +Specifies the value to match on when verifying the the claim designated in [`JWT{}.Providers[].VerifyClaims[].Path`](#jwt-providers-verifyclaims-path). + +#### Values + +- Default: None +- Data type: String + ### `spec.sources[]` List of configurations that define intention sources and the authorization granted to the sources. You can specify source configurations in any order, but Consul stores and evaluates them in order of reverse precedence at runtime. @@ -1287,3 +1450,111 @@ When using cluster peering connections, intentions secure your deployments with ``` + +### JWT validation with intentions + +The following example configures a service intention that evaluates requests when a service named `backend` receives a request from the `frontend` service. When the request comes from from the `/admin` HTTP path, a JSON Web Token provided by Okta is evaluated. In addition to the validation requirements in a separate JWT provider configuration entry, an additional check occurs to confirm that the token has either a `perms` or `role` claim with the `admin` value. If it does, the request is authorized. + +Because the intention allows requests that come from the `/` HTTP path, only requests on the `/admin` path are subject to token validation. + + + +```hcl +Kind = "service-intentions" +Name = "backend" +Sources = [ + { + Name = "frontend" + Permissions = [ + { + HTTP = { + PathExact = "/admin" + } + JWT = { + Providers = [ + { + Provider = "okta" + VerifyClaims = [ + { + Path = ["perms", "role"] + Value = "admin" + } + ] + } + ] + } + }, + { + Action = "allow" + HTTP = { + PathPrefix = "/" + } + } + ] + } +] +``` + +```yaml + apiVersion: consul.hashicorp.com/v1alpha1 + kind: ServiceIntentions + metadata: + name: backend + spec: + sources: + name: frontend + permissions: + http: + pathExact: /admin + jwt: + providers: + provider: okta + verifyClaims: + path: + - perms + - role + value: admin + action: allow + http: + pathPrefix: / +``` + +```json +{ +"Kind": "service-intentions", +"Name": "backend", +"Sources": [ + { + "Name": "frontend", + "Permissions": [ + { + "HTTP": { + "PathExact": "/admin" + }, + "JWT": { + "Providers": [ + { + "Provider": "okta", + "VerifyClaims": [ + { + "Path": ["perms", "role"], + "Value": "admin" + } + ] + } + ] + } + }, + { + "Action": "allow", + "HTTP": { + "PathPrefix": "/" + } + } + ] + } +] +} +``` + + \ No newline at end of file From aaccd1ab5f17aac6a78bbfeaba1e5504a837d3bb Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 15:07:46 -0700 Subject: [PATCH 05/12] usage --- .../connect/intentions/jwt-authorization.mdx | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/website/content/docs/connect/intentions/jwt-authorization.mdx b/website/content/docs/connect/intentions/jwt-authorization.mdx index 9cf98c63cb1..d867b7c62f1 100644 --- a/website/content/docs/connect/intentions/jwt-authorization.mdx +++ b/website/content/docs/connect/intentions/jwt-authorization.mdx @@ -14,9 +14,9 @@ By specifying a JSON Web Key Set (JWKS) in the configuration entry and referenci The process to configure your network to enforce service intentions based on JSON web tokens consists of the following steps: -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`. +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`. -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`. +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 @@ -78,3 +78,24 @@ $ consul config write okta.hcl ### Update service intentions +After you create the JWT provider entry, you can update your service intentions so that proxies validate the token before authorizing a request. The following example includes the minimum required configuration to enable JWT authorization with service intentions: + +```hcl +Kind = "service-intentions" +Name = "web" +JWT = { + Providers = [ + { + Provider = "okta" + } + ] +} +``` + +You can include additional configuration information to require the token to match specific claims. You can also configure the `JWT` field to apply only to requests that come from certain HTTP paths. Refer to [JWT validations with intentions](/consul/docs/conntect/config-entries/service-intentions#jwt-validations-with-intentions) for an example configuration. + +After you update the service intention, write the configuration to Consul so that it takes effect: + +```shell-session +$ consul config write web.hcl +``` \ No newline at end of file From 8cdeaf2dcd5666f514368775c695906488283b53 Mon Sep 17 00:00:00 2001 From: boruszak Date: Fri, 9 Jun 2023 15:10:11 -0700 Subject: [PATCH 06/12] description --- website/content/docs/connect/intentions/jwt-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/intentions/jwt-authorization.mdx b/website/content/docs/connect/intentions/jwt-authorization.mdx index d867b7c62f1..6db1a384246 100644 --- a/website/content/docs/connect/intentions/jwt-authorization.mdx +++ b/website/content/docs/connect/intentions/jwt-authorization.mdx @@ -1,7 +1,7 @@ --- page_title: JWT authorization overview description: |- - + Consul can use service mesh proxies to check and validate JSON Web Tokens (JWT) to enable additional identify-based access security for both human and machine users. Learn how to configure a JWT provider configuration entry and a service intentions configuration entry to authorize requests. --- # Use JWT authorization with service intentions From b06df87875bc32101aec6fb769013d77cf8cf2fa Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 12 Jun 2023 13:34:18 -0700 Subject: [PATCH 07/12] config entry updates --- .../connect/config-entries/jwt-provider.mdx | 249 +++++++++++------- 1 file changed, 155 insertions(+), 94 deletions(-) diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index 273ebf16f14..e4a41ad4a1f 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -19,17 +19,20 @@ The following list outlines field hierarchy, language-specific data types, and r - [`Kind`](#kind): string | required | must be set to `jwt-provider` - [`Name`](#name): string | required - [`Issuer`](#issuer): string -- [`JWKS`](#jwks): map - - [`Local`](#jwks-local): map - - [`String`](#jwks-local-string): string - - [`Filename`](#jwks-local-filename): string - - [`Remote`](#jwks-remote): map - - [`URI`](#jwks-remote-uri): string - - [`RequestTimeoutMs`](#jwks-remote-requesttimeoutms): integer - - [`CacheDuration`](#jwks-remote-cacheduration): string | `5m` - - [`FetchAsynchronously`](#jwks-remote-fetchasynchronously): boolean | `false` - - [`RetryPolicy`](#jwks-remote-retrypolicy): map - - [`NumRetries`](#jwks-remote-retrypolicy): integer | `0` +- [`JSONWebKeySet`](#jsonwebkeyset): map + - [`Local`](#jsonwebkeyset-local): map + - [`JWKS`](#jsonwebkeyset-local-jwks): string + - [`Filename`](#jsonwebkeyset-local-filename): string + - [`Remote`](#jsonwebkeyset-remote): map + - [`URI`](#jsonwebkeyset-remote-uri): string + - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms): integer + - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration): string | `5m` + - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously): boolean | `false` + - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy): map + - [`NumRetries`](#jsonwebkeyset-remote-retrypolicy-numretries): integer | `0` + - [`RetryPolicyBackoff`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): map + - [`BaseInterval`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string + - [`MaxInterval`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string - [`Audiences`](#audiences): list of strings - [`Locations`](#locations): list of maps - [`Header`](#locations-header): map @@ -58,17 +61,20 @@ The following list outlines field hierarchy, language-specific data types, and r - [`namespace`](#metadata-namespace): string - [`spec`](#spec): map | required - [`issuer`](#spec-issuer): string - - [`jwks`](#spec-jwks): map - - [`local`](#spec-jwks-local): map - - [`string`](#spec-jwks-local-string): string - - [`filename`](#spec-jwks-local-filename): string - - [`remote`](#spec-jwks-remote): map - - [`uri`](#spec-jwks-remote-uri): string - - [`requestTimeoutMs`](#spec-jwks-remote-requesttimeoutms): integer - - [`cacheDuration`](#spec-jwks-remote-cacheduration): string | `5m` - - [`fetchAsynchronously`](#spec-jwks-remote-fetchasynchronously): boolean | `false` - - [`retryPolicy`](#spec-jwks-remote-retrypolicy): map - - [`numRetries`](#spec-jwks-remote-retrypolicy): integer | `0` + - [`jsonWebKeySet`](#spec-jsonwebkeyset): map + - [`local`](#spec-jsonwebkeyset-local): map + - [`jwks`](#spec-jsonwebkeyset-local-jwks): string + - [`filename`](#spec-jsonwebkeyset-local-filename): string + - [`remote`](#spec-jsonwebkeyset-remote): map + - [`uri`](#spec-jsonwebkeyset-remote-uri): string + - [`requestTimeoutMs`](#spec-jsonwebkeyset-remote-requesttimeoutms): integer + - [`cacheDuration`](#spec-jsonwebkeyset-remote-cacheduration): string | `5m` + - [`fetchAsynchronously`](#spec-jsonwebkeyset-remote-fetchasynchronously): boolean | `false` + - [`retryPolicy`](#spec-jsonwebkeyset-remote-retrypolicy): map + - [`numRetries`](#spec-jsonwebkeyset-remote-retrypolicy-numretries): integer | `0` + - [`retryPolicyBackoff`](#spec-jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): map + - [`baseInterval`](#spec-jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string + - [`maxInterval`](#spec-jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): string - [`audiences`](#spec-audiences): list of strings - [`locations`](#spec-locations): list of maps - [`header`](#spec-locations-header): map @@ -101,13 +107,13 @@ When every field is defined, a JWT provider configuration entry has the followin Kind = "jwt-provider" # required Name = "" # required Issuer = "" # required -JWKS = { # required +JSONWebKeySet = { # required Local = { # cannot specify with JWKS{}.Remote - String = "" # cannot specify with JWKS{}.Remote{}.Filename - Filename = "" # cannot specify with JWKS{}.Remote{}.String + JWKS = "" # cannot specify with JWKS{}.Local{}.Filename + Filename = "" # cannot specify with JWKS{}.Local{}.String } } -JWKS = { +JSONWebKeySet = { Remote = { # cannot specify with JWKS{}.Local URI = "" RequestTimeoutMs = 1500 @@ -115,6 +121,10 @@ JWKS = { FetchAsynchronously = false RetryPolicy = { NumRetries = 0 + RetryPolicyBackoff = { + BaseInterval = "1s" + MaxInterval = "10s" + } } } } @@ -157,20 +167,24 @@ CacheConfig = { "Kind": "jwt-provider", // required "Name": "", // required "Issuer": "", // required -"JWKS": { // required +"JSONWebKeySet": { // required "Local": { // cannot specify with JWKS.Remote - "String": "", // cannot specify with JWKS.Local.Filename + "JWKS": "", // cannot specify with JWKS.Local.Filename "Filename": "" // cannot specify with JWKS.Local.String } }, -"JWKS": { +"JSONWebKeySet": { "Remote": { // cannot specify with JWKS.Local "URI": "", "RequestTimeoutMs": "1500", "CacheDuration": "5m", "FetchAsynchronously": "false", "RetryPolicy": { - "NumRetries": "0" + "NumRetries": "0", + "RetryPolicyBackOff": { + "BaseInterval": "1s", + "MaxInterval": "10s" + } } } }, @@ -217,18 +231,21 @@ metadata: # required namespace: spec: # required issuer: - jwks: - local: # cannot specify with spec.jwks.remote - string: # cannot specify with spec.jwks.local.filename - filename: # cannot specify with spec.jwks.local.string - jwks: - remote: # cannot specify with spec.jwks.local + jsonWebKeySet: + local: # cannot specify with spec.jsonWebKeySet.remote + jwks: # cannot specify with spec.jsonWebKeySet.local.filename + filename: # cannot specify with spec.jsonWebKeySet.local.string + jsonWebKeySet: + remote: # cannot specify with spec.jsonWebKeySet.local uri: requestTimeoutMs: 1500 cacheDuration: 5m fetchAsynchronously: false retryPolicy: numRetries: 0 + retryPolicyBackoff: + baseInterval: 1s + maxInterval: 10s audiences: [] locations: header: @@ -287,49 +304,49 @@ Specifies the provider that issued the JWT. This value must match the token’s - Default: None - Data type: String -### `JWKS` +### `JSONWebKeySet` -Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`JWKS{}.Local`](#jwks-local) and [`JWKS{}.Remote`](#jwks-remote) in the same map. +Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`JSONWebKeySet{}.Local`](#jsonwebkeyset-local) and [`JSONWebKeySet{}.Remote`](#jsonwebkeyset-remote) in the same map. #### Values - Default: None - Data type: Map that can contain one of the following parameters: - - [`Local`](#jwks-local) - - [`Remote`](#jwks-remote) + - [`Local`](#jsonwebkeyset-local) + - [`Remote`](#jsonwebkeyset-remote) -### `JWKS{}.Local` +### `JSONWebKeySet{}.Local` -Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `String` and `Filename` in the same map. +Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `JWKS` and `Filename` in the same map. #### Values - Default: None - Data type: Map that can contain one of the following parameters: - - [`String`](#jwks-local-string) - - [`Filename`](#jwks-local-filename) + - [`JWKS`](#jsonwebkeyset-local-jwks) + - [`Filename`](#jsonwebkeyset-local-filename) -### `JWKS{}.Local{}.String` +### `JSONWebKeySet{}.Local{}.JWKS` -Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `String` parameter if [`JWKS{}.Local{}.Filename`](#jwks-local-filename) is also specified in the same map. +Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `JWKS` parameter if [`JWKS{}.Local{}.Filename`](#jsonwebkeyset-local-filename) is also specified in the same map. #### Values - Default: None - Data type: String -### `JWKS{}.Local{}.Filename` +### `JSONWebKeySet{}.Local{}.Filename` -Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `Filename` parameter if [`JWKS{}.Local{}.String`](#jwks-local-string) is also specified in the same map. +Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `Filename` parameter if [`JWKS{}.Local{}.String`](#jsonwebkeyset-local-string) is also specified in the same map. #### Values - Default: None - Data type: String -### `JWKS{}.Remote` +### `JSONWebKeySet{}.Remote` Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set. @@ -338,13 +355,13 @@ Specifies a remote source for the JSON Web Key Set and configures behavior when - Default: None - Data type: Map that can contain the following parameters: - - [`URI`](#jwks-remote-uri) - - [`RequestTimeoutMs`](#jwks-remote-requesttimeoutms) - - [`CacheDuration`](#jwks-remote-cacheduration) - - [`FetchAsynchronously`](#jwks-remote-fetchasynchronously) - - [`RetryPolicy`](#jwks-remote-retrypolicy) + - [`URI`](#jsonwebkeyset-remote-uri) + - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms) + - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration) + - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously) + - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy) -### `JWKS.Remote{}.URI` +### `JSONWebKeySet{}.Remote{}.URI` Specifies the URI of the server to query for the JSON Key Web Set. @@ -353,7 +370,7 @@ Specifies the URI of the server to query for the JSON Key Web Set. - Default: None - Data type: String -### `JWKS.Remote{}.RequestTimeoutMs` +### `JSONWebKeySet{}.Remote{}.RequestTimeoutMs` Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms). @@ -362,7 +379,7 @@ Specifies the length of time before a request to the remote URI times out, measu - Default: None - Data type: Integer -### `JWKS.Remote{}.CacheDuration` +### `JSONWebKeySet{}.Remote{}.CacheDuration` Specifies the amount of time cached keys are available before they expire. @@ -373,7 +390,7 @@ The default cache duration is 5 minutes. - Default: `5m` - Data type: String -### `JWKS.Remote{}.FetchAsynchronously` +### `JSONWebKeySet{}.Remote{}.FetchAsynchronously` Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating. @@ -384,18 +401,40 @@ This parameter is set to `false` by default. - Default: `false` - Data type: Boolean -### `JWKS.Remote{}.RetryPolicy` +### `JSONWebKeySet{}.Remote{}.RetryPolicy` Defines a retry policy when fetching the JSON Web Key Set from the remote location. #### Values - Default: None -- Data type: Map that contains the following parameter: +- Data type: Map that can contain the following parameters: + + - [`NumRetries`](#jsonwebkeyset-remote-retrypolicy-numretries) + - [`RetryPolicyBackoff`](#jsonwebkeyset-remote-retrypolicy-retrypolicybackoff) + +### `JSONWebKeySet{}.Remote{}.RetryPolicy{}.NumRetries` + +Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. + +#### Values + +- Default: `0` +- Data type: Integer -| Parameter | Description | Data type | Default value| -| -------------- | --------------- | ------------- | ---------------- | -| `NumRetries`| Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. | Integer | `0` | +## `JSONWebKeySet{}.Remote{}.RetryPolicy{}.RetryPolicyBackoff` + +Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `BaseInterval`| Specifies the base interval to use for the next back off computation. | String | `1s` | +| `MaxInterval` | Specifies the maximum interval between retries. By default, this value is 10 times `BaseInterval`. | String | `10s` | ### `Audiences` @@ -623,19 +662,19 @@ Specifies the provider that issued the JWT. This value must match the token’s - Default: None - Data type: String -### `spec.jwks` +### `spec.jsonWebKeySet` -Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`spec.jwks.local`](#spec-jwks-local) and [`spec.jwks.remote`](#spec-jwks-remote) in the same map. +Defines a JSON Web Key Set. This field can be configured for a local file, or it can specify instructions to fetch a key set from a remote server. You cannot specify [`spec.jsonWebKeySet.local`](#spec-jsonwebkeyset-local) and [`spec.jsonWebKeySet.remote`](#spec-jsonwebkeyset-remote) in the same map. #### Values - Default: None - Data type: Map that can contain one of the following parameters: - - [`local`](#spec-jwks-local) - - [`remote`](#spec-jwks-remote) + - [`local`](#spec-jsonwebkeyset-local) + - [`remote`](#spec-jsonwebkeyset-remote) -### `spec.jwks.local` +### `spec.jsonWebKeySet.local` Specifies a local source for the JSON Web Key Set. You can specify the source as a string in the configuration entry or you can include a local filename that contains the set. You cannot specify both `string` and `filename` in the same map. @@ -644,28 +683,28 @@ Specifies a local source for the JSON Web Key Set. You can specify the source as - Default: None - Data type: Map that can contain one of the following parameters: - - [`string`](#spec-jwks-local-string) - - [`filename`](#spec-jwks-local-filename) + - [`jwks`](#spec-jsonwebkeyset-local-jwks) + - [`filename`](#spec-jsonwebkeyset-local-filename) -### `spec.jwks.local.string` +### `spec.jsonWebKeySet.local.jwks` -Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `string` parameter if [`spec.jwks.local.filename`](#spec-jwks-local-filename) is also specified in the same map. +Specifies the JSON Web Key Set that validates the JWT’s signature, formatted as a base64 encoded string. You cannot specify the `jwks` parameter if [`spec.jsonWebKeySet.local.filename`](#spec-jsonwebkeyset-local-filename) is also specified in the same map. #### Values - Default: None - Data type: String -### `spec.jwks.local.filename` +### `spec.jsonWebKeySet.local.filename` -Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `filename` parameter if [`spec.jwks.local.string`](#spec-jwks-local-string) is also specified in the same map. +Specifies the path to the JSON Web Key Set’s location on the local disk. When this field is specified, the file must be present on the disk for all proxies with service intentions referencing this provider. You cannot specify the `filename` parameter if [`spec.jsonWebKeySet.local.jwks`](#spec-jsonwebkeyset-local-jwks) is also specified in the same map. #### Values - Default: None - Data type: String -### `spec.jwks.remote` +### `spec.jsonWebKeySet.remote` Specifies a remote source for the JSON Web Key Set and configures behavior when fetching the key set. @@ -674,13 +713,13 @@ Specifies a remote source for the JSON Web Key Set and configures behavior when - Default: None - Data type: Map that can contain the following parameters: - - [`uri`](#spec-jwks-remote-uri) - - [`requestTimeoutMs`](#spec-jwks-remote-requesttimeoutms) - - [`cacheDuration`](#spec-jwks-remote-cacheduration) - - [`fetchAsynchronously`](#spec-jwks-remote-fetchasynchronously) - - [`retryPolicy`](#spec-jwks-remote-retrypolicy) + - [`uri`](#spec-jsonwebkeyset-remote-uri) + - [`requestTimeoutMs`](#spec-jsonwebkeyset-remote-requesttimeoutms) + - [`cacheDuration`](#spec-jsonwebkeyset-remote-cacheduration) + - [`fetchAsynchronously`](#spec-jsonwebkeyset-remote-fetchasynchronously) + - [`retryPolicy`](#spec-jsonwebkeyset-remote-retrypolicy) -### `spec.jwks.remote.uri` +### `spec.jsonWebKeySet.remote.uri` Specifies the URI of the server to query for the JSON Key Web Set. @@ -689,7 +728,7 @@ Specifies the URI of the server to query for the JSON Key Web Set. - Default: None - Data type: String -### `spec.jwks.remote.requestTimeoutMs` +### `spec.jsonWebKeySet.remote.requestTimeoutMs` Specifies the length of time before a request to the remote URI times out, measured in milliseconds (ms). @@ -698,7 +737,7 @@ Specifies the length of time before a request to the remote URI times out, measu - Default: None - Data type: Integer -### `spec.jwks.remote.cacheDuration` +### `spec.jsonWebKeySet.remote.cacheDuration` Specifies the amount of time cached keys are available before they expire. @@ -709,7 +748,7 @@ The default cache duration is 5 minutes. - Default: `5m` - Data type: String -### `spec.jwks.remote.fetchAsynchronously` +### `spec.jsonWebKeySet.remote.fetchAsynchronously` Determines if the JSON Web Key Set is fetched before a client request arrives. When enabled, the JWKS is fetched before incoming requests. When not enabled, the JWKS is fetched after each request arrives and the proxy listener waits for the JWKS to be fetched before activating. @@ -720,7 +759,7 @@ This parameter is set to `false` by default. - Default: `false` - Data type: Boolean -### `spec.jwks.remote.retryPolicy` +### `spec.jsonWebKeySet.remote.retryPolicy` Defines a retry policy when fetching the JSON Web Key Set from the remote location. @@ -729,9 +768,31 @@ Defines a retry policy when fetching the JSON Web Key Set from the remote locati - Default: None - Data type: Map that contains the following parameter: -| Parameter | Description | Data type | Default value | -| :---------- | :------------------------------------------------------------------------------------------------------ | :-------- | :------------ | -| `numRetries`| Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. | Integer | `0` | + - [`numRetries`](#spec-jsonwebkeyset-remote-retrypolicy-numretries) + - [`retryPolicyBackoff`](#spec-jsonwebkeyset-remote-retrypolicy-retrypolicybackoff) + +### `spec.jsonWebKeySet.remote.retryPolicy.numRetries` + +Specifies the number of times to attempt to fetch the JSON Web Key Set when the previous attempt fails. + +#### Values + +- Default: `0` +- Data type: Integer + +## `spec.jsonWebKeySet.remote.retryPolicy.retryPolicyBackoff` + +Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `baseInterval`| Specifies the base interval to use for the next back off computation. | String | `1s` | +| `maxInterval` | Specifies the maximum interval between retries. By default, this value is 10 times `BaseInterval`. | String | `10s` | ### `spec.audiences` @@ -909,9 +970,9 @@ Name = "okta" Issuer = "okta" -JWKS = { +JSONWebKeySet = { Remote = { - URI = "https://dev-850216.okta.com/oauth2/default/v1/keys" + URI = "https://.okta.com/oauth2/default/v1/keys" CacheDuration = "30m" } } @@ -930,9 +991,9 @@ Forwarding = { "Kind": "jwt-provider", "Name": "okta", "Issuer": "okta", - "JWKS": { + "JSONWebKeySet": { "Remote": { - "URI": "https://dev-850216.okta.com/oauth2/default/v1/keys", + "URI": "https://.okta.com/oauth2/default/v1/keys", "CacheDuration": "30m" } }, @@ -953,9 +1014,9 @@ metadata: name: okta spec: issuer: okta - jwks: + jsonwebkeyset: remote: - uri: https://dev-850216.okta.com/oauth2/default/v1/keys + uri: https://.okta.com/oauth2/default/v1/keys cacheDuration: 30m forwarding: headerName: user-token From 8c3666e422b5904c2b0ffa18828074d6233214c9 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 12 Jun 2023 13:37:43 -0700 Subject: [PATCH 08/12] formatting fixes --- .../content/docs/connect/config-entries/jwt-provider.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index e4a41ad4a1f..47c7eed6753 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -422,7 +422,7 @@ Specifies the number of times to attempt to fetch the JSON Web Key Set when the - Default: `0` - Data type: Integer -## `JSONWebKeySet{}.Remote{}.RetryPolicy{}.RetryPolicyBackoff` +### `JSONWebKeySet{}.Remote{}.RetryPolicy{}.RetryPolicyBackoff` Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval. @@ -615,7 +615,7 @@ Specifies the type of configuration entry to implement. Must be set to `jwtProvi - This field is required. - Data type: String value that must be set to `jwtProvider`. -## `metadata` +### `metadata` Map that contains an arbitrary name for the configuration entry and the namespace it applies to. @@ -780,7 +780,7 @@ Specifies the number of times to attempt to fetch the JSON Web Key Set when the - Default: `0` - Data type: Integer -## `spec.jsonWebKeySet.remote.retryPolicy.retryPolicyBackoff` +### `spec.jsonWebKeySet.remote.retryPolicy.retryPolicyBackoff` Specifies a jittered exponential backoff strategy. When this field is empty, Envoy's default policy is used. This policy has a 1 second base interval and a 10 second max interval. From 710beffcdf50077f5d72c9ff0c8600de76769453 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Mon, 12 Jun 2023 13:45:33 -0700 Subject: [PATCH 09/12] Update website/content/docs/connect/config-entries/service-intentions.mdx Co-authored-by: Paul Glass --- .../content/docs/connect/config-entries/service-intentions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index a5440b02ca8..15f3b863e12 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -1453,7 +1453,7 @@ When using cluster peering connections, intentions secure your deployments with ### JWT validation with intentions -The following example configures a service intention that evaluates requests when a service named `backend` receives a request from the `frontend` service. When the request comes from from the `/admin` HTTP path, a JSON Web Token provided by Okta is evaluated. In addition to the validation requirements in a separate JWT provider configuration entry, an additional check occurs to confirm that the token has either a `perms` or `role` claim with the `admin` value. If it does, the request is authorized. +The following example configures a service intention that evaluates requests when a service named `backend` receives a request from the `frontend` service. When the request is sent to the `/admin` HTTP path, a JSON Web Token provided by Okta is evaluated. In addition to the validation requirements in a separate JWT provider configuration entry, an additional check occurs to confirm that the token has either a `perms` or `role` claim with the `admin` value. If it does, the request is authorized. Because the intention allows requests that come from the `/` HTTP path, only requests on the `/admin` path are subject to token validation. From 0affa404820cd5d2a9cdbbac42f2597a68f9d11c Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 12 Jun 2023 13:49:17 -0700 Subject: [PATCH 10/12] service intentions review fixes --- .../config-entries/service-intentions.mdx | 64 +++++++------------ 1 file changed, 24 insertions(+), 40 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 15f3b863e12..d8e3840e44a 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -24,7 +24,7 @@ The following outline shows how to format the service intentions configuration e - [`Meta`](#meta): map - [`JWT`](#jwt): map - [`Providers`](#jwt-providers): list of maps - - [`Provider`](#jwt-providers-provider): string + - [`Name`](#jwt-providers-name): string - [`VerifyClaims`](#jwt-provider-verifyclaims): list of maps - [`Path`](#jwt-provider-verifyclaims-path): list of strings - [`Value`](#jwt-provider-verifyclaims-value): string @@ -40,7 +40,7 @@ The following outline shows how to format the service intentions configuration e - [`PathExact`](#sources-permissions-http): string - [`PathPrefix`](#sources-permissions-http): string - [`PathRegex`](#sources-permissions-http): string - - [`Methods`](#sources-permissions-http): list | no default + - [`Methods`](#sources-permissions-http): list - [`Header`](#sources-permissions-http-header): list of maps - [`Name`](#sources-permissions-http-header): string | required - [`Present`](#sources-permissions-http-header): boolean | `false` @@ -49,13 +49,13 @@ The following outline shows how to format the service intentions configuration e - [`Suffix`](#sources-permissions-http-header): string - [`Regex`](#sources-permissions-http-header): string - [`Invert`](#sources-permissions-http-header): boolean | `false` - - [`Precedence`](#sources-precedence): number + - [`Precedence`](#sources-precedence): number - [`Type`](#sources-type): string | `consul` - [`Description`](#sources-description): string - [`LegacyID`](#sources-legacyid): string - [`LegacyMeta`](#sources-legacymeta): map - - [`LegacyCreateTime`](#sources-legacycreatetime): string - - [`LegacyUpdateTime`](#sources-legacyupdatetime): string + - [`LegacyCreateTime`](#sources-legacycreatetime): string + - [`LegacyUpdateTime`](#sources-legacyupdatetime): string @@ -71,7 +71,7 @@ The following outline shows how to format the service intentions configuration e - [`namespace`](#metadata-namespace): string | `default` | - [`jwt`](#spec-jwt): map - [`providers`](#spec-jwt-providers): list of maps - - [`provider`](#spec-jwt-providers-provider): string + - [`name`](#spec-jwt-providers-name): string - [`verifyClaims`](#spec-jwt-provider-verifyclaims): list of maps - [`path`](#spec-jwt-provider-verifyclaims-path): list of strings - [`value`](#spec-jwt-provider-verifyclaims-value): string @@ -122,7 +122,7 @@ Meta = { JWT = { Providers = [ { - Provider = "" + Name = "" VerifyClaims = [ { Path = [""] @@ -203,7 +203,7 @@ spec: namespace: jwt: providers: - provider: + name: verifyClaims: path: [] value: @@ -254,7 +254,7 @@ spec: "JWT": { "Providers": [ { - "Provider": "", + "Name": "", "VerifyClaims": [ { "Path": [""], @@ -396,14 +396,14 @@ Specifies a JSON Web Token provider configured in a [JWT provider configuration ### `JWT{}.Providers` -Specifies the names of one or more previously configured [JWT provider configuration entries](/consul/docs/connect/config-entries/jwt-provider), which include the information necessary to calidate a JSON web token. +Specifies the names of one or more previously configured [JWT provider configuration entries](/consul/docs/connect/config-entries/jwt-provider), which include the information necessary to validate a JSON web token. #### Values - Default: None - Data type: List of maps -### `JWT{}.Providers[].Provider` +### `JWT{}.Providers[].Name` Specifies the name of a JWT provider defined in the `Name` field of the [`jwt-provider` configuration entry](/consul/docs/connect/config-entries/jwt-provider). You must write the JWT Provider to Consul before referencing it in a service intention. @@ -420,7 +420,7 @@ Specifies additional token information to verify beyond what is configured in th - Default: None - Data type: List of maps that can contain the following parameters: -- + - [`Path`](#jwt-providers-verifyclaims-path) - [`Value`](#jwt-providers-verifyclaims-value) @@ -431,15 +431,7 @@ Specifies the path to the claim in the JSON web token. For more information abou #### Values - Default: None -- Data type: List of strings that can contain one of the following values: - - - `iss`: Issuer claim - - `sub`: Subject claim - - `aud`: Audience claim - - `exp`: Expiration Time claim - - `nbf`: Not Before claim - - `iat`: Issued At claim - - `jti`: JWT ID claim +- Data type: List of strings ### `JWT{}.Providers[].VerifyClaims.Value` @@ -607,7 +599,6 @@ Each member of the `Header` list is a map that contains a `Name` field and at le | `Regex` | Specifies a regular expression pattern as the value for the header key set in the `Name` field. If the request header value matches the regex, Consul applies the permission. Do not specify `Regex` if `Present`, `Exact`, `Prefix`, or `Suffix` are configured in the same `Header` configuration. The regex syntax is proxy-specific. If using Envoy, refer to the [re2 documentation](https://github.com/google/re2/wiki/Syntax) for details. | string | optional | | `Invert` | Inverts the matching logic configured in the `Header`. Default is `false`. | boolean | optional | - ### `Sources[].Precedence` The `Precedence` field contains a read-only integer. Consul generates the value based on name configurations for the source and destination services. Refer to [Precedence and matching order](/consul/docs/connect/intentions/create-manage-intentions#precedence-and-matching-order) for additional information. @@ -701,23 +692,24 @@ Specifies the [namespace](/consul/docs/enterprise/namespaces) that the configura - Data type: String ### `spec` + Map that contains the details about the `ServiceIntentions` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. #### Values - Default: None - This field is required. -- Data type: Map +- Data type: Map ### `spec.destination` -Map that identifies the destination name and destination namespace that source services are allowed or denied access to. +Map that identifies the destination name and destination namespace that source services are allowed or denied access to. #### Values - Default: None - This field is required. -- Data type: Map +- Data type: Map ### `spec.destination.name` @@ -741,14 +733,14 @@ Specifies a JSON Web Token provider configured in a [JWT provider configuration ### `spec.jwt.providers` -Specifies the names of one or more previously configured [JWT provider configuration entries](/consul/docs/connect/config-entries/jwt-provider), which include the information necessary to calidate a JSON web token. +Specifies the names of one or more previously configured [JWT provider configuration entries](/consul/docs/connect/config-entries/jwt-provider), which include the information necessary to validate a JSON web token. #### Values - Default: None - Data type: List of maps -### `spec.jwt.providers[].provider` +### `spec.jwt.providers[].name` Specifies the name of a JWT provider defined in the `metadata.name` field of the [JWT provider configuration entry](/consul/docs/connect/config-entries/jwt-provider). You must write the JWT Provider to Consul before referencing it in a service intention. @@ -765,7 +757,7 @@ Specifies additional token information to verify beyond what is configured in th - Default: None - Data type: List of maps that can contain the following parameters: -- + - [`path`](#spec-jwt-providers-verifyclaims-path) - [`value`](#spec-jwt-providers-verifyclaims-value) @@ -776,15 +768,7 @@ Specifies the path to the claim in the JSON web token. For more information abou #### Values - Default: None -- Data type: List of strings that can contain one of the following values: - - - `iss`: Issuer claim - - `sub`: Subject claim - - `aud`: Audience claim - - `exp`: Expiration Time claim - - `nbf`: Not Before claim - - `iat`: Issued At claim - - `jti`: JWT ID claim +- Data type: List of strings ### `spec.jwt.providers[].verifyClaims[].value` @@ -1473,7 +1457,7 @@ Sources = [ JWT = { Providers = [ { - Provider = "okta" + Name = "okta" VerifyClaims = [ { Path = ["perms", "role"] @@ -1508,7 +1492,7 @@ Sources = [ pathExact: /admin jwt: providers: - provider: okta + name: okta verifyClaims: path: - perms @@ -1534,7 +1518,7 @@ Sources = [ "JWT": { "Providers": [ { - "Provider": "okta", + "Name": "okta", "VerifyClaims": [ { "Path": ["perms", "role"], From 22d32daf09e0b833b238c55b2b8d8fe0bb2bc9d1 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 12 Jun 2023 13:52:06 -0700 Subject: [PATCH 11/12] Overview page review fixes --- .../docs/connect/intentions/jwt-authorization.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/content/docs/connect/intentions/jwt-authorization.mdx b/website/content/docs/connect/intentions/jwt-authorization.mdx index 6db1a384246..6812c282acb 100644 --- a/website/content/docs/connect/intentions/jwt-authorization.mdx +++ b/website/content/docs/connect/intentions/jwt-authorization.mdx @@ -38,7 +38,7 @@ The `jwt-provider` configuration requires the following fields: - `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: +You must also specify a JSON Web Key Set in the `JSONWebKeySet` field. You can specify the JWKS as one of the following: - A local string - A path to a local file @@ -56,9 +56,9 @@ Name = "okta" Issuer = "okta" -JWKS = { +JSONWebKeySet = { Remote = { - URI = "https://dev-850216.okta.com/oauth2/default/v1/keys" + URI = "https://.okta.com/oauth2/default/v1/keys" CacheDuration = "30m" } } @@ -73,7 +73,7 @@ Refer to [JWT provider configuration entry](/consul/docs/connect/config-entries/ To write the configuration entry to Consul, use the [`consul config write` command](/consul/commands/config/write): ```shell-session -$ consul config write okta.hcl +$ consul config write okta-provider.hcl ``` ### Update service intentions @@ -86,7 +86,7 @@ Name = "web" JWT = { Providers = [ { - Provider = "okta" + Name = "okta" } ] } @@ -97,5 +97,5 @@ You can include additional configuration information to require the token to mat After you update the service intention, write the configuration to Consul so that it takes effect: ```shell-session -$ consul config write web.hcl +$ consul config write web-intention.hcl ``` \ No newline at end of file From 87d2c37bcf7016c3c6ffa8f7df1246f4a4789ca9 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Mon, 12 Jun 2023 14:39:58 -0700 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/connect/config-entries/jwt-provider.mdx | 12 ++++++------ .../docs/connect/intentions/jwt-authorization.mdx | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index 47c7eed6753..3ad00483c6c 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -489,7 +489,7 @@ Specifies the name of the HTTP request header containing the token. Specifies a prefix that must precede the token in the header value. -For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token itself. +For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token. #### Values @@ -498,9 +498,9 @@ For example, `Bearer` is a standard value prefix for a header named "Authorizati ### `Locations[].Header{}.Forward` -Specifies whether the header with the JWT is forwarded after the token is verified. When set to false, the header is not forwarded. +Specifies whether the header with the JWT is forwarded after the token is verified. When set to `false`, the header is not forwarded. -The default value is false. +The default value is `false`. #### Values @@ -847,7 +847,7 @@ Specifies the name of the HTTP request header containing the token. Specifies a prefix that must precede the token in the header value. -For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token itself. +For example, `Bearer` is a standard value prefix for a header named "Authorization" that is formatted as `Authorization: Bearer `. The prefix is not part of the token. #### Values @@ -856,9 +856,9 @@ For example, `Bearer` is a standard value prefix for a header named "Authorizati ### `spec.locations[].header.forward` -Specifies whether the header with the JWT is forwarded after the token is verified. When set to false, the header is not forwarded. +Specifies whether the header with the JWT is forwarded after the token is verified. When set to `false`, the header is not forwarded. -The default value is false. +The default value is `false`. #### Values diff --git a/website/content/docs/connect/intentions/jwt-authorization.mdx b/website/content/docs/connect/intentions/jwt-authorization.mdx index 6812c282acb..a58bd3af3e1 100644 --- a/website/content/docs/connect/intentions/jwt-authorization.mdx +++ b/website/content/docs/connect/intentions/jwt-authorization.mdx @@ -14,7 +14,7 @@ By specifying a JSON Web Key Set (JWKS) in the configuration entry and referenci The process to configure your network to enforce service intentions based on JSON web tokens consists of the following steps: -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`. +1. **Create a JWT provider configuration entry**. This configuration entry defines rules and behaviors for verifying tokens. These configurations apply to admin partitions 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`. 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`. @@ -22,7 +22,7 @@ The process to configure your network to enforce service intentions based on JSO Because intentions without tokens are authorized when they arrive at the destination proxy, a [common pattern for the service-intentions configuration entry](/consul/docs/connect/config-entries/service-intentions#l4-intentions-for-all-destinations) sets the entry’s `Name` field as a wildcard, `*`. This pattern enables you to apply incoming requests from specific services to every service in the datacenter. -When configuring your deployment to enforce service intentions with JSON Web Tokens, it is possible for multiple tokens with different permissions to apply to a single service’s incoming request based on attributes such as HTTP path or the request method. Because the `service-intentions` configuration entry applies the intention that is the most exact match for the request, using the `Name` wildcard with specific JWT authorization configurations can lead to unintended results. +When configuring your deployment to enforce service intentions with JSON Web Tokens, it is possible for multiple tokens with different permissions to apply to a single service’s incoming request based on attributes such as HTTP path or the request method. Because the `service-intentions` configuration entry applies the intention that most closely matches the request, using the `Name` wildcard with specific JWT authorization configurations can lead to unintended results. 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.