[DOC] Add documentation for OnBehalfOf Authentication

[RyanL1997]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Description of the Feature

the security team has opted to develop an on-behalf-of Json web token for managing authentication requests between the user's client and the extension just in time. For the initial extensions design, these tokens will allow the extension to interact with the OpenSearch cluster using the same privileges as the initiating user, that’s the reason it is named as “on-behalf-of”. However, since this token doesn’t have any restrictions in place, it also has the capability of letting a service operate as if they are the original user for some window of time. Which means this generic feature is not limited extension related use cases..

For the most of the scenarios, this obo token will be used just-in-time which means that the token is issued just before it is needed for usage. The token will have a configurable short time window of validity after which it is expired and no longer good for use. If the extension REST handler finished quickly, the token may still be valid after the request is done. If the extension REST handler takes a long time then there is a risk that the token will expire before the request has been fully handled. There may need to be a mechanism in place to refresh a token or have certain handlers be able to obtain tokens with a longer window of validity, for example I think 5 minutes is reasonable and most handlers should be able to handle a request in a short period of time.

Generic Usage vs. Extension Project

Just-in-time UsageFor extensions project, the security team has opted to develop an on-behalf-of Json web token for managing authentication requests between the user's client and the extension just in time. For the initial extensions design, these tokens will allow the extension to interact with the OpenSearch cluster using the same privileges as the initiating user, that’s the reason it is named as “on-behalf-of”. However, since this token doesn’t have any restrictions in place, it also has the capability of letting a service operate as if they are the original user for some window of time. Which means this generic feature is not limited extension related use cases..

For the most of the scenarios, this obo token will be used just-in-time which means that the token is issued just before it is needed for usage. The token will have a configurable short time window of validity after which it is expired and no longer good for use. If the extension REST handler finished quickly, the token may still be valid after the request is done. If the extension REST handler takes a long time then there is a risk that the token will expire before the request has been fully handled. There may need to be a mechanism in place to refresh a token or have certain handlers be able to obtain tokens with a longer window of validity, for example I think 5 minutes is reasonable and most handlers should be able to handle a request in a short period of time.

Token’s Payload

Issuer (iss): OpenSearch Cluster Identifier
Issue-at (iat): Current time of issuing this token
Expiry (exp): Expiration time
Subject (sub): User ID
Audience (aud): Extension’s unique identifier
Roles: Security Privilege Evaluation

Roles in OBO's Payload

Plugin Backward Compatibility Mode (BWC Mode)

BWC Mode OFF (default):
Encrypted roles (er)
BWC Mode ON:
Decrypted roles in plain-text (dr)
Decrypted backend roles in plain-text (dbr)

Configuration in Config.yml

on_behalf_of:
    signing_key: xxxxxxxxxx
    encryption_key: xxxxxxxx

References

• [META] On-Behalf-Of Authentication security#2573
• [Feature/Extensions] Include backend roles in on-behalf-of token in CreateOnBehalfOfTokenAction security#2865

[cwillum]

@RyanL1997 A big thanks for adding this issue, and especially for the thoroughly detailed information on the feature.

[cwillum]

Pausing this for 2.9. If it doesn't get fresh attention between release cycles, it will be an issue for 2.10.

[hdhalter]

@RyanL1997 - can you please add this to the roadmap? Thanks.

[peternied]

@cwillum This is not going to make it for 2.10, moving to 2.11 - sorry for the shuffle.

CC: @davidlago @hdhalter

[RyanL1997]

Hi @cwillum and @hdhalter, thanks for the following up. This issue is a bit outdated and we are preparing a documentation guidance for both service accounts + obo on opensearch-project/security#3290. Me and @scrawfor99 will update everything in the comment section of that issue and we will let you know when everything is ready.

[RyanL1997]

Hi @hdhalter, just a friendly reminder that our documentation guidance is ready. Please feel free to contact me if you guys have some questions.

[peternied]

Note; we need to make sure we are consistent with the casing/naming of the feature it is my understanding it is OnBehalfOf @RyanL1997 if you agree can you see about making sure this is consistent?

[hdhalter]

This has been moved to 2.12 as per Jialing Liang.