From badb6ca299489d1de2dce59e55ade31a49c73847 Mon Sep 17 00:00:00 2001 From: Stephen Crawford Date: Tue, 7 Nov 2023 10:52:43 -0500 Subject: [PATCH 01/56] readd auth token doc Signed-off-by: Stephen Crawford --- .../access-control/authentication-tokens.md | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 _security/access-control/authentication-tokens.md diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md new file mode 100644 index 0000000000..0487670c87 --- /dev/null +++ b/_security/access-control/authentication-tokens.md @@ -0,0 +1,120 @@ +--- +layout: default +title: Authorization tokens +parent: Access control +nav_order: 125 +redirect_from: + - /security/access-control/authorization-tokens/ + - /security-plugin/access-control/authorization-tokens/ +--- + +## On-Behalf-Of Authentication + +### 1.0 Usage +On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued just before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. + +On-behalf-of tokens will allow an extension to interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension related use cases. + +### 2.0 Configuration +In the security config file, the on-behalf-of configuration is located under the dynamic config section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: +``` +config: + dynamic: + on_behalf_of: + enabled: #'true'/non-specified will be consider as 'enabled' + signing_key: #encoded signing key here + encryption_key: #encoded encryption key here +... +``` + +The encoding algorithm is HMAC SHA512 by default for the signing of the JWT. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise it encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. + +### 3.0 Token Structure +The payload of an on-behalf-of token must include all standard configurations of a JWT (JSON Web Token), along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. + +The on-behalf-of token contains the following claims: +* Issuer (`iss`): OpenSearch Cluster Identifier + * It is essential that the issuer is validated as a part of security control measures. This strategy is forward-thinking, particularly in the context of potential multi-tenant scenarios like OpenSearch Serverless, where differing cryptographic keys could be associated with each issuer. By checking the value of issuer, each on-behalf-of token is restricted to its associated issuer. +* Issue-at (`iat`): Current time of issuing this token + * Used as the reference of the expiration. +* Not-before (`nbf`): The earliest point at which the token can be used. + * Given that the on-behalf-of token is designed for just-in-time usage, its `nbf` should align with the `iat` (issued-at) time, indicating the moment when the token was created. +* Expiry (`exp`): Expiration time + * Each on-behalf-of token incorporates an expiration mechanism, which is verified upon its receipt. Once a token is issued, it cannot be revoked. Instead, the only token is only invalidated upon its expiration. Furthermore, the generation of on-behalf-of tokens by extensions is subject to dynamic settings. This functionality safeguards the system by preventing the issuance of future tokens under certain conditions. + * The default configuration establishes an expiration time of 300 seconds for on-beahalf-of tokens. Recognizing that different scenarios may necessitate different token durations, we have incorporated the capability for users to personalize this expiration time. At present, the maximum duration that can be assigned to a token is 600 seconds. + * In reference to the current design of the on-behalf-of (obo) token, it's accurate to say that token revocation isn't a current concern, given its intended just-in-time use and brief lifespan. However, if future adjustments necessitate an extended lifespan for this token, token revocation will be added. This strategy will be adopted to improve and solidify the security measures associated with on-behalf-of token use. +* Subject (`sub`): User Identifier + * Name of the user with which this on-behalf-of token is associated. +* Audience (`aud`): Extension’s unique identifier + * For the extension use case, the aud field is a reference to the specific extension that represents the target service. + * For the REST API use case, the the API parameter “service” will let user to specify the target service(s) using this token, and the default value is set to “self-issued“ +* Roles: Security Privilege Evaluation + * Role Security Mode [[source code](https://github.com/opensearch-project/security/blob/main/src/main/java/org/opensearch/security/authtoken/jwt/JwtVendor.java#L151)], this configuration determines the encryption of the roles claim. + * Role Security Mode On (default value) - Roles claim will be encrypted. + * Encrypted mapped roles (`er`) + * Role Security Mode Off - Roles claims will be in plain-text, and both mapped roles and backend roles will be included in the claim [[related discussion](https://github.com/opensearch-project/security/issues/2865)] + * Decrypted mapped roles in plain text (`dr`) + * Decrypted backend roles (`br`) + +The OpenSearch security plugin will be responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third party services. + +### 3.0 API Endpoint +There will be an new API endpoint `POST /_plugins/_security/api/generateonbehalfoftoken` on the security plugin that will allow users to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. + +To access this API endpoint, the request body should contain three API parameters: + +* description: This allows the use to articulate the purpose for requesting this token, providing clarity and transparency. +* service (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". +* durationSeconds (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. +* Here is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: +``` +curl -XPOST https://localhost:9200/_plugins/_security/api/generateonbehalfoftoken -u 'admin:admin' -H 'Content-Type: application/json' --data +'{ + "description":"Testing", + "service":"Testing Service", + "durationSeconds":"180" +}' +``` + +### 4.0 Additional Authorization Restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) + +While the conversation about the usage of on-behalf-of (OBO) tokens continues, it is critical to manage certain edge cases. Even though an OBO token can act as a valid Bearer authorization header for any API access, there needs to be certain limitations. For instance, it should be forbidden to use an OBO token to access the API endpoint to issue another OBO token. Similarly, using an OBO token to access the reset password API in order to modify a user's authentication information should be disallowed. These preventive measures are necessary to uphold the integrity and security of the system. + +## Service Accounts + +### 1.0 Introduction of Service Accounts +Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. **Currently, Service Account only permit operations on system indices associated with the mapped extension.** + +### 2.0 Service Account Background +Before the introduction of Service Accounts, it was not possible for an extension to execute a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User which acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: +* Impersonation compromises referential integrity, meaning it is difficult for auditors to identify which requests were executed by an extension or by an operator. A system with referential integrity maintains a transactional record in its audit log. The record provides a clear history of actions taken by various subjects at specific times. When extensions impersonate users for both requests they make on behalf of the operator, and requests they execute on their own, the audit log lacks referential integrity. +* Impersonation also makes it impossible to restrict an extension’s permissions beyond those of the user it impersonates. When an extension assumes the roles of the active subject, it copies all of the roles. This includes even those permissions which are uneccessary for executing its intended actions. This practice not only deviates from the principal of least-privileges, but also increases the threat surface area. With each additional permission granted to the Plugin User, the potential impact a misconfigured or malicious extension may have grows. + +### 3.0 Service Account Benefit +Service Accounts address the issues listed in 2.0 by defining a separate state which autonomously executing extensions run in. Service Accounts maintain referential integrity by introducing a distinct state which extensions run in when executing requests on their own behalf. Audit logging can then record when an extension executes on its own—it will make authC/authZ calls against the Service Account—or whether it is executing an action on behalf of the operator and therefore making use of the OnBehalfOf tokens. + +Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. + +### 4.0 API Endpoint +As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled` attempts to fetch its auth token will be blocked and it will be unable to execute requests on its own behalf using a previously issued auth token. +* Here is an example of create a service account with ALL PERMISSIONS for your service/extension: +``` +curl -XPUT "[https://localhost:9200/_plugins/_security/api/internalusers/admin-extension https://localhost:9200/_plugins/_security/api/internalusers/hello-world" -H 'Content-Type: application/json' -d' +{ + "opendistro_security_roles": ["all_access"], + "backend_roles": [], + "attributes": { + "enabled": "true", + "service": "true" + } +}' -u "admin:admin" --insecure +``` + +## Handling on-behalf-of & Service Account Requests +While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the `IdentityPlugin` implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. + +Extensions acting on their own behalf also make use of the client exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Account for it and provide the associated Service Account token. In the default configuration, the Security Plugin is the `IdentityPlugin` and handles these processes. After OpenSearch receives the Service Account token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Account associated with the extension are operable. In these scenarios, the extension receives the requests from the client, and then forwards the request along with the Service Account token to OpenSearch. OpenSearch further transfers the packages to the Security Plugin where the token is parsed and the request is treated as a traditional request using Basic Authentication in the `InternalAuthenticationBackend`. + +In both on-behalf-of and Service Account token request flows, the `IdentityPlugin`'s `TokenManager` interface is used by the `IdentityPlugin` to handle the distribution and processing of the tokens. This interface is implemented by the Security Plugin as an `IdentityPlugin` and contains logic for issuing a token which is either an on-behalf-of or Service Account token. + + From 10158d3f744c967abec4079173927e63e227647b Mon Sep 17 00:00:00 2001 From: Stephen Crawford Date: Mon, 13 Nov 2023 16:44:12 -0500 Subject: [PATCH 02/56] Fix vale Signed-off-by: Stephen Crawford --- .../access-control/authentication-tokens.md | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 0487670c87..e52c5b9f6b 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -8,15 +8,18 @@ redirect_from: - /security-plugin/access-control/authorization-tokens/ --- -## On-Behalf-Of Authentication +## On-Behalf-Of authentication + +The Security plugin allows you to configure two types of authentication tokens. The first of these is On-Behalf-Of (OBO) tokens. ### 1.0 Usage -On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued just before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. +On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. On-behalf-of tokens will allow an extension to interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension related use cases. ### 2.0 Configuration In the security config file, the on-behalf-of configuration is located under the dynamic config section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: + ``` config: dynamic: @@ -29,7 +32,7 @@ config: The encoding algorithm is HMAC SHA512 by default for the signing of the JWT. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise it encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. -### 3.0 Token Structure +### 3.0 Token structure The payload of an on-behalf-of token must include all standard configurations of a JWT (JSON Web Token), along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. The on-behalf-of token contains the following claims: @@ -40,14 +43,14 @@ The on-behalf-of token contains the following claims: * Not-before (`nbf`): The earliest point at which the token can be used. * Given that the on-behalf-of token is designed for just-in-time usage, its `nbf` should align with the `iat` (issued-at) time, indicating the moment when the token was created. * Expiry (`exp`): Expiration time - * Each on-behalf-of token incorporates an expiration mechanism, which is verified upon its receipt. Once a token is issued, it cannot be revoked. Instead, the only token is only invalidated upon its expiration. Furthermore, the generation of on-behalf-of tokens by extensions is subject to dynamic settings. This functionality safeguards the system by preventing the issuance of future tokens under certain conditions. + * Each on-behalf-of token incorporates an expiration mechanism, which is verified upon its receipt. Once a token is issued, it cannot be revoked. Instead, the only token is only invalidated upon its expiration. Furthermore, the generation of on-behalf-of tokens by extensions is subject to dynamic settings. This functionality safeguards the system by preventing the issuance of future tokens under certain conditions. * The default configuration establishes an expiration time of 300 seconds for on-beahalf-of tokens. Recognizing that different scenarios may necessitate different token durations, we have incorporated the capability for users to personalize this expiration time. At present, the maximum duration that can be assigned to a token is 600 seconds. - * In reference to the current design of the on-behalf-of (obo) token, it's accurate to say that token revocation isn't a current concern, given its intended just-in-time use and brief lifespan. However, if future adjustments necessitate an extended lifespan for this token, token revocation will be added. This strategy will be adopted to improve and solidify the security measures associated with on-behalf-of token use. + * In reference to the current design of the On-Behalf-Of token, it's accurate to say that token revocation isn't a current concern, given its intended just-in-time use and brief lifespan. However, if future adjustments necessitate an extended lifespan for this token, token revocation will be added. This strategy will be adopted to improve and solidify the security measures associated with on-behalf-of token use. * Subject (`sub`): User Identifier * Name of the user with which this on-behalf-of token is associated. * Audience (`aud`): Extension’s unique identifier * For the extension use case, the aud field is a reference to the specific extension that represents the target service. - * For the REST API use case, the the API parameter “service” will let user to specify the target service(s) using this token, and the default value is set to “self-issued“ + * For the REST API use case, the API parameter “service” will let user to specify the target service(s) using this token, and the default value is set to “self-issued“ * Roles: Security Privilege Evaluation * Role Security Mode [[source code](https://github.com/opensearch-project/security/blob/main/src/main/java/org/opensearch/security/authtoken/jwt/JwtVendor.java#L151)], this configuration determines the encryption of the roles claim. * Role Security Mode On (default value) - Roles claim will be encrypted. @@ -56,9 +59,9 @@ The on-behalf-of token contains the following claims: * Decrypted mapped roles in plain text (`dr`) * Decrypted backend roles (`br`) -The OpenSearch security plugin will be responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third party services. +The OpenSearch Security plugin will be responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third party services. -### 3.0 API Endpoint +### 3.0 API endpoint There will be an new API endpoint `POST /_plugins/_security/api/generateonbehalfoftoken` on the security plugin that will allow users to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. To access this API endpoint, the request body should contain three API parameters: @@ -110,7 +113,7 @@ curl -XPUT "[https://localhost:9200/_plugins/_security/api/internalusers/admin-e }' -u "admin:admin" --insecure ``` -## Handling on-behalf-of & Service Account Requests +## Handling On-Behalf-Of and Service Account Requests While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the `IdentityPlugin` implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. Extensions acting on their own behalf also make use of the client exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Account for it and provide the associated Service Account token. In the default configuration, the Security Plugin is the `IdentityPlugin` and handles these processes. After OpenSearch receives the Service Account token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Account associated with the extension are operable. In these scenarios, the extension receives the requests from the client, and then forwards the request along with the Service Account token to OpenSearch. OpenSearch further transfers the packages to the Security Plugin where the token is parsed and the request is treated as a traditional request using Basic Authentication in the `InternalAuthenticationBackend`. From 031054c4250b33ce068264100daa264a5d30c9c4 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:24:10 -0500 Subject: [PATCH 03/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index e52c5b9f6b..691f43bf45 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -15,7 +15,7 @@ The Security plugin allows you to configure two types of authentication tokens. ### 1.0 Usage On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. -On-behalf-of tokens will allow an extension to interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension related use cases. +With on-behalf-of tokens, an extension can interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension-related use cases. ### 2.0 Configuration In the security config file, the on-behalf-of configuration is located under the dynamic config section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: From 57858d52656dde67ab7770d38935264005c6f977 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:24:23 -0500 Subject: [PATCH 04/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 691f43bf45..40729024bc 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -30,7 +30,7 @@ config: ... ``` -The encoding algorithm is HMAC SHA512 by default for the signing of the JWT. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise it encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. +The default encoding algorithm for the signing of the JWT (JSON Web Token) is HMAC SHA512. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. ### 3.0 Token structure The payload of an on-behalf-of token must include all standard configurations of a JWT (JSON Web Token), along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. From 7aabc9337c3d7e0bbee316c417e07d54da9f8a34 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:24:33 -0500 Subject: [PATCH 05/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 40729024bc..3e9448acb0 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -40,7 +40,7 @@ The on-behalf-of token contains the following claims: * It is essential that the issuer is validated as a part of security control measures. This strategy is forward-thinking, particularly in the context of potential multi-tenant scenarios like OpenSearch Serverless, where differing cryptographic keys could be associated with each issuer. By checking the value of issuer, each on-behalf-of token is restricted to its associated issuer. * Issue-at (`iat`): Current time of issuing this token * Used as the reference of the expiration. -* Not-before (`nbf`): The earliest point at which the token can be used. +* Not-before (`nbf`): The earliest point at which the token can be used * Given that the on-behalf-of token is designed for just-in-time usage, its `nbf` should align with the `iat` (issued-at) time, indicating the moment when the token was created. * Expiry (`exp`): Expiration time * Each on-behalf-of token incorporates an expiration mechanism, which is verified upon its receipt. Once a token is issued, it cannot be revoked. Instead, the only token is only invalidated upon its expiration. Furthermore, the generation of on-behalf-of tokens by extensions is subject to dynamic settings. This functionality safeguards the system by preventing the issuance of future tokens under certain conditions. From 231b57139e533537e54aabbb0e0a1caa0197f36d Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:24:42 -0500 Subject: [PATCH 06/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 3e9448acb0..f3fd97cdbe 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -33,7 +33,7 @@ config: The default encoding algorithm for the signing of the JWT (JSON Web Token) is HMAC SHA512. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. ### 3.0 Token structure -The payload of an on-behalf-of token must include all standard configurations of a JWT (JSON Web Token), along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. +The payload of an on-behalf-of token must include all standard configurations of a JWT, along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. The on-behalf-of token contains the following claims: * Issuer (`iss`): OpenSearch Cluster Identifier From f2c257bde69d68d6c828f23bcaef4ecef8461f5a Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:26:18 -0500 Subject: [PATCH 07/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index f3fd97cdbe..6c2a4f52aa 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -59,7 +59,7 @@ The on-behalf-of token contains the following claims: * Decrypted mapped roles in plain text (`dr`) * Decrypted backend roles (`br`) -The OpenSearch Security plugin will be responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third party services. +The OpenSearch Security plugin is responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third-party services. ### 3.0 API endpoint There will be an new API endpoint `POST /_plugins/_security/api/generateonbehalfoftoken` on the security plugin that will allow users to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. From 89f2ea6fe483dab38f0915a887a2599ba1fa9feb Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:26:26 -0500 Subject: [PATCH 08/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 6c2a4f52aa..c2666008e1 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -76,7 +76,7 @@ curl -XPOST https://localhost:9200/_plugins/_security/api/generateonbehalfoftoke "description":"Testing", "service":"Testing Service", "durationSeconds":"180" -}' +} ``` ### 4.0 Additional Authorization Restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) From b65267ef6444aed809be9781137fffe9d18f3c3f Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:26:58 -0500 Subject: [PATCH 09/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index c2666008e1..be6ba77c5c 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -62,7 +62,7 @@ The on-behalf-of token contains the following claims: The OpenSearch Security plugin is responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third-party services. ### 3.0 API endpoint -There will be an new API endpoint `POST /_plugins/_security/api/generateonbehalfoftoken` on the security plugin that will allow users to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. +You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API endpoint on the security plugin in order to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. To access this API endpoint, the request body should contain three API parameters: From 8be7a23b3c377916bdf5f32ada9e01b02180e76f Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:27:18 -0500 Subject: [PATCH 10/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index be6ba77c5c..e3f2ebc784 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -66,7 +66,7 @@ You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API en To access this API endpoint, the request body should contain three API parameters: -* description: This allows the use to articulate the purpose for requesting this token, providing clarity and transparency. +* `description`: This parameter allows the user to articulate the purpose for requesting this token, providing clarity and transparency. * service (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". * durationSeconds (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. * Here is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: From 3702667afdd84e71a530f1ace0f67b380a33827a Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:27:25 -0500 Subject: [PATCH 11/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index e3f2ebc784..84b410de4b 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -70,7 +70,7 @@ To access this API endpoint, the request body should contain three API parameter * service (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". * durationSeconds (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. * Here is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: -``` +```json curl -XPOST https://localhost:9200/_plugins/_security/api/generateonbehalfoftoken -u 'admin:admin' -H 'Content-Type: application/json' --data '{ "description":"Testing", From b07d204b18946535bea70dc952df4aae0742f33e Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:27:33 -0500 Subject: [PATCH 12/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 84b410de4b..a22a8af0d1 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -101,7 +101,7 @@ Similarly, Service Accounts address threat exposure concerns by separating the r ### 4.0 API Endpoint As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled` attempts to fetch its auth token will be blocked and it will be unable to execute requests on its own behalf using a previously issued auth token. * Here is an example of create a service account with ALL PERMISSIONS for your service/extension: -``` +```json curl -XPUT "[https://localhost:9200/_plugins/_security/api/internalusers/admin-extension https://localhost:9200/_plugins/_security/api/internalusers/hello-world" -H 'Content-Type: application/json' -d' { "opendistro_security_roles": ["all_access"], From f196b480ac13afe780407eab1472bf08eb448945 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:27:47 -0500 Subject: [PATCH 13/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index a22a8af0d1..e3be068505 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -67,7 +67,7 @@ You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API en To access this API endpoint, the request body should contain three API parameters: * `description`: This parameter allows the user to articulate the purpose for requesting this token, providing clarity and transparency. -* service (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". +* `service` (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". * durationSeconds (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. * Here is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: ```json From b97006f50902f01023dcd3754571bf1dbbfec56e Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:28:02 -0500 Subject: [PATCH 14/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index e3be068505..286b301d8f 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -68,7 +68,7 @@ To access this API endpoint, the request body should contain three API parameter * `description`: This parameter allows the user to articulate the purpose for requesting this token, providing clarity and transparency. * `service` (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". -* durationSeconds (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. +* `durationSeconds` (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. * Here is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: ```json curl -XPOST https://localhost:9200/_plugins/_security/api/generateonbehalfoftoken -u 'admin:admin' -H 'Content-Type: application/json' --data From 05c2cf45b62f764e81233d8ec48da11a6f624f04 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:28:21 -0500 Subject: [PATCH 15/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 286b301d8f..1cc4657d82 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -69,7 +69,7 @@ To access this API endpoint, the request body should contain three API parameter * `description`: This parameter allows the user to articulate the purpose for requesting this token, providing clarity and transparency. * `service` (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". * `durationSeconds` (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. -* Here is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: +The following is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: ```json curl -XPOST https://localhost:9200/_plugins/_security/api/generateonbehalfoftoken -u 'admin:admin' -H 'Content-Type: application/json' --data '{ From 66ff46411718ecab24952fef2777f8fd8748472e Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:32:57 -0500 Subject: [PATCH 16/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 1cc4657d82..bf50de4f91 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -86,7 +86,10 @@ While the conversation about the usage of on-behalf-of (OBO) tokens continues, i ## Service Accounts ### 1.0 Introduction of Service Accounts -Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. **Currently, Service Account only permit operations on system indices associated with the mapped extension.** +Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. + +Currently, Service Account only permit operations on system indices associated with the mapped extension. +{: .important} ### 2.0 Service Account Background Before the introduction of Service Accounts, it was not possible for an extension to execute a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User which acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: From 813bcb5ebff1083169f72e4eab3fb4536853e3cd Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:33:31 -0500 Subject: [PATCH 17/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index bf50de4f91..1cd6a87726 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -97,7 +97,7 @@ Before the introduction of Service Accounts, it was not possible for an extensio * Impersonation also makes it impossible to restrict an extension’s permissions beyond those of the user it impersonates. When an extension assumes the roles of the active subject, it copies all of the roles. This includes even those permissions which are uneccessary for executing its intended actions. This practice not only deviates from the principal of least-privileges, but also increases the threat surface area. With each additional permission granted to the Plugin User, the potential impact a misconfigured or malicious extension may have grows. ### 3.0 Service Account Benefit -Service Accounts address the issues listed in 2.0 by defining a separate state which autonomously executing extensions run in. Service Accounts maintain referential integrity by introducing a distinct state which extensions run in when executing requests on their own behalf. Audit logging can then record when an extension executes on its own—it will make authC/authZ calls against the Service Account—or whether it is executing an action on behalf of the operator and therefore making use of the OnBehalfOf tokens. +Service Accounts address the issues listed in 2.0 by defining a separate state in which autonomously executing extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when executing requests on their own behalf. Audit logging can then record when an extension executes on its own—it will make authC/authZ calls against the Service Account—or whether it is executing an action on behalf of the operator and therefore making use of the on-behalf-of tokens. Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. From 6b5c8e345eb8f7c191d92f15896ef80dc9ddc1ff Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:33:47 -0500 Subject: [PATCH 18/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 1cd6a87726..4499d11366 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -99,7 +99,7 @@ Before the introduction of Service Accounts, it was not possible for an extensio ### 3.0 Service Account Benefit Service Accounts address the issues listed in 2.0 by defining a separate state in which autonomously executing extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when executing requests on their own behalf. Audit logging can then record when an extension executes on its own—it will make authC/authZ calls against the Service Account—or whether it is executing an action on behalf of the operator and therefore making use of the on-behalf-of tokens. -Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. +Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard-coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. ### 4.0 API Endpoint As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled` attempts to fetch its auth token will be blocked and it will be unable to execute requests on its own behalf using a previously issued auth token. From 551008854a0df36743f2cbf625bcf3fb94fad9c7 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:34:02 -0500 Subject: [PATCH 19/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 4499d11366..521d22e207 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -102,7 +102,7 @@ Service Accounts address the issues listed in 2.0 by defining a separate state i Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard-coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. ### 4.0 API Endpoint -As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled` attempts to fetch its auth token will be blocked and it will be unable to execute requests on its own behalf using a previously issued auth token. +As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. * Here is an example of create a service account with ALL PERMISSIONS for your service/extension: ```json curl -XPUT "[https://localhost:9200/_plugins/_security/api/internalusers/admin-extension https://localhost:9200/_plugins/_security/api/internalusers/hello-world" -H 'Content-Type: application/json' -d' From f542553eddb1fc790b1970d803ad15f064a9e51e Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:34:15 -0500 Subject: [PATCH 20/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 521d22e207..1149ce3008 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -103,7 +103,7 @@ Similarly, Service Accounts address threat exposure concerns by separating the r ### 4.0 API Endpoint As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. -* Here is an example of create a service account with ALL PERMISSIONS for your service/extension: +The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json curl -XPUT "[https://localhost:9200/_plugins/_security/api/internalusers/admin-extension https://localhost:9200/_plugins/_security/api/internalusers/hello-world" -H 'Content-Type: application/json' -d' { From ef0f543cb2f08b6358b51768ec8f42867b01fe45 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:34:38 -0500 Subject: [PATCH 21/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 1149ce3008..d9b28aa563 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -71,7 +71,7 @@ To access this API endpoint, the request body should contain three API parameter * `durationSeconds` (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. The following is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: ```json -curl -XPOST https://localhost:9200/_plugins/_security/api/generateonbehalfoftoken -u 'admin:admin' -H 'Content-Type: application/json' --data +POST /_plugins/_security/api/generateonbehalfoftoken '{ "description":"Testing", "service":"Testing Service", From c0ef181f1b890767e7ec7840f98bf5e39dc4f443 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:35:06 -0500 Subject: [PATCH 22/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index d9b28aa563..6a69ffc593 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -72,7 +72,7 @@ To access this API endpoint, the request body should contain three API parameter The following is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: ```json POST /_plugins/_security/api/generateonbehalfoftoken -'{ +{ "description":"Testing", "service":"Testing Service", "durationSeconds":"180" From 035cae6de6d952ed8b082005533b29ad18dd9e7a Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:35:59 -0500 Subject: [PATCH 23/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 6a69ffc593..c76154ad58 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -10,7 +10,7 @@ redirect_from: ## On-Behalf-Of authentication -The Security plugin allows you to configure two types of authentication tokens. The first of these is On-Behalf-Of (OBO) tokens. +The Security plugin allows you to configure two types of authentication tokens: On-Behalf-Of (OBO) tokens and Service Account tokens. ### 1.0 Usage On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. From e51cff1ae68635763e9ca8699729084d7ead6f66 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:36:12 -0500 Subject: [PATCH 24/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index c76154ad58..4f663212aa 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -78,6 +78,7 @@ POST /_plugins/_security/api/generateonbehalfoftoken "durationSeconds":"180" } ``` +{% include copy-curl.html %} ### 4.0 Additional Authorization Restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) From de00af4ae8c0557ce7338ff3c2d34563bdf9c5f8 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:37:06 -0500 Subject: [PATCH 25/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 4f663212aa..0bbdfa392b 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -86,6 +86,7 @@ While the conversation about the usage of on-behalf-of (OBO) tokens continues, i ## Service Accounts +Service Accounts tokens are the second form of authentication token supported by the Security plugin. ### 1.0 Introduction of Service Accounts Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. From 69663c9c66a8ff36c0dfa9128998fb6302d309e8 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:37:28 -0500 Subject: [PATCH 26/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 0bbdfa392b..e04ac19c0a 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -87,6 +87,7 @@ While the conversation about the usage of on-behalf-of (OBO) tokens continues, i ## Service Accounts Service Accounts tokens are the second form of authentication token supported by the Security plugin. + ### 1.0 Introduction of Service Accounts Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. From 7e78e8e93f08c4fc875f53b55f8469eb91264a63 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:42:52 -0500 Subject: [PATCH 27/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index e04ac19c0a..8076595c5e 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -108,7 +108,13 @@ Similarly, Service Accounts address threat exposure concerns by separating the r As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json -curl -XPUT "[https://localhost:9200/_plugins/_security/api/internalusers/admin-extension https://localhost:9200/_plugins/_security/api/internalusers/hello-world" -H 'Content-Type: application/json' -d' +```json +PUT /_plugins/_security/api/internalusers/admin-extension + +{ + "roles": ["all_access"] +} + { "opendistro_security_roles": ["all_access"], "backend_roles": [], From c7d6c79a1d1e944fcd2186b958db47e2ba63a709 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:43:32 -0500 Subject: [PATCH 28/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 8076595c5e..2d6afacdd0 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -108,7 +108,6 @@ Similarly, Service Accounts address threat exposure concerns by separating the r As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json -```json PUT /_plugins/_security/api/internalusers/admin-extension { From e178fa27c2c95fa4523490c1b685fb37a309b38a Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:44:27 -0500 Subject: [PATCH 29/56] Apply suggestions from code review Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 2d6afacdd0..7f7be0d5f0 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -108,10 +108,6 @@ Similarly, Service Accounts address threat exposure concerns by separating the r As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json -PUT /_plugins/_security/api/internalusers/admin-extension - -{ - "roles": ["all_access"] } { From e3c764d6c130e970bf2d71ad677fd247c2cab752 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:44:34 -0500 Subject: [PATCH 30/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 7f7be0d5f0..5ac396d9f9 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -108,7 +108,6 @@ Similarly, Service Accounts address threat exposure concerns by separating the r As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json -} { "opendistro_security_roles": ["all_access"], From db16f8a1bf5b62ffbf306b1541cfc9ebed424857 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:44:56 -0500 Subject: [PATCH 31/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 5ac396d9f9..15f0b96100 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -116,7 +116,6 @@ The following is an example of create a service account with ALL PERMISSIONS for "enabled": "true", "service": "true" } -}' -u "admin:admin" --insecure ``` ## Handling On-Behalf-Of and Service Account Requests From 1f18c7415d3f24bd16c2f1b030be19a1f0dbf9e4 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:47:58 -0500 Subject: [PATCH 32/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 15f0b96100..c635dd857a 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -119,7 +119,7 @@ The following is an example of create a service account with ALL PERMISSIONS for ``` ## Handling On-Behalf-Of and Service Account Requests -While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the `IdentityPlugin` implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. +While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. Extensions acting on their own behalf also make use of the client exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Account for it and provide the associated Service Account token. In the default configuration, the Security Plugin is the `IdentityPlugin` and handles these processes. After OpenSearch receives the Service Account token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Account associated with the extension are operable. In these scenarios, the extension receives the requests from the client, and then forwards the request along with the Service Account token to OpenSearch. OpenSearch further transfers the packages to the Security Plugin where the token is parsed and the request is treated as a traditional request using Basic Authentication in the `InternalAuthenticationBackend`. From c0f22a5eb5da07bc6168c5dd1a630d385a15047c Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:48:19 -0500 Subject: [PATCH 33/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index c635dd857a..da69b68031 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -116,7 +116,6 @@ The following is an example of create a service account with ALL PERMISSIONS for "enabled": "true", "service": "true" } -``` ## Handling On-Behalf-Of and Service Account Requests While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. From 21beb150a74af9b2025b5583df10ca3292718730 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:52:16 -0500 Subject: [PATCH 34/56] Apply suggestions from code review Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index da69b68031..10ee44d8b5 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -109,6 +109,7 @@ As suggested by the name, the boolean flag `service` denotes whether a given int The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json +PUT /_plugins/_security/api/internalusers/admin_service { "opendistro_security_roles": ["all_access"], "backend_roles": [], @@ -116,7 +117,6 @@ The following is an example of create a service account with ALL PERMISSIONS for "enabled": "true", "service": "true" } - ## Handling On-Behalf-Of and Service Account Requests While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. From 663ac2cee8a7856b4c857eb57a4ec8bd147614c9 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:53:15 -0500 Subject: [PATCH 35/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 10ee44d8b5..6412f81a27 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -117,6 +117,7 @@ PUT /_plugins/_security/api/internalusers/admin_service "enabled": "true", "service": "true" } + ## Handling On-Behalf-Of and Service Account Requests While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. From ffe5bfa8e1cba93538740f2cd8438986767c6176 Mon Sep 17 00:00:00 2001 From: Stephen Crawford Date: Tue, 14 Nov 2023 11:23:03 -0500 Subject: [PATCH 36/56] Fix embedded command Signed-off-by: Stephen Crawford --- _security/access-control/authentication-tokens.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 6412f81a27..3ae788d55b 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -108,7 +108,6 @@ Similarly, Service Accounts address threat exposure concerns by separating the r As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json - PUT /_plugins/_security/api/internalusers/admin_service { "opendistro_security_roles": ["all_access"], @@ -117,6 +116,8 @@ PUT /_plugins/_security/api/internalusers/admin_service "enabled": "true", "service": "true" } + ``` +{% include copy-curl.html %} ## Handling On-Behalf-Of and Service Account Requests While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. From b6f1bd8937fa1a82ba9d7f622b940f6922bdc83f Mon Sep 17 00:00:00 2001 From: Stephen Crawford Date: Tue, 14 Nov 2023 11:25:26 -0500 Subject: [PATCH 37/56] Blank lines after headings Signed-off-by: Stephen Crawford --- _security/access-control/authentication-tokens.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 3ae788d55b..bed95ed162 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -13,11 +13,13 @@ redirect_from: The Security plugin allows you to configure two types of authentication tokens: On-Behalf-Of (OBO) tokens and Service Account tokens. ### 1.0 Usage + On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. With on-behalf-of tokens, an extension can interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension-related use cases. ### 2.0 Configuration + In the security config file, the on-behalf-of configuration is located under the dynamic config section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: ``` @@ -33,6 +35,7 @@ config: The default encoding algorithm for the signing of the JWT (JSON Web Token) is HMAC SHA512. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. ### 3.0 Token structure + The payload of an on-behalf-of token must include all standard configurations of a JWT, along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. The on-behalf-of token contains the following claims: @@ -62,6 +65,7 @@ The on-behalf-of token contains the following claims: The OpenSearch Security plugin is responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third-party services. ### 3.0 API endpoint + You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API endpoint on the security plugin in order to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. To access this API endpoint, the request body should contain three API parameters: @@ -89,22 +93,26 @@ While the conversation about the usage of on-behalf-of (OBO) tokens continues, i Service Accounts tokens are the second form of authentication token supported by the Security plugin. ### 1.0 Introduction of Service Accounts + Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. Currently, Service Account only permit operations on system indices associated with the mapped extension. {: .important} ### 2.0 Service Account Background + Before the introduction of Service Accounts, it was not possible for an extension to execute a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User which acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: * Impersonation compromises referential integrity, meaning it is difficult for auditors to identify which requests were executed by an extension or by an operator. A system with referential integrity maintains a transactional record in its audit log. The record provides a clear history of actions taken by various subjects at specific times. When extensions impersonate users for both requests they make on behalf of the operator, and requests they execute on their own, the audit log lacks referential integrity. * Impersonation also makes it impossible to restrict an extension’s permissions beyond those of the user it impersonates. When an extension assumes the roles of the active subject, it copies all of the roles. This includes even those permissions which are uneccessary for executing its intended actions. This practice not only deviates from the principal of least-privileges, but also increases the threat surface area. With each additional permission granted to the Plugin User, the potential impact a misconfigured or malicious extension may have grows. ### 3.0 Service Account Benefit + Service Accounts address the issues listed in 2.0 by defining a separate state in which autonomously executing extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when executing requests on their own behalf. Audit logging can then record when an extension executes on its own—it will make authC/authZ calls against the Service Account—or whether it is executing an action on behalf of the operator and therefore making use of the on-behalf-of tokens. Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard-coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. ### 4.0 API Endpoint + As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. The following is an example of create a service account with ALL PERMISSIONS for your service or extension: ```json From 5b15faa42e96a796f540d5ee3a9bba084f218c85 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 09:24:30 -0500 Subject: [PATCH 38/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index bed95ed162..15bfa4af25 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -14,7 +14,7 @@ The Security plugin allows you to configure two types of authentication tokens: ### 1.0 Usage -On-behalf-of tokens are a special form of JSON Web Token used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes) after which it expires and cannot be used. +On-Behalf-Of tokens are a special form of JSON Web Token (JWT) used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes), after which it expires and cannot be used. With on-behalf-of tokens, an extension can interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension-related use cases. From ee7a69883e7f947dd2a82bd264dd3192c4ce68ae Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 09:24:42 -0500 Subject: [PATCH 39/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 15bfa4af25..16ebb42335 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -16,7 +16,7 @@ The Security plugin allows you to configure two types of authentication tokens: On-Behalf-Of tokens are a special form of JSON Web Token (JWT) used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes), after which it expires and cannot be used. -With on-behalf-of tokens, an extension can interact with the OpenSearch cluster using the same privileges as the initiating user (the reason the tokens are “on-behalf-of”). However, since these tokens do not have any restrictions in place, they also provide services the ability to operate as if they are the original user until token expiration. This implies that this feature can be used more broadly and is not limited to extension-related use cases. +An extension can use an OBO token to interact with an OpenSearch cluster, using the same privileges as the user it represents. This is why these tokens are called "on-behalf-of." Since these tokens are not restricted, they enable services to function as though they are the original user until the token expires. This implies that the feature's applicability extends beyond just extension-related uses cases, allowing for a wider range of uses. ### 2.0 Configuration From f720020939306eb1f78ae3b694c246e73224943e Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 09:24:56 -0500 Subject: [PATCH 40/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 16ebb42335..86080d901d 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -128,7 +128,9 @@ PUT /_plugins/_security/api/internalusers/admin_service {% include copy-curl.html %} ## Handling On-Behalf-Of and Service Account Requests -While both on-behalf-of token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client which is used to connect to the OpenSearch cluster and provides Plugins the ability to execute requests. With the introduction of on-behalf-of tokens and Service Accounts the client is now able to be used to handle requests which will make use of both of these new features. Now, when the client executes a request which requires an extension to use an on-behalf-of token, the first step of handling the request is the forwarding of the request to the Security Plugin. In the Security Plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base where a request to create an on-behalf-of for the target extension using the active user’s identity is created. This request to generate the on-behalf-of token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security Plugin, so the request is returned to the Security Plugin’s implementation of the `TokenManager` interface which generates a new on-behalf-of token for the request. After generating the token, the Security Plugin forwards the request with the on-behalf-of token to the extension. At that point, the extension is then able to call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If instead, the on-behalf-of token does not entail the permissions required for execution of the target action, the a forbidden response is returned to the extension. +While both OBO token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client that is used to connect to the OpenSearch cluster and provides the plugins with the capability to run requests. +With OBO tokens and Service Accounts, the client now is able to be used to handle requests that use both of these features. When the client executes a request that requires an extension to use an OBO token, the first step for handling the request is forwarding the request to the Security plugin. In the Security plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base, where a request to create an OBO token for the target extension using the active user’s identity is created. This request to generate the OBO token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security plugin, so the request is returned to the Security plugin’s implementation of the `TokenManager` interface, which generates a new OBO token for the request. +After generating the token, the Security plugin forwards the request with the OBO token to the extension. At that point, the extension can call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed, and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If the OBO token does not entail the permissions required for initiating the target action, a forbidden response is returned to the extension. Extensions acting on their own behalf also make use of the client exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Account for it and provide the associated Service Account token. In the default configuration, the Security Plugin is the `IdentityPlugin` and handles these processes. After OpenSearch receives the Service Account token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Account associated with the extension are operable. In these scenarios, the extension receives the requests from the client, and then forwards the request along with the Service Account token to OpenSearch. OpenSearch further transfers the packages to the Security Plugin where the token is parsed and the request is treated as a traditional request using Basic Authentication in the `InternalAuthenticationBackend`. From 85752965310a72147bf60c19a3f0fb486767f929 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:04:12 -0500 Subject: [PATCH 41/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 86080d901d..f952c17539 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -20,7 +20,7 @@ An extension can use an OBO token to interact with an OpenSearch cluster, using ### 2.0 Configuration -In the security config file, the on-behalf-of configuration is located under the dynamic config section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: +In the security configuration file, the OBO configuration is located under the dynamic configuration section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: ``` config: From 7a104c37a8d171e91a14a8808aef83cef0e560c7 Mon Sep 17 00:00:00 2001 From: Stephen Crawford Date: Thu, 16 Nov 2023 12:04:54 -0500 Subject: [PATCH 42/56] change Signed-off-by: Stephen Crawford --- _security/access-control/authentication-tokens.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index f952c17539..6ac8f4f2c4 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -8,9 +8,13 @@ redirect_from: - /security-plugin/access-control/authorization-tokens/ --- +Authorization tokens + +The Security plugin allows you to configure two types of authentication tokens: On-Behalf-Of (OBO) tokens and Service Account tokens. + ## On-Behalf-Of authentication -The Security plugin allows you to configure two types of authentication tokens: On-Behalf-Of (OBO) tokens and Service Account tokens. +The following sections describe the use, configuration, structure, and endpoint for OBO tokens. ### 1.0 Usage @@ -20,7 +24,7 @@ An extension can use an OBO token to interact with an OpenSearch cluster, using ### 2.0 Configuration -In the security configuration file, the OBO configuration is located under the dynamic configuration section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: +In the [security `config.yml` file]({{site.url}}{{site.baseurl}}/security/configuration/configuration/), the OBO configuration is located under the dynamic configuration section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: ``` config: From 811922aacb5f3d6645464083eaafe4fd95078baa Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:05:52 -0500 Subject: [PATCH 43/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 6ac8f4f2c4..fc1418e396 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -118,7 +118,7 @@ Similarly, Service Accounts address threat exposure concerns by separating the r ### 4.0 API Endpoint As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. -The following is an example of create a service account with ALL PERMISSIONS for your service or extension: +The following is an example of creating a Service Accounts with `ALL PERMISSIONS` for your service or extension. ```json PUT /_plugins/_security/api/internalusers/admin_service { From fe674d4ba8ad16d08454a168be31b2ad24e7de5e Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:06:08 -0500 Subject: [PATCH 44/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index fc1418e396..1defdf5956 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -36,7 +36,7 @@ config: ... ``` -The default encoding algorithm for the signing of the JWT (JSON Web Token) is HMAC SHA512. Both the signing key and encryption key are Base64 encoded and stored on the file system of the OpenSearch node. The keys should be the same on all hosts, otherwise encryption and decryption operations may fail. Deployment of these keys is managed by the cluster operator. +The default encoding algorithm for signing the JWT is HMAC SHA512. Both the signing key and the encryption key are base64 encoded and stored on the OpenSearch node's file system. The keys should be the same on all hosts. Otherwise, encryption and decryption operations may fail. The keys' deployment is managed by the cluster operator. ### 3.0 Token structure From 705bd90485af4324780eb8ac626da9228a173cf5 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:06:16 -0500 Subject: [PATCH 45/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 1defdf5956..acdd359442 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -131,7 +131,7 @@ PUT /_plugins/_security/api/internalusers/admin_service ``` {% include copy-curl.html %} -## Handling On-Behalf-Of and Service Account Requests +## Handling OBO and Service Accounts requests While both OBO token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client that is used to connect to the OpenSearch cluster and provides the plugins with the capability to run requests. With OBO tokens and Service Accounts, the client now is able to be used to handle requests that use both of these features. When the client executes a request that requires an extension to use an OBO token, the first step for handling the request is forwarding the request to the Security plugin. In the Security plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base, where a request to create an OBO token for the target extension using the active user’s identity is created. This request to generate the OBO token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security plugin, so the request is returned to the Security plugin’s implementation of the `TokenManager` interface, which generates a new OBO token for the request. After generating the token, the Security plugin forwards the request with the OBO token to the extension. At that point, the extension can call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed, and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If the OBO token does not entail the permissions required for initiating the target action, a forbidden response is returned to the extension. From d7210f1719b257c43332de5bc354aba38d150159 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:06:26 -0500 Subject: [PATCH 46/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index acdd359442..3347569a48 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -136,7 +136,8 @@ While both OBO token handling and Service Accounts can be viewed as independent With OBO tokens and Service Accounts, the client now is able to be used to handle requests that use both of these features. When the client executes a request that requires an extension to use an OBO token, the first step for handling the request is forwarding the request to the Security plugin. In the Security plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base, where a request to create an OBO token for the target extension using the active user’s identity is created. This request to generate the OBO token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security plugin, so the request is returned to the Security plugin’s implementation of the `TokenManager` interface, which generates a new OBO token for the request. After generating the token, the Security plugin forwards the request with the OBO token to the extension. At that point, the extension can call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed, and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If the OBO token does not entail the permissions required for initiating the target action, a forbidden response is returned to the extension. -Extensions acting on their own behalf also make use of the client exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Account for it and provide the associated Service Account token. In the default configuration, the Security Plugin is the `IdentityPlugin` and handles these processes. After OpenSearch receives the Service Account token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Account associated with the extension are operable. In these scenarios, the extension receives the requests from the client, and then forwards the request along with the Service Account token to OpenSearch. OpenSearch further transfers the packages to the Security Plugin where the token is parsed and the request is treated as a traditional request using Basic Authentication in the `InternalAuthenticationBackend`. +Extensions acting on their own behalf also use the client that is exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Accounts for it and to provide the associated Service Accounts token. In the default configuration, the Security plugin is the `IdentityPlugin` and handles these processes. +After OpenSearch receives the Service Accounts token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Accounts associated with the extension are operable. In these scenarios, the extension receives the requests from the client and then forwards the request along with the Service Accounts token to OpenSearch. OpenSearch further transfers the packages to the Security plugin, where the token is parsed and the request is treated as a traditional request using "Basic Authentication" in the `InternalAuthenticationBackend`. In both on-behalf-of and Service Account token request flows, the `IdentityPlugin`'s `TokenManager` interface is used by the `IdentityPlugin` to handle the distribution and processing of the tokens. This interface is implemented by the Security Plugin as an `IdentityPlugin` and contains logic for issuing a token which is either an on-behalf-of or Service Account token. From 3e3cd247994daba1967c0bd773fdc2de25249aac Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:06:42 -0500 Subject: [PATCH 47/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 3347569a48..8a1446c0d7 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -42,7 +42,7 @@ The default encoding algorithm for signing the JWT is HMAC SHA512. Both the sign The payload of an on-behalf-of token must include all standard configurations of a JWT, along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. -The on-behalf-of token contains the following claims: +The OBO token contains the following claims: * Issuer (`iss`): OpenSearch Cluster Identifier * It is essential that the issuer is validated as a part of security control measures. This strategy is forward-thinking, particularly in the context of potential multi-tenant scenarios like OpenSearch Serverless, where differing cryptographic keys could be associated with each issuer. By checking the value of issuer, each on-behalf-of token is restricted to its associated issuer. * Issue-at (`iat`): Current time of issuing this token From 027718d9d11fd1f6d1f3d34c2a109f9c189ef34b Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:06:57 -0500 Subject: [PATCH 48/56] Update _security/access-control/authentication-tokens.md Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 8a1446c0d7..8760626dd7 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -40,7 +40,7 @@ The default encoding algorithm for signing the JWT is HMAC SHA512. Both the sign ### 3.0 Token structure -The payload of an on-behalf-of token must include all standard configurations of a JWT, along with encrypted and decrypted roles. Depending on the setting of the "Plugin Backward Compatibility Mode," backend roles should also be incorporated into role claims. It is important to note that the absence of any of these claims will result in a malformed token, failing to meet the required standard for authentication. +The payload of an OBO token must include all standard configurations of a JWT, along with encrypted and decrypted roles. Depending on the Plugin Backward Compatibility Mode setting, backend roles should also be incorporated into role claims. The absence of any of these claims results in a malformed token and fails to meet the required standard for authentication. The OBO token contains the following claims: * Issuer (`iss`): OpenSearch Cluster Identifier From 97d6d58b1fb4e48b216603cc17b23e8377e8bfc5 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:09:23 -0500 Subject: [PATCH 49/56] Apply suggestions from code review Co-authored-by: Melissa Vagi Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- .../access-control/authentication-tokens.md | 68 ++++++++++--------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 8760626dd7..4f900d2e2d 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -44,40 +44,40 @@ The payload of an OBO token must include all standard configurations of a JWT, a The OBO token contains the following claims: * Issuer (`iss`): OpenSearch Cluster Identifier - * It is essential that the issuer is validated as a part of security control measures. This strategy is forward-thinking, particularly in the context of potential multi-tenant scenarios like OpenSearch Serverless, where differing cryptographic keys could be associated with each issuer. By checking the value of issuer, each on-behalf-of token is restricted to its associated issuer. -* Issue-at (`iat`): Current time of issuing this token + * It is essential that the issuer is validated as a part of security control measures. This strategy is forward-thinking, particularly in the context of potential multi-tenant scenarios, such as OpenSearch Serverless, where differing cryptographic keys could be associated with each issuer. By checking the value of issuer, each OBO token is restricted to its associated issuer. +* Issue-at (`iat`): Current time for issuing this token * Used as the reference of the expiration. * Not-before (`nbf`): The earliest point at which the token can be used - * Given that the on-behalf-of token is designed for just-in-time usage, its `nbf` should align with the `iat` (issued-at) time, indicating the moment when the token was created. + * Given that the OBO token is designed for just-in-time usage, its `nbf` should align with the issued-at time (`iat`), indicating the moment when the token was created. * Expiry (`exp`): Expiration time - * Each on-behalf-of token incorporates an expiration mechanism, which is verified upon its receipt. Once a token is issued, it cannot be revoked. Instead, the only token is only invalidated upon its expiration. Furthermore, the generation of on-behalf-of tokens by extensions is subject to dynamic settings. This functionality safeguards the system by preventing the issuance of future tokens under certain conditions. - * The default configuration establishes an expiration time of 300 seconds for on-beahalf-of tokens. Recognizing that different scenarios may necessitate different token durations, we have incorporated the capability for users to personalize this expiration time. At present, the maximum duration that can be assigned to a token is 600 seconds. - * In reference to the current design of the On-Behalf-Of token, it's accurate to say that token revocation isn't a current concern, given its intended just-in-time use and brief lifespan. However, if future adjustments necessitate an extended lifespan for this token, token revocation will be added. This strategy will be adopted to improve and solidify the security measures associated with on-behalf-of token use. -* Subject (`sub`): User Identifier - * Name of the user with which this on-behalf-of token is associated. -* Audience (`aud`): Extension’s unique identifier - * For the extension use case, the aud field is a reference to the specific extension that represents the target service. - * For the REST API use case, the API parameter “service” will let user to specify the target service(s) using this token, and the default value is set to “self-issued“ -* Roles: Security Privilege Evaluation - * Role Security Mode [[source code](https://github.com/opensearch-project/security/blob/main/src/main/java/org/opensearch/security/authtoken/jwt/JwtVendor.java#L151)], this configuration determines the encryption of the roles claim. - * Role Security Mode On (default value) - Roles claim will be encrypted. + * Each OBO token incorporates an expiration mechanism, which is verified upon its receipt. Once a token is issued, it cannot be revoked. Instead, the token is only invalidated upon its expiration. Further, the generation of OBO tokens by extensions is subject to dynamic settings. This functionality safeguards the system by preventing the issuance of future tokens under certain conditions. + * The default configuration establishes an expiration time of 300 seconds for OBO tokens. Recognizing that different scenarios may necessitate different token durations, OpenSearch has the capability for users to personalize this expiration time. The maximum duration that can be assigned to a token is 600 seconds. + * In reference to the OBO token's current design, token revocation isn't a current concern, given its intended just-in-time use and brief lifespan. If, however, future adjustments necessitate an extended lifespan for this token, token revocation will be added. This strategy will be adopted to improve and solidify the security measures associated with OBO token use. +* Subject (`sub`): User identifier + * Name of the user with which this OBO token is associated. +* Audience (`aud`): The extension’s unique identifier + * For the extension use case, the `aud` field is a reference to the specific extension that represents the target service. + * For the REST API use case, the API parameter service enables the specifying of the target service(s) using this token. The default value is set to `self-issued`. +* Roles: Security privilege evaluation + * The Role Security Mode [[source code](https://github.com/opensearch-project/security/blob/main/src/main/java/org/opensearch/security/authtoken/jwt/JwtVendor.java#L151)]: The configuration determines the roles claim encryption. + * Role Security Mode On (default value): Roles claim will be encrypted. * Encrypted mapped roles (`er`) - * Role Security Mode Off - Roles claims will be in plain-text, and both mapped roles and backend roles will be included in the claim [[related discussion](https://github.com/opensearch-project/security/issues/2865)] + * Role Security Mode Off: Roles claims is in plain-text. Both the mapped roles and backend roles are included in the claim [[related discussion](https://github.com/opensearch-project/security/issues/2865)]. * Decrypted mapped roles in plain text (`dr`) * Decrypted backend roles (`br`) -The OpenSearch Security plugin is responsible for handling encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third-party services. +The OpenSearch Security plugin handles the encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third-party services. ### 3.0 API endpoint -You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API endpoint on the security plugin in order to create a short-lived self-issued on-behalf-of token to perform certain actions on behalf of a user. +You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API endpoint on the Security plugin in order to create a short-lived, self-issued OBO token to perform certain actions on the user's behalf. To access this API endpoint, the request body should contain three API parameters: * `description`: This parameter allows the user to articulate the purpose for requesting this token, providing clarity and transparency. -* `service` (optional): This parameter is directed to the audience claim of the on-behalf-of token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to "self-issued". -* `durationSeconds` (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. However, the maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. -The following is an example of requesting an on-behalf-of token with lifespan of 3 mins as user '“admin” for testing purpose: +* `service` (optional): This parameter is directed to the audience claim of the OBO token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to `self-issued`. +* `durationSeconds` (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. The maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. +The following is an example of requesting an OBO token with a lifespan of 3 mins for the user “admin” for testing purposes: ```json POST /_plugins/_security/api/generateonbehalfoftoken { @@ -88,36 +88,38 @@ POST /_plugins/_security/api/generateonbehalfoftoken ``` {% include copy-curl.html %} -### 4.0 Additional Authorization Restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) +### 4.0 Additional authorization restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) -While the conversation about the usage of on-behalf-of (OBO) tokens continues, it is critical to manage certain edge cases. Even though an OBO token can act as a valid Bearer authorization header for any API access, there needs to be certain limitations. For instance, it should be forbidden to use an OBO token to access the API endpoint to issue another OBO token. Similarly, using an OBO token to access the reset password API in order to modify a user's authentication information should be disallowed. These preventive measures are necessary to uphold the integrity and security of the system. +While the conversation about the usage of OBO tokens continues, it is critical to manage certain edge cases. Even though an OBO token can act as a valid Bearer authorization header for any API access, certain limitations are needed. For instance, using an OBO token to access the API endpoint to issue another OBO token should be forbidden. Similarly, using an OBO token to access the reset password API in order to modify a user's authentication information should be disallowed. These preventive measures are necessary to uphold the system's integrity and security. ## Service Accounts Service Accounts tokens are the second form of authentication token supported by the Security plugin. -### 1.0 Introduction of Service Accounts +### 1.0 Introduction -Service Accounts are a new authC/authZ path where extensions can execute requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to a Service Account grant the associated extension the authorization to execute any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. +Service Accounts are a new authC/authZ path where extensions can run requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to Service Accounts grant the associated extension the authorization to run any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. -Currently, Service Account only permit operations on system indices associated with the mapped extension. +Currently, Service Accounts only permit operations on system indices associated with the mapped extension. {: .important} -### 2.0 Service Account Background +### 2.0 Background -Before the introduction of Service Accounts, it was not possible for an extension to execute a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User which acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: -* Impersonation compromises referential integrity, meaning it is difficult for auditors to identify which requests were executed by an extension or by an operator. A system with referential integrity maintains a transactional record in its audit log. The record provides a clear history of actions taken by various subjects at specific times. When extensions impersonate users for both requests they make on behalf of the operator, and requests they execute on their own, the audit log lacks referential integrity. +Before the introduction of Service Accounts, it was not possible for an extension to execute a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User that acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: +* Impersonation compromises referential integrity, meaning it is difficult for auditors to identify which requests were executed by an extension or by an operator. A system with referential integrity maintains a transactional record in its audit log. The record provides a clear history of actions taken by various subjects at specific times. When extensions impersonate users for both requests they make on behalf of the operator and requests they execute on their own, the audit log lacks referential integrity. * Impersonation also makes it impossible to restrict an extension’s permissions beyond those of the user it impersonates. When an extension assumes the roles of the active subject, it copies all of the roles. This includes even those permissions which are uneccessary for executing its intended actions. This practice not only deviates from the principal of least-privileges, but also increases the threat surface area. With each additional permission granted to the Plugin User, the potential impact a misconfigured or malicious extension may have grows. -### 3.0 Service Account Benefit +### 3.0 Benefits -Service Accounts address the issues listed in 2.0 by defining a separate state in which autonomously executing extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when executing requests on their own behalf. Audit logging can then record when an extension executes on its own—it will make authC/authZ calls against the Service Account—or whether it is executing an action on behalf of the operator and therefore making use of the on-behalf-of tokens. +Service Accounts address the issues described in the Background section by defining a separate state in which autonomously executing extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when executing requests on their own behalf. +Audit logging can then record when an extension runs on its own—it makes authC/authZ calls against the Service Accounts—or whether it is running an action on behalf of the operator and therefore making use of the OBO tokens. -Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard-coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator, but instead have their own privileges listed in the Service Account. The roles associated with a Service Account can therefore, be as a restrictive as possible in alignment with the principle of least-privileges. In order to avoid providing extensions overly-permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hopes to execute. +Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard-coded user (such as those in the `internal_users.yml` file). +Service Accounts will not assume the roles of the operator but instead have their own privileges listed in the Service Accounts. The roles associated with Service Accounts can therefore be as a restrictive as possible in alignment with the principle of least-privileges. To avoid providing extensions with overly permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hope to run. ### 4.0 API Endpoint -As suggested by the name, the boolean flag `service` denotes whether a given internal user account is Service Account. If an account is not a Service Account, then any attempts to generate an associated auth token for the account will fail. Similarly, the `enabled` field dictates when a Service Account can be used by an extensions to perform operations. If a Service Account is not `enabled`, attempts to fetch its auth token will be blocked and the Service Account will be unable to execute requests on its own behalf using a previously issued auth token. +As suggested by the name, the Boolean flag `service` denotes whether a given internal user account is a Service Accounts. If an account is not a Service Accounts, then any attempts to generate an associated authorization token for the account will fail. Similarly, the `enabled` field determines when a Service Accounts can be used by an extension to perform operations. If a Service Accounts is not `enabled`, attempts to fetch its authorization token will be blocked and the Service Accounts will be unable to run requests on its own behalf using a previously issued auth token. The following is an example of creating a Service Accounts with `ALL PERMISSIONS` for your service or extension. ```json PUT /_plugins/_security/api/internalusers/admin_service @@ -139,6 +141,6 @@ After generating the token, the Security plugin forwards the request with the OB Extensions acting on their own behalf also use the client that is exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Accounts for it and to provide the associated Service Accounts token. In the default configuration, the Security plugin is the `IdentityPlugin` and handles these processes. After OpenSearch receives the Service Accounts token, it forwards that token to the associated extension. After the extension has received its token, requests by the client to make use of the Service Accounts associated with the extension are operable. In these scenarios, the extension receives the requests from the client and then forwards the request along with the Service Accounts token to OpenSearch. OpenSearch further transfers the packages to the Security plugin, where the token is parsed and the request is treated as a traditional request using "Basic Authentication" in the `InternalAuthenticationBackend`. -In both on-behalf-of and Service Account token request flows, the `IdentityPlugin`'s `TokenManager` interface is used by the `IdentityPlugin` to handle the distribution and processing of the tokens. This interface is implemented by the Security Plugin as an `IdentityPlugin` and contains logic for issuing a token which is either an on-behalf-of or Service Account token. +In both OBO and Service Accounts token request flows, the `TokenManager` interface for the `IdentityPlugin` is used by the `IdentityPlugin` to handle the tokens' distribution and processing. This interface is implemented by the Security plugin as an `IdentityPlugin` and contains logic for issuing a token that is either an OBO or Service Accounts token. From 580b4d985a8e01da891dede7daa7f9d589ec1de0 Mon Sep 17 00:00:00 2001 From: Stephen Crawford Date: Thu, 16 Nov 2023 12:13:29 -0500 Subject: [PATCH 50/56] Style guidelines Signed-off-by: Stephen Crawford --- .../access-control/authentication-tokens.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 4f900d2e2d..5d01dbdc91 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -16,13 +16,13 @@ The Security plugin allows you to configure two types of authentication tokens: The following sections describe the use, configuration, structure, and endpoint for OBO tokens. -### 1.0 Usage +### Usage On-Behalf-Of tokens are a special form of JSON Web Token (JWT) used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes), after which it expires and cannot be used. An extension can use an OBO token to interact with an OpenSearch cluster, using the same privileges as the user it represents. This is why these tokens are called "on-behalf-of." Since these tokens are not restricted, they enable services to function as though they are the original user until the token expires. This implies that the feature's applicability extends beyond just extension-related uses cases, allowing for a wider range of uses. -### 2.0 Configuration +### Configuration In the [security `config.yml` file]({{site.url}}{{site.baseurl}}/security/configuration/configuration/), the OBO configuration is located under the dynamic configuration section. It contains the signing key for the token signature and the encryption key for the token payload (role information) decryption: @@ -38,12 +38,12 @@ config: The default encoding algorithm for signing the JWT is HMAC SHA512. Both the signing key and the encryption key are base64 encoded and stored on the OpenSearch node's file system. The keys should be the same on all hosts. Otherwise, encryption and decryption operations may fail. The keys' deployment is managed by the cluster operator. -### 3.0 Token structure +### Token structure The payload of an OBO token must include all standard configurations of a JWT, along with encrypted and decrypted roles. Depending on the Plugin Backward Compatibility Mode setting, backend roles should also be incorporated into role claims. The absence of any of these claims results in a malformed token and fails to meet the required standard for authentication. The OBO token contains the following claims: -* Issuer (`iss`): OpenSearch Cluster Identifier +* Issuer (`iss`): OpenSearch cluster identifier * It is essential that the issuer is validated as a part of security control measures. This strategy is forward-thinking, particularly in the context of potential multi-tenant scenarios, such as OpenSearch Serverless, where differing cryptographic keys could be associated with each issuer. By checking the value of issuer, each OBO token is restricted to its associated issuer. * Issue-at (`iat`): Current time for issuing this token * Used as the reference of the expiration. @@ -68,7 +68,7 @@ The OBO token contains the following claims: The OpenSearch Security plugin handles the encryption and decryption processes. This approach ensures the protection of user information, even when traversing the trust boundary between OpenSearch and any third-party services. -### 3.0 API endpoint +### API endpoint You can access the `POST /_plugins/_security/api/generateonbehalfoftoken` API endpoint on the Security plugin in order to create a short-lived, self-issued OBO token to perform certain actions on the user's behalf. @@ -88,7 +88,7 @@ POST /_plugins/_security/api/generateonbehalfoftoken ``` {% include copy-curl.html %} -### 4.0 Additional authorization restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) +### Additional authorization restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) While the conversation about the usage of OBO tokens continues, it is critical to manage certain edge cases. Even though an OBO token can act as a valid Bearer authorization header for any API access, certain limitations are needed. For instance, using an OBO token to access the API endpoint to issue another OBO token should be forbidden. Similarly, using an OBO token to access the reset password API in order to modify a user's authentication information should be disallowed. These preventive measures are necessary to uphold the system's integrity and security. @@ -96,28 +96,28 @@ While the conversation about the usage of OBO tokens continues, it is critical t Service Accounts tokens are the second form of authentication token supported by the Security plugin. -### 1.0 Introduction +### Introduction Service Accounts are a new authC/authZ path where extensions can run requests without assuming the role(s) of the active user. Service Accounts are a special type of principal associated with each extension and have a set of permissions. The permissions assigned to Service Accounts grant the associated extension the authorization to run any of the mapped operations without needing to assume the roles of the active user or stash the user’s role(s) in the ephemeral user context. Currently, Service Accounts only permit operations on system indices associated with the mapped extension. {: .important} -### 2.0 Background +### Background -Before the introduction of Service Accounts, it was not possible for an extension to execute a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User that acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: -* Impersonation compromises referential integrity, meaning it is difficult for auditors to identify which requests were executed by an extension or by an operator. A system with referential integrity maintains a transactional record in its audit log. The record provides a clear history of actions taken by various subjects at specific times. When extensions impersonate users for both requests they make on behalf of the operator and requests they execute on their own, the audit log lacks referential integrity. -* Impersonation also makes it impossible to restrict an extension’s permissions beyond those of the user it impersonates. When an extension assumes the roles of the active subject, it copies all of the roles. This includes even those permissions which are uneccessary for executing its intended actions. This practice not only deviates from the principal of least-privileges, but also increases the threat surface area. With each additional permission granted to the Plugin User, the potential impact a misconfigured or malicious extension may have grows. +Before the introduction of Service Accounts, it was not possible for an extension to service a request without assuming the roles of the active user. Instead, when a request is processed, an ephemeral “Plugin User” was created. The Plugin User then assumed all the permissions of the currently authenticated operator (human user). The result was a Plugin User that acted on the extension’s behalf but had all of the privileges of the operator. In this way, the previous model can be said to have had extensions “impersonate” the operator. This impersonation approach lead to two main issues: +* Impersonation compromises referential integrity, meaning it is difficult for auditors to identify which requests were run by an extension or by an operator. A system with referential integrity maintains a transactional record in its audit log. The record provides a clear history of actions taken by various subjects at specific times. When extensions impersonate users for both requests they make on behalf of the operator and requests they send on their own, the audit log lacks referential integrity. +* Impersonation also makes it impossible to restrict an extension’s permissions beyond those of the user it impersonates. When an extension assumes the roles of the active subject, it copies all of the roles. This includes even those permissions which are uneccessary for completing its intended actions. This practice not only deviates from the principal of least-privileges, but also increases the threat surface area. With each additional permission granted to the Plugin User, the potential impact a misconfigured or malicious extension may have grows. -### 3.0 Benefits +### Benefits -Service Accounts address the issues described in the Background section by defining a separate state in which autonomously executing extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when executing requests on their own behalf. +Service Accounts address the issues described in the Background section by defining a separate state in which autonomously operating extensions run. Service Accounts maintain referential integrity by introducing a distinct state in which extensions run when sending requests on their own behalf. Audit logging can then record when an extension runs on its own—it makes authC/authZ calls against the Service Accounts—or whether it is running an action on behalf of the operator and therefore making use of the OBO tokens. Similarly, Service Accounts address threat exposure concerns by separating the roles an extension assumes from those of the operator or a generic hard-coded user (such as those in the `internal_users.yml` file). Service Accounts will not assume the roles of the operator but instead have their own privileges listed in the Service Accounts. The roles associated with Service Accounts can therefore be as a restrictive as possible in alignment with the principle of least-privileges. To avoid providing extensions with overly permissive service accounts, extension authors should have a strong understanding of what types of operations their extensions hope to run. -### 4.0 API Endpoint +### API Endpoint As suggested by the name, the Boolean flag `service` denotes whether a given internal user account is a Service Accounts. If an account is not a Service Accounts, then any attempts to generate an associated authorization token for the account will fail. Similarly, the `enabled` field determines when a Service Accounts can be used by an extension to perform operations. If a Service Accounts is not `enabled`, attempts to fetch its authorization token will be blocked and the Service Accounts will be unable to run requests on its own behalf using a previously issued auth token. The following is an example of creating a Service Accounts with `ALL PERMISSIONS` for your service or extension. @@ -135,7 +135,7 @@ PUT /_plugins/_security/api/internalusers/admin_service ## Handling OBO and Service Accounts requests While both OBO token handling and Service Accounts can be viewed as independent features, the most significant benefits are realized when coupled. Specifically, OpenSearch exposes a client that is used to connect to the OpenSearch cluster and provides the plugins with the capability to run requests. -With OBO tokens and Service Accounts, the client now is able to be used to handle requests that use both of these features. When the client executes a request that requires an extension to use an OBO token, the first step for handling the request is forwarding the request to the Security plugin. In the Security plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base, where a request to create an OBO token for the target extension using the active user’s identity is created. This request to generate the OBO token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security plugin, so the request is returned to the Security plugin’s implementation of the `TokenManager` interface, which generates a new OBO token for the request. +With OBO tokens and Service Accounts, the client now is able to be used to handle requests that use both of these features. When the client makes a request that requires an extension to use an OBO token, the first step for handling the request is forwarding the request to the Security plugin. In the Security plugin, the request is authenticated and authorized against the active user. If the active user is permitted, the request returns to OpenSearch’s core code base, where a request to create an OBO token for the target extension using the active user’s identity is created. This request to generate the OBO token is then handled by the _`IdentityPlugin`_ implementation. In the standard scenario this is the Security plugin, so the request is returned to the Security plugin’s implementation of the `TokenManager` interface, which generates a new OBO token for the request. After generating the token, the Security plugin forwards the request with the OBO token to the extension. At that point, the extension can call OpenSearch’s REST methods with the token. The permissions associated with the token will then be evaluated for the authorization of the request. If the token conveys the permissions required for the operation, the action will be performed, and the response will be sent back to the extension. After processing OpenSearch’s response, the extension will forward its own handling of the response to the client. If the OBO token does not entail the permissions required for initiating the target action, a forbidden response is returned to the extension. Extensions acting on their own behalf also use the client that is exposed by OpenSearch. When an extension is first initialized in OpenSearch, the `IdentityPlugin` is triggered to create a new Service Accounts for it and to provide the associated Service Accounts token. In the default configuration, the Security plugin is the `IdentityPlugin` and handles these processes. From 46a15ff92f727515d1551f93f39513d8dfc49ac2 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:14:52 -0500 Subject: [PATCH 51/56] Update _security/access-control/authentication-tokens.md Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 5d01dbdc91..d7fc02067c 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -131,6 +131,7 @@ PUT /_plugins/_security/api/internalusers/admin_service "service": "true" } ``` + {% include copy-curl.html %} ## Handling OBO and Service Accounts requests From f62c004e4ed69a2445a771bd8dbbc3279b4a0f49 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Thu, 16 Nov 2023 12:25:53 -0500 Subject: [PATCH 52/56] Apply suggestions from code review Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index d7fc02067c..ab699bd10a 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -20,7 +20,7 @@ The following sections describe the use, configuration, structure, and endpoint On-Behalf-Of tokens are a special form of JSON Web Token (JWT) used for managing authentication requests between a user's client and an extension. These tokens operate "just-in-time," meaning that a token is issued immediately before it is required for authentication. A token will have a configurable window of validity (with a maximum duration of five minutes), after which it expires and cannot be used. -An extension can use an OBO token to interact with an OpenSearch cluster, using the same privileges as the user it represents. This is why these tokens are called "on-behalf-of." Since these tokens are not restricted, they enable services to function as though they are the original user until the token expires. This implies that the feature's applicability extends beyond just extension-related uses cases, allowing for a wider range of uses. +An extension can use an OBO token to interact with an OpenSearch cluster, using the same privileges as the user it represents. This is why these tokens are called "on-behalf-of." Since these tokens are not restricted, they enable services to function as though they are the original user until the token expires. This implies that the feature's applicability extends beyond only extension-related uses cases, allowing for a wider range of uses. ### Configuration From edd48d1755b392d1639579f923269123919c9eba Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 28 Nov 2023 11:59:53 -0500 Subject: [PATCH 53/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index ab699bd10a..83b9d7a4b1 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -8,7 +8,7 @@ redirect_from: - /security-plugin/access-control/authorization-tokens/ --- -Authorization tokens +# Authorization tokens The Security plugin allows you to configure two types of authentication tokens: On-Behalf-Of (OBO) tokens and Service Account tokens. From c3e2c5ba899a914cfcfcc9ccd430d51db2a66316 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 28 Nov 2023 12:00:02 -0500 Subject: [PATCH 54/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 83b9d7a4b1..e57a4563f7 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -92,6 +92,8 @@ POST /_plugins/_security/api/generateonbehalfoftoken While the conversation about the usage of OBO tokens continues, it is critical to manage certain edge cases. Even though an OBO token can act as a valid Bearer authorization header for any API access, certain limitations are needed. For instance, using an OBO token to access the API endpoint to issue another OBO token should be forbidden. Similarly, using an OBO token to access the reset password API in order to modify a user's authentication information should be disallowed. These preventive measures are necessary to uphold the system's integrity and security. +For more information, see the [related discussion](https://github.com/opensearch-project/security/issues/2891). + ## Service Accounts Service Accounts tokens are the second form of authentication token supported by the Security plugin. From 0476791b5b578a5ec7c4581e2115ad0db033b5f3 Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 28 Nov 2023 12:00:09 -0500 Subject: [PATCH 55/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index e57a4563f7..8d509aecac 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -88,7 +88,7 @@ POST /_plugins/_security/api/generateonbehalfoftoken ``` {% include copy-curl.html %} -### Additional authorization restriction ([related discussion](https://github.com/opensearch-project/security/issues/2891)) +### Additional authorization restriction While the conversation about the usage of OBO tokens continues, it is critical to manage certain edge cases. Even though an OBO token can act as a valid Bearer authorization header for any API access, certain limitations are needed. For instance, using an OBO token to access the API endpoint to issue another OBO token should be forbidden. Similarly, using an OBO token to access the reset password API in order to modify a user's authentication information should be disallowed. These preventive measures are necessary to uphold the system's integrity and security. From 26d20eb0be44071af5eaa74e942fb1f63478ccbd Mon Sep 17 00:00:00 2001 From: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Date: Tue, 28 Nov 2023 12:00:19 -0500 Subject: [PATCH 56/56] Update _security/access-control/authentication-tokens.md Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> --- _security/access-control/authentication-tokens.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_security/access-control/authentication-tokens.md b/_security/access-control/authentication-tokens.md index 8d509aecac..4b91da20c1 100644 --- a/_security/access-control/authentication-tokens.md +++ b/_security/access-control/authentication-tokens.md @@ -78,6 +78,7 @@ To access this API endpoint, the request body should contain three API parameter * `service` (optional): This parameter is directed to the audience claim of the OBO token. It offers users the opportunity to designate the target service for which they intend to use the token. Although this is an optional parameter, if not specified, the default value is set to `self-issued`. * `durationSeconds` (optional): This parameter allows users to customize the token's expiration time according to its anticipated usage. The maximum duration is capped at 600 seconds to maintain security. If not specified, the default duration is set to 300 seconds. The following is an example of requesting an OBO token with a lifespan of 3 mins for the user “admin” for testing purposes: + ```json POST /_plugins/_security/api/generateonbehalfoftoken {