From 138bf07e5f476ecf5ced0f2e4447b0a1daf96ef1 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Tue, 28 Oct 2025 12:49:47 -0700 Subject: [PATCH 1/7] Add details to JWT authentication document about JSON Web Key Set (JWKS) background reloading feature. --- .../cluster-or-deployment-auth/jwt.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index b6a4ebcf6a..43c731bfc2 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -121,7 +121,19 @@ Client authentication is enabled by default for the JWT realms. Disabling client : Indicates that {{es}} should use the `RS256` or `HS256` signature algorithms to verify the signature of the JWT from the JWT issuer. `pkc_jwkset_path` - : The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. + : The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. Background JWKS reloading can also be configured with the setting `pkc_jwkset_reload.enabled`. + + `pkc_jwkset_reload.enabled` + : Indicates whether JWKS background reloading is enabled (`false`). + + `pkc_jwkset_reload.file_interval` + : Specifies the reload interval for file-based JWKS (`5m`). + + `pkc_jwkset_reload.url_interval_min` + : Specifies the minimum reload interval for URL-based JWKS. The `Expires` and `Cache-Control` HTTP response headers inform the reload interval. This configuration setting is the lower bound of what is considered, and it is also the default interval in the absence of useful response headers (`1h`). + + `pkc_jwkset_reload.url_interval_max` + : Specifies the maximum reload interval for URL-based JWKS. This configuration setting is the upper bound of what is considered from header responses (`5d`). `claims.principal` : The name of the JWT claim that contains the user’s principal (username). @@ -434,6 +446,8 @@ PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS JWT realms load a PKC JWKS and an HMAC JWKS or HMAC UTF-8 JWK at startup. JWT realms can also reload PKC JWKS contents at runtime; a reload is triggered by signature validation failures. +JWT realms can also be configured to reload a PKC JWKS periodically in the background. + ::::{note} HMAC JWKS or HMAC UTF-8 JWK reloading is not supported at this time. :::: From 5dacb0dbb37ff8c2051cd8d970cf2c2e34d21e39 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 29 Oct 2025 10:37:53 -0700 Subject: [PATCH 2/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index 43c731bfc2..1f01dd5965 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -124,7 +124,7 @@ Client authentication is enabled by default for the JWT realms. Disabling client : The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. Background JWKS reloading can also be configured with the setting `pkc_jwkset_reload.enabled`. `pkc_jwkset_reload.enabled` - : Indicates whether JWKS background reloading is enabled (`false`). + : Indicates whether JWKS background reloading is enabled. Defaults to `false`. `pkc_jwkset_reload.file_interval` : Specifies the reload interval for file-based JWKS (`5m`). From 0aa54bbc01156d4d95c65c0f504d8552b49e1a76 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 29 Oct 2025 10:38:03 -0700 Subject: [PATCH 3/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index 1f01dd5965..ef35488fb8 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -127,7 +127,7 @@ Client authentication is enabled by default for the JWT realms. Disabling client : Indicates whether JWKS background reloading is enabled. Defaults to `false`. `pkc_jwkset_reload.file_interval` - : Specifies the reload interval for file-based JWKS (`5m`). + : Specifies the reload interval for file-based JWKS. Defaults to `5m`. `pkc_jwkset_reload.url_interval_min` : Specifies the minimum reload interval for URL-based JWKS. The `Expires` and `Cache-Control` HTTP response headers inform the reload interval. This configuration setting is the lower bound of what is considered, and it is also the default interval in the absence of useful response headers (`1h`). From 2b98c326e146f5503d7f715aba2ac1c0d604a81b Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 29 Oct 2025 10:38:16 -0700 Subject: [PATCH 4/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index ef35488fb8..eb6be1ca61 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -130,7 +130,7 @@ Client authentication is enabled by default for the JWT realms. Disabling client : Specifies the reload interval for file-based JWKS. Defaults to `5m`. `pkc_jwkset_reload.url_interval_min` - : Specifies the minimum reload interval for URL-based JWKS. The `Expires` and `Cache-Control` HTTP response headers inform the reload interval. This configuration setting is the lower bound of what is considered, and it is also the default interval in the absence of useful response headers (`1h`). + : Specifies the minimum reload interval for URL-based JWKS. The `Expires` and `Cache-Control` HTTP response headers inform the reload interval. This configuration setting is the lower bound of what is considered, and it is also the default interval in the absence of useful response headers. Defaults to `1h`. `pkc_jwkset_reload.url_interval_max` : Specifies the maximum reload interval for URL-based JWKS. This configuration setting is the upper bound of what is considered from header responses (`5d`). From 4b0f7ed6c7460bca703d02e702c2a3c15a0a9261 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 29 Oct 2025 10:38:50 -0700 Subject: [PATCH 5/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index eb6be1ca61..c3a80732d9 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -136,7 +136,7 @@ Client authentication is enabled by default for the JWT realms. Disabling client : Specifies the maximum reload interval for URL-based JWKS. This configuration setting is the upper bound of what is considered from header responses (`5d`). `claims.principal` - : The name of the JWT claim that contains the user’s principal (username). + : The name of the JWT claim that contains the user’s principal. Defaults to `username`. :::: From e4d0e95e9adee0cc6116a9bf49391142e5f07454 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 29 Oct 2025 10:42:24 -0700 Subject: [PATCH 6/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index c3a80732d9..986df3e6d1 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -123,7 +123,7 @@ Client authentication is enabled by default for the JWT realms. Disabling client `pkc_jwkset_path` : The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. Background JWKS reloading can also be configured with the setting `pkc_jwkset_reload.enabled`. - `pkc_jwkset_reload.enabled` + `pkc_jwkset_reload.enabled` {applies_to}`stack: ga 9.3` : Indicates whether JWKS background reloading is enabled. Defaults to `false`. `pkc_jwkset_reload.file_interval` From 8831a42aa5a6094d0986d3b4c0fd8cedf5959eaf Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 29 Oct 2025 10:51:13 -0700 Subject: [PATCH 7/7] Expand content for JWKS reloading. --- .../users-roles/cluster-or-deployment-auth/jwt.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md index 986df3e6d1..f41d881714 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/jwt.md @@ -121,18 +121,18 @@ Client authentication is enabled by default for the JWT realms. Disabling client : Indicates that {{es}} should use the `RS256` or `HS256` signature algorithms to verify the signature of the JWT from the JWT issuer. `pkc_jwkset_path` - : The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. Background JWKS reloading can also be configured with the setting `pkc_jwkset_reload.enabled`. + : The file name or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. A value is considered a file name if it does not begin with `https`. The file name is resolved relative to the {{es}} configuration directory. If a URL is provided, then it must begin with `https://` (`http://` is not supported). {{es}} automatically caches the JWK set and will attempt to refresh the JWK set upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys. Background JWKS reloading can also be configured with the setting `pkc_jwkset_reload.enabled`. This ensures that rotated keys are automatically discovered and used to verify JWT signatures. `pkc_jwkset_reload.enabled` {applies_to}`stack: ga 9.3` : Indicates whether JWKS background reloading is enabled. Defaults to `false`. - `pkc_jwkset_reload.file_interval` + `pkc_jwkset_reload.file_interval` {applies_to}`stack: ga 9.3` : Specifies the reload interval for file-based JWKS. Defaults to `5m`. - `pkc_jwkset_reload.url_interval_min` + `pkc_jwkset_reload.url_interval_min` {applies_to}`stack: ga 9.3` : Specifies the minimum reload interval for URL-based JWKS. The `Expires` and `Cache-Control` HTTP response headers inform the reload interval. This configuration setting is the lower bound of what is considered, and it is also the default interval in the absence of useful response headers. Defaults to `1h`. - `pkc_jwkset_reload.url_interval_max` + `pkc_jwkset_reload.url_interval_max` {applies_to}`stack: ga 9.3` : Specifies the maximum reload interval for URL-based JWKS. This configuration setting is the upper bound of what is considered from header responses (`5d`). `claims.principal`