docs: JWT Authorization for intentions (#17643)
* Initial page/nav creation * configuration entry reference page * Usage + fixes * service intentions page * usage * description * config entry updates * formatting fixes * Update website/content/docs/connect/config-entries/service-intentions.mdx Co-authored-by: Paul Glass <pglass@hashicorp.com> * service intentions review fixes * Overview page review fixes * Apply suggestions from code review Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --------- Co-authored-by: Paul Glass <pglass@hashicorp.com> Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
Jeff Boruszak
boruszak
parent
83a9fb8e9e
commit
9a509dba00
|
|
@ -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
|
||||
|
|
@ -102,53 +108,53 @@ Kind = "jwt-provider" # required
|
|||
Name = "<name-of-provider-configuration-entry>" # required
|
||||
Issuer = "<jwt-issuer>" # required
|
||||
JSONWebKeySet = { # required
|
||||
Local = { # cannot specify with JWKS{}.Remote
|
||||
JWKS = "<JWKS-as-base64-string>" # cannot specify with JWKS{}.Local{}.Filename
|
||||
Filename = "<path/to/JWKS/file>" # cannot specify with JWKS{}.Local{}.String
|
||||
}
|
||||
Local = { # cannot specify with JWKS{}.Remote
|
||||
JWKS = "<JWKS-as-base64-string>" # cannot specify with JWKS{}.Local{}.Filename
|
||||
Filename = "<path/to/JWKS/file>" # cannot specify with JWKS{}.Local{}.String
|
||||
}
|
||||
}
|
||||
JSONWebKeySet = {
|
||||
Remote = { # cannot specify with JWKS{}.Local
|
||||
URI = "<uniform-resource-identifier>"
|
||||
RequestTimeoutMs = 1500
|
||||
CacheDuration = "5m"
|
||||
FetchAsynchronously = false
|
||||
RetryPolicy = {
|
||||
NumRetries = 0
|
||||
RetryPolicyBackoff = {
|
||||
BaseInterval = "1s"
|
||||
MaxInterval = "10s"
|
||||
Remote = { # cannot specify with JWKS{}.Local
|
||||
URI = "<uniform-resource-identifier>"
|
||||
RequestTimeoutMs = 1500
|
||||
CacheDuration = "5m"
|
||||
FetchAsynchronously = false
|
||||
RetryPolicy = {
|
||||
NumRetries = 0
|
||||
RetryPolicyBackoff = {
|
||||
BaseInterval = "1s"
|
||||
MaxInterval = "10s"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Audiences = ["<aud-claims>"]
|
||||
Locations = [
|
||||
{
|
||||
Header = {
|
||||
Name = "<name-of-header-with-token>"
|
||||
ValuePrefix = "<prefix-in-header-before-token>"
|
||||
Forward = false
|
||||
{
|
||||
Header = {
|
||||
Name = "<name-of-header-with-token>"
|
||||
ValuePrefix = "<prefix-in-header-before-token>"
|
||||
Forward = false
|
||||
}
|
||||
},
|
||||
{
|
||||
QueryParam = {
|
||||
Name = "<name-of-query-parameter-with-token>"
|
||||
}
|
||||
},
|
||||
{
|
||||
Cookie = {
|
||||
Name = "<name-of-cookie-with-token>"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
QueryParam = {
|
||||
Name = "<name-of-query-parameter-with-token>"
|
||||
}
|
||||
},
|
||||
{
|
||||
Cookie = {
|
||||
Name = "<name-of-cookie-with-token>"
|
||||
}
|
||||
}
|
||||
]
|
||||
Forwarding = {
|
||||
HeaderName = "<name-appended-to-forwarding-header>"
|
||||
PadForwardPayloadHeader = false
|
||||
HeaderName = "<name-appended-to-forwarding-header>"
|
||||
PadForwardPayloadHeader = false
|
||||
}
|
||||
ClockSkewSeconds = 30
|
||||
CacheConfig = {
|
||||
Size = 0
|
||||
Size = 0
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -158,58 +164,58 @@ CacheConfig = {
|
|||
|
||||
```json
|
||||
{
|
||||
"Kind": "jwt-provider", // required
|
||||
"Name": "<name-of-provider-configuration-entry>", // required
|
||||
"Issuer": "<jwt-issuer>", // required
|
||||
"JSONWebKeySet": { // required
|
||||
"Local": { // cannot specify with JWKS.Remote
|
||||
"JWKS": "<JWKS-as-base64-string>", // cannot specify with JWKS.Local.Filename
|
||||
"Filename": "<path/to/JWKS/file>" // cannot specify with JWKS.Local.String
|
||||
"Kind": "jwt-provider", // required
|
||||
"Name": "<name-of-provider-configuration-entry>", // required
|
||||
"Issuer": "<jwt-issuer>", // required
|
||||
"JSONWebKeySet": { // required
|
||||
"Local": { // cannot specify with JWKS.Remote
|
||||
"JWKS": "<JWKS-as-base64-string>", // cannot specify with JWKS.Local.Filename
|
||||
"Filename": "<path/to/JWKS/file>" // cannot specify with JWKS.Local.String
|
||||
}
|
||||
},
|
||||
"JSONWebKeySet": {
|
||||
"Remote": { // cannot specify with JWKS.Local
|
||||
"URI": "<uniform-resource-identifier>",
|
||||
"RequestTimeoutMs": "1500",
|
||||
"CacheDuration": "5m",
|
||||
"FetchAsynchronously": "false",
|
||||
"RetryPolicy": {
|
||||
"NumRetries": "0",
|
||||
"RetryPolicyBackOff": {
|
||||
"BaseInterval": "1s",
|
||||
"MaxInterval": "10s"
|
||||
},
|
||||
"JSONWebKeySet": {
|
||||
"Remote": { // cannot specify with JWKS.Local
|
||||
"URI": "<uniform-resource-identifier>",
|
||||
"RequestTimeoutMs": "1500",
|
||||
"CacheDuration": "5m",
|
||||
"FetchAsynchronously": "false",
|
||||
"RetryPolicy": {
|
||||
"NumRetries": "0",
|
||||
"RetryPolicyBackOff": {
|
||||
"BaseInterval": "1s",
|
||||
"MaxInterval": "10s"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"Audiences": ["<aud-claims>"],
|
||||
"Locations": [
|
||||
},
|
||||
"Audiences": ["<aud-claims>"],
|
||||
"Locations": [
|
||||
{
|
||||
"Header": {
|
||||
"Name": "<name-of-header-with-token>",
|
||||
"ValuePrefix": "<prefix-in-header-before-token>",
|
||||
"Forward": "false"
|
||||
}
|
||||
"Header": {
|
||||
"Name": "<name-of-header-with-token>",
|
||||
"ValuePrefix": "<prefix-in-header-before-token>",
|
||||
"Forward": "false"
|
||||
}
|
||||
},
|
||||
{
|
||||
"QueryParam": {
|
||||
"Name":"<name-of-query-parameter-with-token>",
|
||||
}
|
||||
"QueryParam": {
|
||||
"Name":"<name-of-query-parameter-with-token>",
|
||||
}
|
||||
},
|
||||
{
|
||||
"Cookie": {
|
||||
"Name": "<name-of-cookie-with-token>"
|
||||
}
|
||||
"Cookie": {
|
||||
"Name": "<name-of-cookie-with-token>"
|
||||
}
|
||||
}
|
||||
],
|
||||
"Forwarding": {
|
||||
"HeaderName": "<name-appended-to-forwarding-header>",
|
||||
"PadForwardPayloadHeader": "false"
|
||||
},
|
||||
"ClockSkewSeconds": "30",
|
||||
"CacheConfig": {
|
||||
],
|
||||
"Forwarding": {
|
||||
"HeaderName": "<name-appended-to-forwarding-header>",
|
||||
"PadForwardPayloadHeader": "false"
|
||||
},
|
||||
"ClockSkewSeconds": "30",
|
||||
"CacheConfig": {
|
||||
"Size": "0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -237,6 +243,9 @@ spec: # required
|
|||
fetchAsynchronously: false
|
||||
retryPolicy:
|
||||
numRetries: 0
|
||||
retryPolicyBackoff:
|
||||
baseInterval: 1s
|
||||
maxInterval: 10s
|
||||
audiences: [<aud-claims>]
|
||||
locations:
|
||||
header:
|
||||
|
|
@ -295,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.
|
||||
|
||||
|
|
@ -346,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.
|
||||
|
||||
|
|
@ -361,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).
|
||||
|
||||
|
|
@ -370,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.
|
||||
|
||||
|
|
@ -381,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.
|
||||
|
||||
|
|
@ -392,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:
|
||||
|
||||
| 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`](#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
|
||||
|
||||
### `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`
|
||||
|
||||
|
|
@ -458,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 <token>`. 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 <token>`. The prefix is not part of the token.
|
||||
|
||||
#### Values
|
||||
|
||||
|
|
@ -467,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
|
||||
|
||||
|
|
@ -584,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.
|
||||
|
||||
|
|
@ -631,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.
|
||||
|
||||
|
|
@ -652,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.
|
||||
|
||||
|
|
@ -682,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.
|
||||
|
||||
|
|
@ -697,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).
|
||||
|
||||
|
|
@ -706,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.
|
||||
|
||||
|
|
@ -717,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.
|
||||
|
||||
|
|
@ -728,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.
|
||||
|
||||
|
|
@ -737,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`
|
||||
|
||||
|
|
@ -794,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 <token>`. 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 <token>`. The prefix is not part of the token.
|
||||
|
||||
#### Values
|
||||
|
||||
|
|
@ -803,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
|
||||
|
||||
|
|
@ -917,9 +970,9 @@ Name = "okta"
|
|||
|
||||
Issuer = "okta"
|
||||
|
||||
JWKS = {
|
||||
JSONWebKeySet = {
|
||||
Remote = {
|
||||
URI = "https://dev-850216.okta.com/oauth2/default/v1/keys"
|
||||
URI = "https://<org>.okta.com/oauth2/default/v1/keys"
|
||||
CacheDuration = "30m"
|
||||
}
|
||||
}
|
||||
|
|
@ -938,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://<org>.okta.com/oauth2/default/v1/keys",
|
||||
"CacheDuration": "30m"
|
||||
}
|
||||
},
|
||||
|
|
@ -961,9 +1014,9 @@ metadata:
|
|||
name: okta
|
||||
spec:
|
||||
issuer: okta
|
||||
jsonWebKeySet:
|
||||
jsonwebkeyset:
|
||||
remote:
|
||||
uri: https://dev-850216.okta.com/oauth2/default/v1/keys
|
||||
uri: https://<org>.okta.com/oauth2/default/v1/keys
|
||||
cacheDuration: 30m
|
||||
forwarding:
|
||||
headerName: user-token
|
||||
|
|
|
|||
|
|
@ -21,7 +21,13 @@ The following outline shows how to format the service intentions configuration e
|
|||
- [`Name`](#name): string | required
|
||||
- [`Namespace`](#namespace): string | `default` | <EnterpriseAlert inline/>
|
||||
- [`Partition`](#partition): string | `default` | <EnterpriseAlert inline />
|
||||
- [`Meta`](#meta): map | no default
|
||||
- [`Meta`](#meta): map
|
||||
- [`JWT`](#jwt): map
|
||||
- [`Providers`](#jwt-providers): list of maps
|
||||
- [`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
|
||||
- [`Sources`](#sources): list | no default
|
||||
- [`Name`](#sources-name): string | no default
|
||||
- [`Peer`](#sources-peer): string | no default
|
||||
|
|
@ -32,28 +38,28 @@ The following outline shows how to format the service intentions configuration e
|
|||
- [`Permissions`](#sources-permissions): list | no default
|
||||
- [`Action`](#sources-permissions-action): string | no default | 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
|
||||
- [`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
|
||||
|
||||
</Tab>
|
||||
<Tab heading="YAML" group="yaml">
|
||||
<Tab heading= "YAML" group="yaml">
|
||||
|
||||
- [`apiVersion`](#apiversion): string | must be set to `consul.hashicorp.com/v1alpha1`
|
||||
- [`kind`](#kind): string | must be set to `ServiceIntentions`
|
||||
|
|
@ -64,6 +70,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` | <EnterpriseAlert inline/>
|
||||
- [`jwt`](#spec-jwt): map
|
||||
- [`providers`](#spec-jwt-providers): list of maps
|
||||
- [`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
|
||||
- [`sources`](#spec-sources): list | no default
|
||||
- [`name`](#spec-sources-name): string | no default
|
||||
- [`peer`](#spec-sources-peer): string | no default
|
||||
|
|
@ -109,6 +121,19 @@ Meta = {
|
|||
"<key-1>" = "<value-1>"
|
||||
"<key-2>" = "<value-2>"
|
||||
}
|
||||
JWT = {
|
||||
Providers = [
|
||||
{
|
||||
Name = "<JWT-provider-name>"
|
||||
VerifyClaims = [
|
||||
{
|
||||
Path = ["<claim>"]
|
||||
Value = "<api.apps.organization.com>"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Sources = [
|
||||
{
|
||||
Name = "<name of service sending traffic>" # string
|
||||
|
|
@ -179,6 +204,12 @@ spec:
|
|||
destination:
|
||||
name: <name of destination service>
|
||||
namespace: <destination namespace>
|
||||
jwt:
|
||||
providers:
|
||||
name: <JWT-provider-name>
|
||||
verifyClaims:
|
||||
path: [<aud>]
|
||||
value: <api.apps.organization.com>
|
||||
sources:
|
||||
name: <name of service sending traffic>
|
||||
peer: <name of cluster containing source service>
|
||||
|
|
@ -224,6 +255,19 @@ spec:
|
|||
"key-1":"<value-1>",
|
||||
"key-2":"<value-2>"
|
||||
},
|
||||
"JWT": {
|
||||
"Providers": [
|
||||
{
|
||||
"Name": "<JWT-provider-name>",
|
||||
"VerifyClaims": [
|
||||
{
|
||||
"Path": ["<aud>"],
|
||||
"Value": "<api.apps.organization.com>"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"Sources":[
|
||||
{
|
||||
"Name":"<name of service sending traffic>",
|
||||
|
|
@ -346,6 +390,63 @@ 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 validate a JSON web token.
|
||||
|
||||
#### Values
|
||||
|
||||
- Default: None
|
||||
- Data type: List of maps
|
||||
|
||||
### `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.
|
||||
|
||||
#### 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
|
||||
|
||||
### `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.
|
||||
|
|
@ -514,7 +615,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.
|
||||
|
|
@ -608,23 +708,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`
|
||||
|
||||
|
|
@ -637,17 +738,63 @@ You can also specify a wildcard character (`*`) to match all services that are m
|
|||
- This field is required.
|
||||
- Data type: String
|
||||
|
||||
### `spec.metadata.namespace` <EnterpriseAlert inline />
|
||||
### `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).
|
||||
|
||||
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.
|
||||
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: 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: 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 validate a JSON web token.
|
||||
|
||||
#### Values
|
||||
|
||||
- Default: None
|
||||
- Data type: List of maps
|
||||
|
||||
### `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.
|
||||
|
||||
#### 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
|
||||
|
||||
### `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.
|
||||
|
|
@ -1359,64 +1506,64 @@ Sources = [
|
|||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: consul.hashicorp.com/v1alpha1
|
||||
kind: ServiceIntentions
|
||||
metadata:
|
||||
name: backend
|
||||
spec:
|
||||
sources:
|
||||
name: frontend
|
||||
permissions:
|
||||
apiVersion: consul.hashicorp.com/v1alpha1
|
||||
kind: ServiceIntentions
|
||||
metadata:
|
||||
name: backend
|
||||
spec:
|
||||
sources:
|
||||
name: frontend
|
||||
permissions:
|
||||
http:
|
||||
pathExact: /admin
|
||||
jwt:
|
||||
providers:
|
||||
name: okta
|
||||
verifyClaims:
|
||||
path:
|
||||
- perms
|
||||
- role
|
||||
value: admin
|
||||
action: allow
|
||||
http:
|
||||
pathExact: /admin
|
||||
jwt:
|
||||
providers:
|
||||
name: okta
|
||||
verifyClaims:
|
||||
path:
|
||||
- perms
|
||||
- role
|
||||
value: admin
|
||||
action: allow
|
||||
http:
|
||||
pathPrefix: /
|
||||
pathPrefix: /
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"Kind": "service-intentions",
|
||||
"Name": "backend",
|
||||
"Sources": [
|
||||
{
|
||||
"Name": "frontend",
|
||||
"Permissions": [
|
||||
{
|
||||
"HTTP": {
|
||||
"PathExact": "/admin"
|
||||
},
|
||||
"JWT": {
|
||||
"Providers": [
|
||||
{
|
||||
"Name": "okta",
|
||||
"VerifyClaims": [
|
||||
{
|
||||
"Path": ["perms", "role"],
|
||||
"Value": "admin"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
"Kind": "service-intentions",
|
||||
"Name": "backend",
|
||||
"Sources": [
|
||||
{
|
||||
"Name": "frontend",
|
||||
"Permissions": [
|
||||
{
|
||||
"HTTP": {
|
||||
"PathExact": "/admin"
|
||||
},
|
||||
{
|
||||
"Action": "allow",
|
||||
"HTTP": {
|
||||
"PathPrefix": "/"
|
||||
}
|
||||
"JWT": {
|
||||
"Providers": [
|
||||
{
|
||||
"Name": "okta",
|
||||
"VerifyClaims": [
|
||||
{
|
||||
"Path": ["perms", "role"],
|
||||
"Value": "admin"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"Action": "allow",
|
||||
"HTTP": {
|
||||
"PathPrefix": "/"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -14,15 +14,15 @@ 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`.
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -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://<org>.okta.com/oauth2/default/v1/keys"
|
||||
CacheDuration = "30m"
|
||||
}
|
||||
}
|
||||
|
|
@ -73,8 +73,29 @@ 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
|
||||
|
||||
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 = [
|
||||
{
|
||||
Name = "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-intention.hcl
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue