From a58b7efc031caddbbaf038934c98c502adf3cead Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Wed, 17 Sep 2025 17:33:04 +0200 Subject: [PATCH 1/6] jwt auth for os --- .../opensearch/howto/jwt-authentication.md | 85 +++++++++++++++++++ .../opensearch/howto/oidc-authentication.md | 2 +- .../howto/saml-sso-authentication.md | 2 +- sidebars.ts | 1 + 4 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 docs/products/opensearch/howto/jwt-authentication.md diff --git a/docs/products/opensearch/howto/jwt-authentication.md b/docs/products/opensearch/howto/jwt-authentication.md new file mode 100644 index 000000000..72cd4f68d --- /dev/null +++ b/docs/products/opensearch/howto/jwt-authentication.md @@ -0,0 +1,85 @@ +--- +title: Enable JSON Web Token authentication on Aiven for OpenSearch® +sidebar_label: JWT authentication +--- + +import RelatedPages from "@site/src/components/RelatedPages"; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Prerequisites + +- Aiven for OpenSearch® version 2.4 or later. Upgrade if needed. +- OpenSearch Security management + [enabled](/docs/products/opensearch/howto/enable-opensearch-security) + on your service + +## Enable JWT authentication + + + + +1. In the [Aiven Console](https://console.aiven.io/), access your Aiven + for OpenSearch service where to enable OpenID Connect. +1. Click **Users** on the sidebar. +1. In the **SSO authentication** section, use the **Add method** + drop-down and click **OpenID**. +1. On **Configure OpenID Connect authentication** screen, + - **Redirect URL**: This URL is auto-populated. It is the URL that + users will be redirected to after they have successfully + authenticated through the IdP. + - **IdP URL**: Enter the URL of your OpenID Connect Identity + Provider. This is the URL that Aiven will use to redirect users + to your IdP for authentication. + - **Client ID**: Enter the ID you obtained during your IdP + registration. This ID is used to authenticate your Aiven + application with your IdP. + - **Client Secret**: Enter the secret associated with the Client + ID. This secret is used to encrypt communications between your + Aiven application and your IdP. + - **Scope**: The scope of the claims. This is the set of + permissions that you are requesting from your IdP. For example, + you can request the `openid`, `profile`, and `email` scopes to + get the user's identity, profile information, and email + address. + - **Roles key**: The key in the returned JSON that stores the + user's roles. This key is used by Aiven to determine the + user's permissions. + - **Subject key**: This refers to the specific key within the + returned JSON that holds the user's name or identifying + subject. Aiven uses this key to recognize and authenticate the + user. By default, this key is labeled as `Subject`. +1. Optional: **Enable advanced configuration** to fine-tune + the authentication process. Aiven for OpenSearch provides the + following advanced configuration options: + - **Token handling**: Choose your preferred method for handling + the authentication token. + - **HTTP Header**: The authentication token is passed in an + HTTP header. + - **Header name**: Enter the specific name of the HTTP + header that will contain the authentication token. The + default header name is Authorization. + - **URL parameter**: The authentication token is passed as a + URL parameter. You can specify the parameter name. + - **Parameter name**: Enter the specific URL parameter + that will carry the authentication token. + - **Refresh limit count**: Maximum number of unrecognized JWT key + IDs allowed within 10 seconds. Enter the value for the Refresh + Limit Count parameter. The default value is 10. + - **Refresh limit window (ms)**: This is the interval, measured in + milliseconds, during which the system will verify unrecognized + JWT key IDs. Enter the value for the Refresh Limit Window + parameter. The default value is 10,000 (10 seconds). +1. Click **Enable** to complete the setup and activate the + configuration. + + + + + + + + + + + diff --git a/docs/products/opensearch/howto/oidc-authentication.md b/docs/products/opensearch/howto/oidc-authentication.md index 5ad785743..d9df37cae 100644 --- a/docs/products/opensearch/howto/oidc-authentication.md +++ b/docs/products/opensearch/howto/oidc-authentication.md @@ -1,6 +1,6 @@ --- title: Enable OpenID Connect authentication on Aiven for OpenSearch® -sidebar_label: Enable OpenID Connect authentication +sidebar_label: OIDC authentication --- OpenID Connect (OIDC) is an authentication protocol that builds on top of the OAuth 2.0 protocol. diff --git a/docs/products/opensearch/howto/saml-sso-authentication.md b/docs/products/opensearch/howto/saml-sso-authentication.md index 7678ca7d1..19c738d46 100644 --- a/docs/products/opensearch/howto/saml-sso-authentication.md +++ b/docs/products/opensearch/howto/saml-sso-authentication.md @@ -1,6 +1,6 @@ --- title: Enable SAML authentication on Aiven for OpenSearch® -sidebar_label: Enable SAML authenttication +sidebar_label: SAML authentication --- SAML (Security Assertion Markup Language) is a standard protocol for exchanging authentication and authorization data between an identity provider (IdP) and a Service Provider (SP). diff --git a/sidebars.ts b/sidebars.ts index 999faeba6..34e8d9c9b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1753,6 +1753,7 @@ const sidebars: SidebarsConfig = { 'products/opensearch/howto/enable-opensearch-security', 'products/opensearch/howto/saml-sso-authentication', 'products/opensearch/howto/oidc-authentication', + 'products/opensearch/howto/jwt-authentication', 'products/opensearch/howto/audit-logs', 'products/opensearch/howto/opensearch-dashboard-multi_tenancy', ], From bb639d5ba7c653ce6de39dcf7e50c86b28a7a12e Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Fri, 19 Sep 2025 15:29:54 +0200 Subject: [PATCH 2/6] intro --- .../opensearch/howto/jwt-authentication.md | 157 ++++++++++++------ 1 file changed, 103 insertions(+), 54 deletions(-) diff --git a/docs/products/opensearch/howto/jwt-authentication.md b/docs/products/opensearch/howto/jwt-authentication.md index 72cd4f68d..ce14ad663 100644 --- a/docs/products/opensearch/howto/jwt-authentication.md +++ b/docs/products/opensearch/howto/jwt-authentication.md @@ -7,79 +7,128 @@ import RelatedPages from "@site/src/components/RelatedPages"; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +Configure JSON Web Token (JWT) authentication to enable secure, stateless authentication for Aiven for OpenSearch®. + +## How it works + +JWT authentication allows you to access Aiven for OpenSearch using tokens issued by +your existing identity provider, eliminating the need to manage separate OpenSearch +credentials or store session state on the server. + +When you make a request to your Aiven for OpenSearch service: + +1. **Token is validated**: Aiven for OpenSearch validates the JWT token using the signing + key you configure. +1. **User is identified**: Aiven for OpenSearch extracts the username from the token's + subject claim. +1. **Role is assignment**: If configured, user roles are extracted from the token or + managed separately in Aiven for OpenSearch. +1. **Access is granted**: Valid tokens provide seamless access to your Aiven for OpenSearch + service. + +JWT authentication in Aiven for OpenSearch uses the "Known Signing Keys" validation method, +where Aiven for OpenSearch uses a trusted public key to verify a digital signature from +your identity provider, ensuring that data is coming from a known and authentic source. +JWT authentication in Aiven for OpenSearch is configured through Aiven's user configuration +API rather than directly through the OpenSearch Security API. + +Supported `user_config` options are as follows: + +| Option | Data type | More information | +|---------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `jwt.enabled` | Boolean | Enables or disables JWT authentication. Set to `true` to activate JWT authentication. | +| `jwt.signing_key` | String | Base64-encoded signing key used to verify JWT tokens. Can be PEM-formatted RSA/EC public key or HMAC secret key. | +| `jwt.jwt_header` | String | HTTP header name containing the JWT token. Default is `Authorization`. | +| `jwt.jwt_url_parameter` | String | URL parameter name for passing JWT token as a query parameter. Optional alternative to header-based authentication. | +| `jwt.subject_key` | String | JWT claim key that contains the username/subject. Default is `sub`. | +| `jwt.roles_key` | String | JWT claim key that contains user roles. If not specified, roles must be managed separately in OpenSearch. | +| `jwt.required_audience` | String | Required audience (`aud`) claim value that must be present in JWT tokens. Optional but recommended for security. | +| `jwt.required_issuer` | String | Required issuer (`iss`) claim value that must be present in JWT tokens. Optional but recommended for security. | +| `jwt.jwt_clock_skew_tolerance_seconds`| Integer | Clock skew tolerance in seconds for JWT token validation. Accounts for time differences between systems. Default is typically 30 seconds. | + ## Prerequisites -- Aiven for OpenSearch® version 2.4 or later. Upgrade if needed. +- Aiven for OpenSearch® version 2.4 or later +- OpenSearch Dashboards version 2.19 or later - OpenSearch Security management [enabled](/docs/products/opensearch/howto/enable-opensearch-security) on your service +- Base64-encoded signing key (PEM-formatted RSA/EC public key or HMAC secret key) +- Tool for enabling and configuring the JWT authentication: + - [Aiven Console](https://console.aiven.io/) + - [Aiven CLI](/docs/tools/cli) + - [Aiven API](/docs/tools/api) ## Enable JWT authentication -1. In the [Aiven Console](https://console.aiven.io/), access your Aiven - for OpenSearch service where to enable OpenID Connect. -1. Click **Users** on the sidebar. -1. In the **SSO authentication** section, use the **Add method** - drop-down and click **OpenID**. -1. On **Configure OpenID Connect authentication** screen, - - **Redirect URL**: This URL is auto-populated. It is the URL that - users will be redirected to after they have successfully - authenticated through the IdP. - - **IdP URL**: Enter the URL of your OpenID Connect Identity - Provider. This is the URL that Aiven will use to redirect users - to your IdP for authentication. - - **Client ID**: Enter the ID you obtained during your IdP - registration. This ID is used to authenticate your Aiven - application with your IdP. - - **Client Secret**: Enter the secret associated with the Client - ID. This secret is used to encrypt communications between your - Aiven application and your IdP. - - **Scope**: The scope of the claims. This is the set of - permissions that you are requesting from your IdP. For example, - you can request the `openid`, `profile`, and `email` scopes to - get the user's identity, profile information, and email - address. - - **Roles key**: The key in the returned JSON that stores the - user's roles. This key is used by Aiven to determine the - user's permissions. - - **Subject key**: This refers to the specific key within the - returned JSON that holds the user's name or identifying - subject. Aiven uses this key to recognize and authenticate the - user. By default, this key is labeled as `Subject`. -1. Optional: **Enable advanced configuration** to fine-tune - the authentication process. Aiven for OpenSearch provides the - following advanced configuration options: - - **Token handling**: Choose your preferred method for handling - the authentication token. - - **HTTP Header**: The authentication token is passed in an - HTTP header. - - **Header name**: Enter the specific name of the HTTP - header that will contain the authentication token. The - default header name is Authorization. - - **URL parameter**: The authentication token is passed as a - URL parameter. You can specify the parameter name. - - **Parameter name**: Enter the specific URL parameter - that will carry the authentication token. - - **Refresh limit count**: Maximum number of unrecognized JWT key - IDs allowed within 10 seconds. Enter the value for the Refresh - Limit Count parameter. The default value is 10. - - **Refresh limit window (ms)**: This is the interval, measured in - milliseconds, during which the system will verify unrecognized - JWT key IDs. Enter the value for the Refresh Limit Window - parameter. The default value is 10,000 (10 seconds). -1. Click **Enable** to complete the setup and activate the - configuration. +1. In the [Aiven Console](https://console.aiven.io/), access your Aiven + for OpenSearch service where to enable the JWT authentication. +1. Click in the sidebar. +1. Scroll to the **Advanced configuration** section and click **Configure**. +1. In the **Advanced configuration** window: + 1. Click **Add configuration options**. + 1. Enter `jwt` in the search field to preview all JWT-related configuration options. + 1. Select the `jwt.signing_key` option and set it to your password. + 1. Select the `jwt.enabled` option and set it to `enabled`. + 1. Click **Save configuration**. +Run [avn service update](/docs/tools/cli/service-cli#avn-cli-service-update): + +```bash {2-4} +avn service update SERVICE_NAME \ + -c jwt.enabled=true \ + -c jwt.signing_key='SIGNING_KEY' \ + -c jwt.jwt_url_parameter=JWT_URL_PARAMETER +``` + +Replace the following placeholders with meaningful data: + +- `SERVICE_NAME` with the name of your Aiven for OpenSearch service, for example, `os2-jwt` +- `SIGNING_KEY` with your base64-encoded signing key (PEM-formatted RSA/EC public key or + HMAC secret key) +- `JWT_URL_PARAMETER` with the URL parameter name for JWT token, for example, `token` + +Call the [ServiceUpdate](https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate) +endpoint: + +```bash {7-11} +curl 'https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME' \ + -X 'PUT' \ + -H 'authorization: aivenv1 BEARER_TOKEN' \ + -H 'content-type: application/json' \ + --data-raw '{ + "user_config": { + "jwt": { + "enabled": true, + "signing_key": "SIGNING_KEY", + "jwt_clock_skew_tolerance_seconds": 45, + "jwt_url_parameter": "JWT_URL_PARAMETER" + } + } + }' +``` + +Replace the following placeholders with meaningful data: + +- `PROJECT_NAME` with your project name, for example, `my-project` +- `SERVICE_NAME` with your Aiven for OpenSearch service name, for example, `os2-jwt` +- `BEARER_TOKEN` with your Aiven API authentication token +- `SIGNING_KE`Y with your base64-encoded signing key (PEM-formatted RSA/EC public key or + HMAC secret key) +- `JWT_URL_PARAMETER` with the URL parameter name for JWT token, for example, `token` + + +[Upstream OpenSearch JWT authentication documentation](https://docs.opensearch.org/latest/security/authentication-backends/jwt/) From 01976f67032cbf547070a5501fb5b1c046c64d87 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Mon, 22 Sep 2025 17:02:46 +0200 Subject: [PATCH 3/6] fix --- docs/products/opensearch/howto/jwt-authentication.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/products/opensearch/howto/jwt-authentication.md b/docs/products/opensearch/howto/jwt-authentication.md index ce14ad663..f27536c25 100644 --- a/docs/products/opensearch/howto/jwt-authentication.md +++ b/docs/products/opensearch/howto/jwt-authentication.md @@ -4,6 +4,7 @@ sidebar_label: JWT authentication --- import RelatedPages from "@site/src/components/RelatedPages"; +import ConsoleLabel from "@site/src/components/ConsoleIcons"; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -26,7 +27,7 @@ When you make a request to your Aiven for OpenSearch service: 1. **Access is granted**: Valid tokens provide seamless access to your Aiven for OpenSearch service. -JWT authentication in Aiven for OpenSearch uses the "Known Signing Keys" validation method, +JWT authentication in Aiven for OpenSearch uses the known-signing-keys validation method, where Aiven for OpenSearch uses a trusted public key to verify a digital signature from your identity provider, ensuring that data is coming from a known and authentic source. JWT authentication in Aiven for OpenSearch is configured through Aiven's user configuration From db97c201e06ca3e6f592ac0a6f0bf2b09dde9399 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Thu, 25 Sep 2025 14:52:28 +0200 Subject: [PATCH 4/6] addressing comment on RSA/ECDSA --- docs/products/opensearch/howto/jwt-authentication.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/products/opensearch/howto/jwt-authentication.md b/docs/products/opensearch/howto/jwt-authentication.md index f27536c25..e41a93d94 100644 --- a/docs/products/opensearch/howto/jwt-authentication.md +++ b/docs/products/opensearch/howto/jwt-authentication.md @@ -38,7 +38,7 @@ Supported `user_config` options are as follows: | Option | Data type | More information | |---------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------| | `jwt.enabled` | Boolean | Enables or disables JWT authentication. Set to `true` to activate JWT authentication. | -| `jwt.signing_key` | String | Base64-encoded signing key used to verify JWT tokens. Can be PEM-formatted RSA/EC public key or HMAC secret key. | +| `jwt.signing_key` | String | Base64-encoded signing key used to verify JWT tokens. Can be PEM-formatted RSA/ECDSA public key or HMAC secret key. | | `jwt.jwt_header` | String | HTTP header name containing the JWT token. Default is `Authorization`. | | `jwt.jwt_url_parameter` | String | URL parameter name for passing JWT token as a query parameter. Optional alternative to header-based authentication. | | `jwt.subject_key` | String | JWT claim key that contains the username/subject. Default is `sub`. | @@ -54,7 +54,7 @@ Supported `user_config` options are as follows: - OpenSearch Security management [enabled](/docs/products/opensearch/howto/enable-opensearch-security) on your service -- Base64-encoded signing key (PEM-formatted RSA/EC public key or HMAC secret key) +- Base64-encoded signing key (PEM-formatted RSA/ECDSA public key or HMAC secret key) - Tool for enabling and configuring the JWT authentication: - [Aiven Console](https://console.aiven.io/) - [Aiven CLI](/docs/tools/cli) @@ -91,7 +91,7 @@ avn service update SERVICE_NAME \ Replace the following placeholders with meaningful data: - `SERVICE_NAME` with the name of your Aiven for OpenSearch service, for example, `os2-jwt` -- `SIGNING_KEY` with your base64-encoded signing key (PEM-formatted RSA/EC public key or +- `SIGNING_KEY` with your base64-encoded signing key (PEM-formatted RSA/ECDSA public key or HMAC secret key) - `JWT_URL_PARAMETER` with the URL parameter name for JWT token, for example, `token` @@ -123,7 +123,7 @@ Replace the following placeholders with meaningful data: - `PROJECT_NAME` with your project name, for example, `my-project` - `SERVICE_NAME` with your Aiven for OpenSearch service name, for example, `os2-jwt` - `BEARER_TOKEN` with your Aiven API authentication token -- `SIGNING_KE`Y with your base64-encoded signing key (PEM-formatted RSA/EC public key or +- `SIGNING_KE`Y with your base64-encoded signing key (PEM-formatted RSA/ECDSA public key or HMAC secret key) - `JWT_URL_PARAMETER` with the URL parameter name for JWT token, for example, `token` From 6c144da71fb0dc2bfc5d81976746800c9028dacb Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Thu, 25 Sep 2025 16:47:11 +0200 Subject: [PATCH 5/6] Bao's feedback --- .../opensearch/howto/jwt-authentication.md | 28 +++++++++++++------ 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/products/opensearch/howto/jwt-authentication.md b/docs/products/opensearch/howto/jwt-authentication.md index e41a93d94..c5d5db442 100644 --- a/docs/products/opensearch/howto/jwt-authentication.md +++ b/docs/products/opensearch/howto/jwt-authentication.md @@ -67,14 +67,26 @@ Supported `user_config` options are as follows: 1. In the [Aiven Console](https://console.aiven.io/), access your Aiven for OpenSearch service where to enable the JWT authentication. -1. Click in the sidebar. -1. Scroll to the **Advanced configuration** section and click **Configure**. -1. In the **Advanced configuration** window: - 1. Click **Add configuration options**. - 1. Enter `jwt` in the search field to preview all JWT-related configuration options. - 1. Select the `jwt.signing_key` option and set it to your password. - 1. Select the `jwt.enabled` option and set it to `enabled`. - 1. Click **Save configuration**. +1. Click in the sidebar. +1. In the **SSO authentication** section, click **Add method** > **JWT**. +1. In the **Configure JWT authentication** window, set up the following: + - **Signing algorithm**: Choose `RSA/ECDSA` or `HMAC`. + - **Signing key**: Enter your public key to verify your JWT signature when using + RSA/ECDSA. + - **HTTP header name**: Provide it if your JWT is transmitted as an HTTP header. + - **URL parameter name**: Provide it if your JWT is transmitted as a URL parameter. + - **JWT claim key for subject**: Enter the JWT payload key that contains the user's + subject identifier to override the `sub` default. + - **JWT claim key for roles**: Enter the JWT payload key that contains the user's + roles to have them extracted from the JWT for authorization. + - **Required JWT audience**: Provide a value for the `aud` claim in the JWT to restrict + its audience. + - **Required JWT issuer**: Provide a value for the `iss` claim in the JWT to restrict + its issuer. + - **JWT Clock Skew Tolerance (seconds)**: Specify the maximum time difference between + the JWT's issuer's clock and the OpenSearch server's clock. +1. Click **Enable** to complete the setup and activate the + configuration. From dcc30704ee15697102e1e6c4687263cf77ad67ff Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Fri, 26 Sep 2025 09:56:53 +0200 Subject: [PATCH 6/6] Feedback Co-authored-by: Stacey Salamon <111294980+staceysalamon-aiven@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/opensearch/howto/jwt-authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/products/opensearch/howto/jwt-authentication.md b/docs/products/opensearch/howto/jwt-authentication.md index c5d5db442..8e7e74a17 100644 --- a/docs/products/opensearch/howto/jwt-authentication.md +++ b/docs/products/opensearch/howto/jwt-authentication.md @@ -22,7 +22,7 @@ When you make a request to your Aiven for OpenSearch service: key you configure. 1. **User is identified**: Aiven for OpenSearch extracts the username from the token's subject claim. -1. **Role is assignment**: If configured, user roles are extracted from the token or +1. **Role is assigned**: If configured, user roles are extracted from the token or managed separately in Aiven for OpenSearch. 1. **Access is granted**: Valid tokens provide seamless access to your Aiven for OpenSearch service. @@ -100,7 +100,7 @@ avn service update SERVICE_NAME \ -c jwt.jwt_url_parameter=JWT_URL_PARAMETER ``` -Replace the following placeholders with meaningful data: +Replace the following placeholders with your data: - `SERVICE_NAME` with the name of your Aiven for OpenSearch service, for example, `os2-jwt` - `SIGNING_KEY` with your base64-encoded signing key (PEM-formatted RSA/ECDSA public key or