From 597926c1bff296b2a8e77f681e3a17b54885be66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A4rt=20Bakhoff?= Date: Thu, 24 Jul 2025 05:29:39 +0300 Subject: [PATCH 1/3] Document more openid settings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The setting descriptions are copied from jwt.md as openid is also jwt-based. required_audience and required_issuer were added in https://github.com/opensearch-project/security/commit/4b386719db87b7d7bdc35191d7706f4a3944b2c9 Rationale explained in https://github.com/opensearch-project/security/issues/2766 Signed-off-by: Märt Bakhoff --- _security/authentication-backends/openid-connect.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_security/authentication-backends/openid-connect.md b/_security/authentication-backends/openid-connect.md index f1194cde09d..640d470b852 100755 --- a/_security/authentication-backends/openid-connect.md +++ b/_security/authentication-backends/openid-connect.md @@ -51,6 +51,7 @@ config: subject_key: preferred_username roles_key: roles openid_connect_url: https://keycloak.example.com:8080/auth/realms/master/.well-known/openid-configuration + required_audience: your-openid-client-id authentication_backend: type: noop ``` @@ -64,6 +65,9 @@ Name | Description `jwt_url_parameter` | If the token is not transmitted in the HTTP header, but as an URL parameter, define the name of the parameter here. Optional. `subject_key` | The key in the JSON payload that stores the user's name. If not defined, the [subject](https://tools.ietf.org/html/rfc7519#section-4.1.2) registered claim is used. Most IdP providers use the `preferred_username` claim. Optional. `roles_key` | The key in the JSON payload that stores the user's roles. The value must be a comma-separated list of roles. This key is required only if you want to use roles in the JWT. You can configure `roles_key` as a list to extract roles from nested JWT claims. +`required_audience` | The name of the audience that the JWT must specify. You can set a single value (for example, `project1`) or multiple comma-separated values (for example, `project1,admin`). If you set multiple values, the JWT must have at least one required audience. This parameter corresponds to the [`aud` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). +`required_issuer` | The target issuer of JWT stored in the JSON payload. This corresponds to the [`iss` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1). +`jwt_clock_skew_tolerance_seconds` | Sets a window of time, in seconds, to compensate for any disparity between the JWT authentication server and OpenSearch node clock times, thereby preventing authentication failures due to the misalignment. Security sets 30 seconds as the default. Use this setting to apply a custom value. ## OpenID Connect URL From 923756e4f0b4d87540c9e1ece9ca122bf63ca083 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A4rt?= Date: Wed, 30 Jul 2025 18:17:08 +0300 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Märt --- _security/authentication-backends/openid-connect.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_security/authentication-backends/openid-connect.md b/_security/authentication-backends/openid-connect.md index 640d470b852..127050e5261 100755 --- a/_security/authentication-backends/openid-connect.md +++ b/_security/authentication-backends/openid-connect.md @@ -65,9 +65,9 @@ Name | Description `jwt_url_parameter` | If the token is not transmitted in the HTTP header, but as an URL parameter, define the name of the parameter here. Optional. `subject_key` | The key in the JSON payload that stores the user's name. If not defined, the [subject](https://tools.ietf.org/html/rfc7519#section-4.1.2) registered claim is used. Most IdP providers use the `preferred_username` claim. Optional. `roles_key` | The key in the JSON payload that stores the user's roles. The value must be a comma-separated list of roles. This key is required only if you want to use roles in the JWT. You can configure `roles_key` as a list to extract roles from nested JWT claims. -`required_audience` | The name of the audience that the JWT must specify. You can set a single value (for example, `project1`) or multiple comma-separated values (for example, `project1,admin`). If you set multiple values, the JWT must have at least one required audience. This parameter corresponds to the [`aud` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). +`required_audience` | The name of the audience that the JWT must specify. You can specify a single value (for example, `project1`) or multiple comma-separated values (for example, `project1,admin`). If you specify multiple values, the JWT must have at least one required audience. This parameter corresponds to the [`aud` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). `required_issuer` | The target issuer of JWT stored in the JSON payload. This corresponds to the [`iss` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1). -`jwt_clock_skew_tolerance_seconds` | Sets a window of time, in seconds, to compensate for any disparity between the JWT authentication server and OpenSearch node clock times, thereby preventing authentication failures due to the misalignment. Security sets 30 seconds as the default. Use this setting to apply a custom value. +`jwt_clock_skew_tolerance_seconds` | Specifies a window of time, in seconds, to compensate for any disparity between the JWT authentication server and OpenSearch node clock times, thereby preventing authentication failures due to the misalignment. The Security plugin sets 30 seconds as the default. Use this setting to apply a custom value. ## OpenID Connect URL From 5b7bebe136c4851e90115754f3763f3c05252934 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Wed, 30 Jul 2025 11:45:50 -0400 Subject: [PATCH 3/3] Update _security/authentication-backends/openid-connect.md Signed-off-by: Nathan Bower --- _security/authentication-backends/openid-connect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/authentication-backends/openid-connect.md b/_security/authentication-backends/openid-connect.md index 127050e5261..dceb75ce182 100755 --- a/_security/authentication-backends/openid-connect.md +++ b/_security/authentication-backends/openid-connect.md @@ -66,7 +66,7 @@ Name | Description `subject_key` | The key in the JSON payload that stores the user's name. If not defined, the [subject](https://tools.ietf.org/html/rfc7519#section-4.1.2) registered claim is used. Most IdP providers use the `preferred_username` claim. Optional. `roles_key` | The key in the JSON payload that stores the user's roles. The value must be a comma-separated list of roles. This key is required only if you want to use roles in the JWT. You can configure `roles_key` as a list to extract roles from nested JWT claims. `required_audience` | The name of the audience that the JWT must specify. You can specify a single value (for example, `project1`) or multiple comma-separated values (for example, `project1,admin`). If you specify multiple values, the JWT must have at least one required audience. This parameter corresponds to the [`aud` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). -`required_issuer` | The target issuer of JWT stored in the JSON payload. This corresponds to the [`iss` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1). +`required_issuer` | The target issuer of the JWT stored in the JSON payload. This corresponds to the [`iss` claim of the JWT](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1). `jwt_clock_skew_tolerance_seconds` | Specifies a window of time, in seconds, to compensate for any disparity between the JWT authentication server and OpenSearch node clock times, thereby preventing authentication failures due to the misalignment. The Security plugin sets 30 seconds as the default. Use this setting to apply a custom value.