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: #17978 --- <details> <summary> Overview of commits </summary> - 1ab3c3b </details> Co-authored-by: Ronald Ekambi <ronekambi@gmail.com>
hashicorp · Jul 14, 2023 · a5c713a · a5c713a
1 parent de1bcd7
commit a5c713a
Showing 1 changed file with 255 additions and 0 deletions.
diff --git 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 = "<path/to/cert/file>"
+                EnvironmentVariable = "<env-variable>"
+                InlineString = "<inline-string>"
+                InlineBytes = "\302\000\302\302\302\302"
+              }
+            }
+            TLSCertificates = {
+              CaCertificateProviderInstance = {
+                InstanceName = "<instance-name>"
+                CertificateName = "<certificate-name>"
+              }
+            }
+          }
         }
       }
+
 Audiences = ["<aud-claims>"]
 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": "<path/to/cert/file>",
+                "EnvironmentVariable": "<env-variable>",
+                "InlineString": "<inline-string>",      
+                "InlineBytes": "\302\000\302\302\302\302"
+            },
+            "TLSCertificates": {
+              "CaCertificateProviderInstance": {
+                "InstanceName": "<instance-name>",
+                "CertificateName": "<certificate-name>"
+              }
+            }
           }
         }
 },
@@ -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: <path/to/cert/file>           
+            environmentVariable: <env-variable>
+            inlineString: <inline-string>
+            inlineBytes: \302\000\302\302\302\302   
+        tlsCertificates:
+          caCertificateProviderInstance:
+            instanceName: <instance-name>
+            certificateName: <certificate-name>
   audiences: [<aud-claims>]
   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.