[META] On-Behalf-Of Authentication

[RyanL1997]

Description

When security is installed, extensions will need an auth token in order to interact with the OpenSearch cluster. This auth token will be in the form of a JWT. Extensions are a replacement for plugins, so any information from a user that plugins utilize today should be contained as a claim in the JWT sent to an extension.

Example header + payload:

Header:
{"alg":"HS512"}

Payload:
{
  "iss": "<cluster_name>",
  "iat":1676908684,
  "exp":1676908744,
  "sub":"<principal_identifier_token>",
  "er":"<encrypted_mapped_roles>", # r for roles
  "br": "<encrypted_backend_roles>", # br for backend_roles
  "aud": "extension/{extensionUniqueId}"
}

Useful reference class to see how JWTs are generated within the security plugin on successful SAML authentication: https://github.com/opensearch-project/security/blob/main/src/main/java/com/amazon/dlic/auth/http/saml/AuthTokenProcessorHandler.java

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.

For the initial implementation, the JWTs can be signed with an HMAC 512 hash by default. If any encryption is performed, then the extension will require a mechanism for decrypting the JWE to view the payload of the JWT. The signing key should be configured in the security configuration. Maybe in the config.dynamic portion of config.yml?

Design

• JWT vs JWE: [Question] What capabilities should a token that is passed to an extension have? Should it be a JWT? #2545
• [Security/Extension] JWT Vendor for extensions #2567
• [Security/Extension] Role encryption/decryption #2620
• [Extension] Authentication Backend for JIT Token Validation #2619
  • [Security/Extension] Extension Authentication Backend #2672
• [Extensions] Create dynamic configuration section in config.yml for extensions #2615
  • Extensions config for JWT signing/encryption key #2671
  • [Feature/Extension] Add oboauthcbackend registry and set up e2e endpoint testing flow #2857
• [Question] Host Mapping of Create OBO Token Endpoint #3000
• [Feature/Extensions] Include backend roles in on-behalf-of token in CreateOnBehalfOfTokenAction #2865
• Determine how auth tokens are forwarded to Extensions #2764

Implementation

• [Feature/Extension] Add configuration of disable OBO #3047
• [FEATURE] Handle the edge cases of On-behalf-of Authentication #2891
  • [Feature/Extension] Restrict OBO token's usage for certain endpoints #3008
• [Feature/Extension] OBO Authenticator should inspect the issuer field and make sure it matches the current cluster #3102
  • [Feature/Extension] Add cluster id check for OBO Authenticator #3117
• [Extension] Extend the Integration Test Cases of On-Behalf-Of Authentication Backend #2707

Integration

• [Spike] Work pending to merge Feature/Extensions into Main #2945
  • OnBehalfOf authenticator and token generator #3179
• Issue and ferry a Service Account Token to an Extension on bootstrap #3176
• [Extensions] Add extensions/extensions.yml setting to enable backward compatible plugin mode for extensions #2616

Release Criteria

• OnBehalfOf tokens internal security review process + App Sec signoff #3162
• [Documentation] Documentation guidance for Service Accounts + OnBehalfOf Authentication #3290
• Switch JWT library implementations #3267
• [Extension] Extend the Integration Test Cases of On-Behalf-Of Authentication Backend #2707
• [Feature/Extension] Add permission for access create OBO Token endpoint. #3177
• [Feature/Extension] 100% Code coverage of OBO Authenticator and Jwt Vendor #3101
• Review documentation needs (including Extensions dev guide) #3225
• [Enhancement] Generate On-Behalf-Of Token endpoint should have input check for request body #3558
• Backport On-Behalf-Of Authentication into 2.x branch #3555

Follow-up

• [Security for Extensions] Consume access tokens passed from core and utilize in REST Clients opensearch-sdk-java#887
  • Use auth tokens passed from core and introduce extension and user REST clients opensearch-sdk-java#892
• [FEATURE/Extension] Audit log entry for OBO token generation #3098
• Audit log entry requirements for OBO tokens #3202
• [Enhancement] Set up a Util class for OBO Authenticator for key checks and endpoints checks #3238

[cwperks]

Another useful snippet for this is: PrivilegesEvaluator#L198-L210

private void setUserInfoInThreadContext(User user, Set<String> mappedRoles) {
    if (threadContext.getTransient(OPENDISTRO_SECURITY_USER_INFO_THREAD_CONTEXT) == null) {
        StringJoiner joiner = new StringJoiner("|");
        joiner.add(user.getName());
        joiner.add(String.join(",", user.getRoles()));
        joiner.add(String.join(",", Sets.union(user.getSecurityRoles(), mappedRoles)));
        String requestedTenant = user.getRequestedTenant();
        if (!Strings.isNullOrEmpty(requestedTenant)) {
            joiner.add(requestedTenant);
        }
        threadContext.putTransient(OPENDISTRO_SECURITY_USER_INFO_THREAD_CONTEXT, joiner.toString());
    }
}

This is the information currently read in by common-utils and parsed into the common-utils User object inside of plugins.

[cwperks]

mappedRoles are:

1. Direct roles mappings of a user to an OpenSearch role

union

2. Backend role resolution - Backend roles resolve to OpenSearch roles via roles_mapping and mapRoles is where the resolution takes place

union

3. Host resolution - There is a feature in roles_mappings to map requests originating from ip addresses/hostnames to opensearch roles

There is also a concept of and_Backend_Roles which I am currently unsure of their usage.

This function inside of ConfigModel[V6|V7] is where the mapping takes place: ConfigModelV7#L1206-L1269

Edit: Just figured out the concept of and_backend_roles. The user must have all of the backend roles in that list to be mapped to the roles. Note: This could be used in conjunction with backend_roles, but the lists should not be overlapping at all.

[cwperks]

@peternied For on-behalf-of tokens its important that the roles in the token refer to the mapped roles of the user which corresponds to the same mappedRoles in the PrivilegesEvaluator here. The mapped roles are ultimately what is used to evaluate privileges and in order to accurately compute the mapped roles the IP Address of the called is required which would only be available in the node that receives the REST Request and issues an on-behalf-of token.

For the Create Token endpoint the handler for the endpoint should likewise call mapRoles so that it has access to the correct caller's information when computing the mapped roles to embed in the token.

As we were scoping out work for extensions we identified that many plugins rely on backend roles and one way of communicating backend roles to an extension is through a claim in the token. While it may not be necessarily required to have backend_roles as a claim in an on-behalf-of token, if they are to be used for extensions then that is the chosen mechanism for communicating that data to an extension.

[cwperks]

Created an issue to track the work to add backend roles to the Create obo token endpoint: #2865

I included the change in this branch: https://github.com/RyanL1997/security/compare/add-oboauthcbackend-registry...cwperks:security:add-oboauthcbackend-registry-security-roles?expand=1