Skip to content

Commit

Permalink
Backport of Add docs for jwt cluster configuration into release/1.16.x (
Browse files Browse the repository at this point in the history
#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

<!-- Please describe why you're making this change, in plain English.
-->

- 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>
  • Loading branch information
1 parent de1bcd7 commit a5c713a
Showing 1 changed file with 255 additions and 0 deletions.
255 changes: 255 additions & 0 deletions website/content/docs/connect/config-entries/jwt-provider.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 = [
{
Expand Down Expand Up @@ -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>"
}
}
}
}
},
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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`

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit a5c713a

Please sign in to comment.