Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for jwt cluster configuration #18004

Merged
merged 1 commit into from
Jul 14, 2023
Merged

Add docs for jwt cluster configuration #18004

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
255 changes: 255 additions & 0 deletions website/content/docs/connect/config-entries/jwt-provider.mdx
View file
Open in desktop
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 = {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there supposed to be two TLSCertificates blocks?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, just following what we already have in the docs. This seems to be the pattern the doc team is following now

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention is to communicate that you can either define a trusted CA configuration or a CA cert provider instance within the TLSCertificates block but not both. @boruszak - what do you think? Maybe we should list one parent block that contains both child configuration options and in a comment say something like "Either define the TrustedCA or CaCertificateProviderInstance"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kisunji @roncodingenthusiast If you can only set one of the children, we wanted to avoid placing both of them in a single block, because it's something the user wouldn't see in the real world. This was a decision to we made to avoid confusing users.

Again - we're open to suggestions, feedback, etc., so please don't hesitate to suggest alternatives that make more sense to you!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think something we might want to consider is putting them in the same block and commenting out the second option. Not sure how that could look though

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this "here's the complete configuration" section a little strange since it's re-iterating our actual documentation in an unrealistically verbose config entry. It's intimidating to see such a large code block.

I recall other parts in our docs having specific examples of common use-cases like "file-defined CA example" "external provider example". I consider those opinionated snippets more valuable than "this is everything that can be possibly be done".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kisunji I want you to know that I head your feedback - we won't change the complete configuration on this page at this time, but @trujillo-adam and I will confer.

Some other context I wanted to add - this page does have an example section at the bottom with a specific configuration example. The "complete configuration" is meant to address a different issue that we've had in our docs. Historically, our configuration entry reference pages have leaned a little heavily on the example section to demonstrate configurations, and as a result many pages have had a number of parameters that aren't used in any examples. That makes it especially unclear how certain configurations should be formatted and what kind of values they take. So the complete configuration is more of a way to demonstrate formatting across the entire config entry as an authoritative reference point.

Thank you so much for this feedback on the complete configuration too - I greatly appreciate it!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the context! It's definitely non-trivial work to balance exhaustive documentation with simple examples. Really appreciate the feedback process in these PRs 🙏

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:
roncodingenthusiast marked this conversation as resolved.
Show resolved Hide resolved

- [`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

roncodingenthusiast marked this conversation as resolved.
Show resolved Hide resolved
- Default: None
- Data type: Map containing one of the following parameters:

| Parameter | Description | Data type | Default value |
roncodingenthusiast marked this conversation as resolved.
Show resolved Hide resolved
| :-------- | :------------------------------------------------- | :-------- | :------------ |
| `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`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of the corresponding comments in the HCL tab apply here, too.


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