From b98d47eeaf64def53f308ebcb6d8dbdcaee7e6ec Mon Sep 17 00:00:00 2001 From: cwillum Date: Tue, 27 Jun 2023 20:05:44 -0700 Subject: [PATCH 1/6] fix#4388 obo token authz Signed-off-by: cwillum --- _security/authentication-backends/obo-token.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 _security/authentication-backends/obo-token.md diff --git a/_security/authentication-backends/obo-token.md b/_security/authentication-backends/obo-token.md new file mode 100644 index 0000000000..d07cc2fd99 --- /dev/null +++ b/_security/authentication-backends/obo-token.md @@ -0,0 +1,11 @@ +--- +layout: default +title: On-behalf-of tokens +parent: Authentication backends +nav_order: 75 +--- + + +# On-behalf-of tokens + +On-behalf-of tokens have the ability to enable services to run with OpenSearch by letting a user authenticate the services on their behalf. \ No newline at end of file From 18317d5d506e8ce964d1ab61426956b2b99aa610 Mon Sep 17 00:00:00 2001 From: cwillum Date: Wed, 28 Jun 2023 12:00:52 -0700 Subject: [PATCH 2/6] fix#4388 obo token authz Signed-off-by: cwillum --- _security/authentication-backends/obo-token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/authentication-backends/obo-token.md b/_security/authentication-backends/obo-token.md index d07cc2fd99..d77bb8d2da 100644 --- a/_security/authentication-backends/obo-token.md +++ b/_security/authentication-backends/obo-token.md @@ -8,4 +8,4 @@ nav_order: 75 # On-behalf-of tokens -On-behalf-of tokens have the ability to enable services to run with OpenSearch by letting a user authenticate the services on their behalf. \ No newline at end of file +On-behalf-of tokens enable services to run on OpenSearch by allowing users to authorize access on behalf of the service. \ No newline at end of file From 3ce5abd94d23f2d2555639834abb5d643f66be38 Mon Sep 17 00:00:00 2001 From: cwillum Date: Wed, 28 Jun 2023 12:10:03 -0700 Subject: [PATCH 3/6] fix#4388 obo token authz Signed-off-by: cwillum --- _security/authentication-backends/obo-token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/authentication-backends/obo-token.md b/_security/authentication-backends/obo-token.md index d77bb8d2da..d123b304b3 100644 --- a/_security/authentication-backends/obo-token.md +++ b/_security/authentication-backends/obo-token.md @@ -8,4 +8,4 @@ nav_order: 75 # On-behalf-of tokens -On-behalf-of tokens enable services to run on OpenSearch by allowing users to authorize access on behalf of the service. \ No newline at end of file +On-behalf-of tokens enable services to run on OpenSearch by allowing a user's security privileges to authorize access on behalf of the service. These tokens can be used for any generic service that you want to run on OpenSearch. However, their initial and current application with OpenSearch involves the support of Security extension functionality. \ No newline at end of file From 3e2b4e61e23264f80320a6ddebccb555e23915bd Mon Sep 17 00:00:00 2001 From: cwillum Date: Thu, 24 Aug 2023 17:35:56 -0700 Subject: [PATCH 4/6] fix#4388 obo token authz Signed-off-by: cwillum --- .../authentication-backends/obo-token.md | 54 ++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/_security/authentication-backends/obo-token.md b/_security/authentication-backends/obo-token.md index d123b304b3..213b883d17 100644 --- a/_security/authentication-backends/obo-token.md +++ b/_security/authentication-backends/obo-token.md @@ -8,4 +8,56 @@ nav_order: 75 # On-behalf-of tokens -On-behalf-of tokens enable services to run on OpenSearch by allowing a user's security privileges to authorize access on behalf of the service. These tokens can be used for any generic service that you want to run on OpenSearch. However, their initial and current application with OpenSearch involves the support of Security extension functionality. \ No newline at end of file +On-behalf-of (OBO) tokens enable services to run on OpenSearch by allowing a user's security privileges to authorize access on behalf of the service. These tokens can be used for any generic service that you want to run on OpenSearch. However, their initial application with OpenSearch involves supporting the use of extensions. + + +## Description + +The OBO token is a JSON Web Token (JWT) used for managing authentication requests between a user's client and an extension or other service. For the initial extensions design, these tokens allow the extension to interact with the OpenSearch cluster using the same privileges as the initiating user; hence the name, “on-behalf-of”. Because these tokens don’t have any real restrictions, they can be used to permit access to any generic service for a set window of time. + +The OBO token provides just-in-time access for extension services and other resources. This means that the token is issued immediately before it is needed rather than at the beginning of a session with the expectation that access persists over the course of the session. This approach is often considered a more secure method of authentication due to the fixed and relatively short length of time it remains valid and the focused access it applies to a select service. + +Given that the OBO token is a JWT, it includes an expiration claim that determines how long the token remains valid. You can therefore configure the token so that it provides access to a service for a short, predertimed length of time. + + +### Token payload + +The payload for an OBO token includes the following claims. To read more about JWT claims, see [JSON Web Token Claims](https://www.iana.org/assignments/jwt/jwt.xhtml#claims). + +| Claim | Claim description | +| :--- | :--- | +| `iss` | Issuer. The OpenSearch cluster identifier. | +| `iat` | Issued at. Time at which the token was issued. | +| `exp` | Expiration time. | +| `sub` | Subject. User ID | +| `aud` | Audience. The extension's, or the service's, unique identifier. | +| `roles` | Roles. Security privilege evaluation. | + + + +## Configuring the token + +As with all backends, the OBO token is configured in the `config.yml` file. + +```yml +on_behalf_of: + signing_key: xxxxxxxxxx + encryption_key: xxxxxxxx +``` + + + +## Plugin backward compatibility + +To make backend roles backward compatible for plugins, the following configuration is necessary: + +```yml +BWC Mode OFF (default): +Encrypted roles (er) +BWC Mode ON: +Decrypted roles in plain-text (dr) +Decrypted backend roles in plain-text (dbr) +``` + + + From 16dfedf440c49da6df563dcc3fdba3769639105a Mon Sep 17 00:00:00 2001 From: cwillum Date: Fri, 25 Aug 2023 09:43:20 -0700 Subject: [PATCH 5/6] fix#4388 obo token authz Signed-off-by: cwillum --- _security/authentication-backends/obo-token.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_security/authentication-backends/obo-token.md b/_security/authentication-backends/obo-token.md index 213b883d17..9e3bf3cd3f 100644 --- a/_security/authentication-backends/obo-token.md +++ b/_security/authentication-backends/obo-token.md @@ -31,7 +31,7 @@ The payload for an OBO token includes the following claims. To read more about J | `exp` | Expiration time. | | `sub` | Subject. User ID | | `aud` | Audience. The extension's, or the service's, unique identifier. | -| `roles` | Roles. Security privilege evaluation. | +| `roles` | Roles. Security privilege evaluation. | @@ -47,9 +47,9 @@ on_behalf_of: -## Plugin backward compatibility +## Enabling backend roles -To make backend roles backward compatible for plugins, the following configuration is necessary: +To make backend roles backward compatible for plugins, the following configuration is necessary in the `extensions/extensions.yml` file: ```yml BWC Mode OFF (default): @@ -58,6 +58,6 @@ BWC Mode ON: Decrypted roles in plain-text (dr) Decrypted backend roles in plain-text (dbr) ``` - + From 6f30302b6c752b941a1e9015ebd5166119ef078a Mon Sep 17 00:00:00 2001 From: cwillum Date: Wed, 30 Aug 2023 15:40:47 -0700 Subject: [PATCH 6/6] fix#4388 obo token authz Signed-off-by: cwillum --- .../authentication-backends/obo-token.md | 33 +++++++++++++++++-- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/_security/authentication-backends/obo-token.md b/_security/authentication-backends/obo-token.md index 9e3bf3cd3f..dfc0164b50 100644 --- a/_security/authentication-backends/obo-token.md +++ b/_security/authentication-backends/obo-token.md @@ -17,7 +17,7 @@ The OBO token is a JSON Web Token (JWT) used for managing authentication request The OBO token provides just-in-time access for extension services and other resources. This means that the token is issued immediately before it is needed rather than at the beginning of a session with the expectation that access persists over the course of the session. This approach is often considered a more secure method of authentication due to the fixed and relatively short length of time it remains valid and the focused access it applies to a select service. -Given that the OBO token is a JWT, it includes an expiration claim that determines how long the token remains valid. You can therefore configure the token so that it provides access to a service for a short, predertimed length of time. +Given that the OBO token is a JWT, it includes an expiration claim that determines how long the token remains valid. You can therefore configure the token so that it provides access to a service for a short, predetermined length of time. ### Token payload @@ -37,14 +37,41 @@ The payload for an OBO token includes the following claims. To read more about J ## Configuring the token -As with all backends, the OBO token is configured in the `config.yml` file. +As with all backends, the OBO token is configured in the `authc` section of the `config.yml` file. Set up an authentication domain and choose `on_behalf_of` as the `http_authenticator`. Because the tokens already contain all required information to verify the request, set `challenge` to `false` and `authentication_backend` to `noop`: ```yml on_behalf_of: signing_key: xxxxxxxxxx encryption_key: xxxxxxxx ``` - + + +The following table lists the most important configuration parameters. + +Name | Description +:--- | :--- +`signing_key` | The signing key to use when verifying the token. If you use a symmetric key algorithm, it is the base64-encoded shared secret. If you use an asymmetric algorithm, it contains the public key. +`encryption_key` | ## Enabling backend roles