From 792812e196d73a1821006964855ae410920cb1cd Mon Sep 17 00:00:00 2001 From: hc-github-team-consul-core Date: Fri, 14 Jul 2023 06:26:38 -0500 Subject: [PATCH] Backport of Add docs for jwt cluster configuration into release/1.16.x (#18135) ## Backport This PR is auto-generated from #18004 to be assessed for backporting due to the inclusion of the label backport/1.16. The below text is copied from the body of the original PR. --- ### Description - Add jwt-provider docs for jwks cluster configuration. The configuration was added here: https://github.com/hashicorp/consul/pull/17978 ---
Overview of commits - 1ab3c3be1e85f4b70a0eafbc875a28311f030e49
Co-authored-by: Ronald Ekambi --- .../connect/config-entries/jwt-provider.mdx | 255 ++++++++++++++++++ 1 file changed, 255 insertions(+) diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx index 8867a3e4f..8716dde8c 100644 --- a/website/content/docs/connect/config-entries/jwt-provider.mdx +++ b/website/content/docs/connect/config-entries/jwt-provider.mdx @@ -28,6 +28,18 @@ The following list outlines field hierarchy, language-specific data types, and r - [`RequestTimeoutMs`](#jsonwebkeyset-remote-requesttimeoutms): integer - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration): string | `5m` - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously): boolean | `false` + - [`JWKSCluster`](#jsonwebkeyset-remote-jwkscluster): map + - [`DiscoveryType`](#jsonwebkeyset-remote-jwkscluster-discoverytype): string | `STRICT_DNS` + - [`ConnectTimeout`](#jsonwebkeyset-remote-jwkscluster-connecttimeout): string | `5s` + - [`TLSCertificates`](#jsonwebkeyset-remote-jwkscluster-tlscertificates): map + - [`CaCertificateProviderInstance`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): map + - [`InstanceName`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string | `default` + - [`CertificateName`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string + - [`TrustedCA`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): map + - [`Filename`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string + - [`EnvironmentVariable`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string + - [`InlineString`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string + - [`InlineBytes`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy): map - [`NumRetries`](#jsonwebkeyset-remote-retrypolicy-numretries): integer | `0` - [`RetryPolicyBackoff`](#jsonwebkeyset-remote-retrypolicy-retry-policy-backoff): map @@ -75,6 +87,18 @@ The following list outlines field hierarchy, language-specific data types, and r - [`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 + - [`jwksCluster`](#spec-jsonwebkeyset-remote-jwkscluster): map + - [`discoveryType`](#spec-jsonwebkeyset-remote-jwkscluster-discoverytype): string | `STRICT_DNS` + - [`connectTimeout`](#spec-jsonwebkeyset-remote-jwkscluster-connecttimeout): string | `5s` + - [`tlsCertificates`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates): map + - [`caCertificateProviderInstance`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): map + - [`instanceName`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string | `default` + - [`certificateName`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance): string + - [`trustedCA`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): map + - [`filename`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string + - [`environmentVariable`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string + - [`inlineString`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string + - [`inlineBytes`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca): string - [`audiences`](#spec-audiences): list of strings - [`locations`](#spec-locations): list of maps - [`header`](#spec-locations-header): map @@ -126,8 +150,29 @@ JSONWebKeySet = { MaxInterval = "10s" } } + JWKSCluster = { + DiscoveryType = "STATIC" + ConnectTimeout = "10s" + # specify only one child: TrustedCA or CaCertificateProviderInstance + TLSCertificates = { + # specify only one child: Filename, EnvironmentVariable, InlineString or InlineBytes + TrustedCA = { + Filename = "" + EnvironmentVariable = "" + InlineString = "" + InlineBytes = "\302\000\302\302\302\302" + } + } + TLSCertificates = { + CaCertificateProviderInstance = { + InstanceName = "" + CertificateName = "" + } + } + } } } + Audiences = [""] Locations = [ { @@ -185,6 +230,25 @@ CacheConfig = { "BaseInterval": "1s", "MaxInterval": "10s" } + }, + "JWKSCluster": { + "DiscoveryType": "STATIC", + "ConnectTimeout": "10s", + // specify only one child: TrustedCA or CaCertificateProviderInstance + "TLSCertificates": { + // specify only one child: Filename, EnvironmentVariable, InlineString or InlineBytes + "TrustedCA": { + "Filename": "", + "EnvironmentVariable": "", + "InlineString": "", + "InlineBytes": "\302\000\302\302\302\302" + }, + "TLSCertificates": { + "CaCertificateProviderInstance": { + "InstanceName": "", + "CertificateName": "" + } + } } } }, @@ -246,6 +310,21 @@ spec: # required retryPolicyBackoff: baseInterval: 1s maxInterval: 10s + jwksCluster: + discoveryType: STATIC + connectTimeout: 10s + # specify only one child: trustedCA or caCertificateProviderInstance + tlsCertificates: + # specify only one child: filename, environmentVariable, inlineString or inlineBytes + trustedCA: + filename: + environmentVariable: + inlineString: + inlineBytes: \302\000\302\302\302\302 + tlsCertificates: + caCertificateProviderInstance: + instanceName: + certificateName: audiences: [] locations: header: @@ -360,6 +439,7 @@ Specifies a remote source for the JSON Web Key Set and configures behavior when - [`CacheDuration`](#jsonwebkeyset-remote-cacheduration) - [`FetchAsynchronously`](#jsonwebkeyset-remote-fetchasynchronously) - [`RetryPolicy`](#jsonwebkeyset-remote-retrypolicy) + - [`JWKSCluster`](#jsonwebkeyset-remote-jwkscluster) ### `JSONWebKeySet{}.Remote{}.URI` @@ -436,6 +516,93 @@ Specifies a jittered exponential backoff strategy. When this field is empty, Env | `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` | +### `JSONWebKeySet{}.Remote{}.JWKSCluster` + +Defines how Envoy fetches the remote JSON Web Key Set URI. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`DiscoveryType`](#jsonwebkeyset-remote-jwkscluster-discoverytype) + - [`ConnectTimeout`](#jsonwebkeyset-remote-jwkscluster-connecttimeout) + - [`TLSCertificates`](#jsonwebkeyset-remote-jwkscluster-tlscertificates) + + +### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.DiscoveryType` + +Specifies the service discovery type to use for resolving the cluster. +You can specify the following discovery types: +- `STRICT_DNS` +- `STATIC` +- `LOGICAL_DNS` +- `EDS` +- `ORIGINAL_DST` + +#### Values + +- Default: `STRICT_DNS` +- Data type: String + +### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.ConnectTimeout` + +Specifies the duration of time new network connections attempt to connect to hosts in the cluster before they timeout. + +#### Values + +- Default: `5s` +- Data type: String + +### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates` + +Specifies the data containing certificate authority certificates to use for verifying a presented peer certificate. +Envoy does not verify certificates that peers present if this field is not configured. + +You cannot specify [`TLSCertificates{}.CaCertificateProviderInstance`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance) and [`TLSCertificates{}.TrustedCA`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca) in the same map. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`CaCertificateProviderInstance`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance) + - [`TrustedCA`](#jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca) + +### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.CaCertificateProviderInstance` + +Speficies the certificate provider instance for fetching TLS certificates. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `InstanceName`| Refers to the certificate provider instance name. | String | `default` | +| `CertificateName` | Specifies the certificate instances or types. For example, use `ROOTCA` to specify a root-certificate. | String | None | + +### `JSONWebKeySet{}.Remote{}.JWKSCluster{}.TLSCertificates{}.TrustedCA` + +Specifies TLS certificate data containing certificate authority certificates. Specify exactly one of the following data holders: +- `Filename` +- `EnvironmentVariable` +- `InlineString` +- `InlineBytes` + +#### Values + +- Default: None +- Data type: Map containing one of the following parameters: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `Filename`| The name of the file on the local system to use a data source for trusted CA certificates. | String | None | +| `EnvironmentVariable` | The environment variable on the local system to use a data source for trusted CA certificates. | String | None | +| `InlineString` | A string to inline in the configuration for use as a data source for trusted CA certificates. | String | None | +| `InlineBytes` | A sequence of bytes to inline in the configuration for use as a data source for trusted CA certificates. | String | None | + ### `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. @@ -794,6 +961,94 @@ Specifies a jittered exponential backoff strategy. When this field is empty, Env | `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.jsonWebKeySet.remote.jwksCluster` + +Defines how Envoy fetches the remote JSON Web Key Set URI. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`discoveryType`](#spec-jsonwebkeyset-remote-jwkscluster-discoverytype) + - [`connectTimeout`](#spec-jsonwebkeyset-remote-jwkscluster-connecttimeout) + - [`tlsCertificates`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates) + +### `spec.jsonWebKeySet.remote.jwksCluster.discoveryType` + +Specifies the service discovery type to use for resolving the cluster. +You can specify the following discovery types: +- `STRICT_DNS` +- `STATIC` +- `LOGICAL_DNS` +- `EDS` +- `ORIGINAL_DST` + +String values must be a valid [Cluster DiscoveryType](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-enum-config-cluster-v3-cluster-discoverytype). + +#### Values + +- Default: `STRICT_DNS` +- Data type: String + +### `spec.jsonWebKeySet.remote.jwksCluster.connectTimeout` + +Specifies the timeout for new network connections to hosts in the cluster. + +#### Values + +- Default: `5s` +- Data type: String + +### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates` + +Specifies the data containing certificate authority certificates to use for verifying a presented peer certificate. +Envoy does not verify certificates that peers present if this field is not configured. + +You cannot specify [`spec.tlsCertificates.caCertificateProviderInstance`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance) and [`spec.tlsCertificates.trustedCA`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca) in the same map. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + + - [`caCertificateProviderInstance`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-cacertificateproviderinstance) + - [`trustedCA`](#spec-jsonwebkeyset-remote-jwkscluster-tlscertificates-trustedca) + +### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.caCertificateProviderInstance` + +Speficies the certificate provider instance for fetching TLS certificates. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `instanceName`| Refers to the certificate provider instance name. | String | `default` | +| `certificateName` | Specifies the certificate instances or types. For example, use `ROOTCA` to specify a root-certificate. | String | None | + +### `spec.jsonWebKeySet.remote.jwksCluster.tlsCertificates.trustedCA` + +Specifies TLS certificate data containing certificate authority certificates. Specify exactly one of the following data holders: +- `Filename` +- `EnvironmentVariable` +- `InlineString` +- `InlineBytes` + +#### Values + +- Default: None +- Data type: Map containing one of the following parameters: + +| Parameter | Description | Data type | Default value | +| :-------- | :------------------------------------------------- | :-------- | :------------ | +| `filename`| The name of the file on the local system to use a data source for trusted CA certificates. | String | None | +| `environmentVariable` | The environment variable on the local system to use a data source for trusted CA certificates. | String | None | +| `inlineString` | A string to inline in the configuration for use as a data source for trusted CA certificates. | String | None | +| `inlineBytes` | A sequence of bytes to inline in the configuration for use as a data source for trusted CA certificates. | String | None | + ### `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.