Introduce API Tokens with `cluster_permissions` and `index_permissions` directly associated with the token #5443

cwperks · 2025-06-25T17:56:21Z

Description

Re-basing #5225 with latest changes from main.

This PR creates a new capability in the security plugin where users can issue tokens and associate permissions directly with the token.

Currently this is limited to security admins.

What is novel about this PR is that we can associated permissions directly with the token instead of OBO tokens which contain a claim with the user's roles that the OBO authenticator uses for authz. With API Tokens an admin can request that the token is scoped down from their own permissions to give the token exactly the permissions it needs. For instance, if the admin only wants the token to have search permissions on a single index, then that can be configured and the token will be unable to perform any other action.

This is a key building block to be able to deprecate and replace Roles Injection which is the current practice for how plugins ensure that tasks or jobs that run asynchronously run with the same restrictions as the user that created the job. Instead, I envision that we require users to issue tokens scoped to exactly the needs for the job to ensure the job runs with only the permissions it needs and no more (principal of least privilege)

I'll update this PR Description with details about new REST APIs with example request and response.

Category (Enhancement, New feature, Bug fix, Test fix, Refactoring, Maintenance, Documentation)

Enhancement

Issues Resolved

Partially resolves #4009, but limited to security admins in initial release

Check List

New functionality includes testing
New functionality has been documented
New Roles/Permissions have a corresponding security dashboards plugin PR
API changes companion pull request created
Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

…4921) Signed-off-by: Derek Ho <[email protected]>

…ect#4967) Signed-off-by: Derek Ho <[email protected]>

Signed-off-by: Derek Ho <[email protected]>

…00 tokens outstanding (opensearch-project#5147) Signed-off-by: Derek Ho <[email protected]>

Signed-off-by: Craig Perkins <[email protected]>

codecov · 2025-06-25T19:51:51Z

Codecov Report

Attention: Patch coverage is 72.13376% with 175 lines in your changes missing coverage. Please review.

Project coverage is 72.34%. Comparing base (a670d4c) to head (dad7551).

Files with missing lines	Patch %	Lines
...arch/security/action/apitokens/ApiTokenAction.java	58.43%	61 Missing and 8 partials ⚠️
...pensearch/security/http/ApiTokenAuthenticator.java	65.38%	17 Missing and 10 partials ⚠️
.../security/action/apitokens/ApiTokenRepository.java	81.53%	10 Missing and 2 partials ⚠️
...urity/action/apitokens/ApiTokenUpdateResponse.java	14.28%	12 Missing ⚠️
...ction/apitokens/TransportApiTokenUpdateAction.java	57.69%	11 Missing ⚠️
...ecurity/action/apitokens/ApiTokenIndexHandler.java	82.75%	10 Missing ⚠️
...opensearch/security/action/apitokens/ApiToken.java	91.30%	2 Missing and 6 partials ⚠️
...search/security/identity/SecurityTokenManager.java	75.00%	4 Missing and 2 partials ⚠️
...ecurity/authtoken/jwt/ExpiringBearerAuthToken.java	0.00%	5 Missing ⚠️
...curity/action/apitokens/ApiTokenUpdateRequest.java	33.33%	4 Missing ⚠️
... and 7 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5443      +/-   ##
==========================================
- Coverage   72.36%   72.34%   -0.02%     
==========================================
  Files         395      408      +13     
  Lines       24317    24933     +616     
  Branches     3713     3779      +66     
==========================================
+ Hits        17597    18039     +442     
- Misses       4892     5033     +141     
- Partials     1828     1861      +33

Files with missing lines	Coverage Δ
.../opensearch/security/OpenSearchSecurityPlugin.java	`84.01% <100.00%> (+0.14%)`	⬆️
...ecurity/action/apitokens/ApiTokenUpdateAction.java	`100.00% <100.00%> (ø)`
...rity/authtoken/jwt/claims/ApiJwtClaimsBuilder.java	`100.00% <100.00%> (ø)`
...ensearch/security/compliance/ComplianceConfig.java	`89.17% <100.00%> (-0.58%)`	⬇️
...rg/opensearch/security/dlic/rest/api/Endpoint.java	`100.00% <100.00%> (ø)`
...dlic/rest/api/RestApiAdminPrivilegesEvaluator.java	`73.07% <100.00%> (+0.52%)`	⬆️
...ch/security/securityconf/DynamicConfigFactory.java	`64.70% <100.00%> (+0.23%)`	⬆️
...arch/security/securityconf/DynamicConfigModel.java	`100.00% <ø> (ø)`
...ch/security/securityconf/DynamicConfigModelV7.java	`75.54% <100.00%> (+1.25%)`	⬆️
...g/opensearch/security/ssl/util/ExceptionUtils.java	`45.83% <100.00%> (+2.35%)`	⬆️
... and 19 more

... and 8 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nibix

Thanks for this! Cool to see API tokens going forward.

One general question: I am wondering whether we also need to modify the DLS/FLS code to be API token aware. Otherwise, the deny-by-default policy might block index access.

nibix · 2025-06-26T05:36:33Z

src/main/java/org/opensearch/security/privileges/PrivilegesEvaluator.java

+                    pluginIdToActionPrivileges.put(
+                        entry.getKey(),
+                        new SubjectBasedActionPrivileges(entry.getValue(), flattenedActionGroups)
+                    );


With this, we might need to make the pluginIdToActionPrivileges HashMap thread-safe, for example, by converting it into a ConcurrentHashMap.

Alternatively, we could have two HashMaps, one for plugins and one for API tokens.

i vote for single thread-safe map

nibix · 2025-06-26T05:46:44Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenRepository.java

+
+    private final Map<String, RoleV7> jtis = new ConcurrentHashMap<>();
+
+    void reloadApiTokensFromIndex(ActionListener<Void> listener) {


I see this is getting called when an update action is received. I think I did not see anything regarding initial node startup. Did I miss something?

Cache seems to be update only when a token is created or deleted. We should add one that loads on node bootstrap.

nibix · 2025-06-26T05:48:05Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenAction.java

+                    if (tokenCount >= 100) {
+                        sendErrorResponse(
+                            channel,
+                            RestStatus.TOO_MANY_REQUESTS,
+                            "Maximum limit of 100 API tokens reached. Please delete existing tokens before creating new ones."
+                        );
+                        return;


This seems to be a quite low limit. Is there a reason for that?

nibix · 2025-06-26T05:52:52Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenRepository.java

+    public void createApiToken(
+        String name,
+        List<String> clusterPermissions,
+        List<ApiToken.IndexPermission> indexPermissions,
+        Long expiration,
+        ActionListener<String> listener
+    ) {
+        apiTokenIndexHandler.createApiTokenIndexIfAbsent(ActionListener.wrap(() -> {
+            ExpiringBearerAuthToken token = securityTokenManager.issueApiToken(name, expiration);
+            ApiToken apiToken = new ApiToken(name, clusterPermissions, indexPermissions, expiration);
+            apiTokenIndexHandler.indexTokenMetadata(


Is the parameter name an identifier for the token? Do we need uniqueness guarantees for this?

nibix · 2025-06-26T05:56:36Z

src/main/java/org/opensearch/security/http/ApiTokenAuthenticator.java

+    private void logDebug(String message, Object... args) {
+        if (log.isDebugEnabled()) {
+            log.debug(message, args);
+        }
+    }


Nit: This method is not really necessary. It can be replaced just by log.debug() without any disadvantages. As a slight advantage, one also avoids the codecov warning for missing test coverage.

nibix · 2025-06-26T06:01:07Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenRepository.java

+    private final List<TokenListener> tokenListener = new ArrayList<>();
+    private static final Logger log = LogManager.getLogger(ApiTokenRepository.class);
+
+    private final Map<String, RoleV7> jtis = new ConcurrentHashMap<>();


What do you think about changing RoleV7 into SubjectBasedActionPrivileges here? PrivilegesEvaluator could then retrieve these instances just from here.

+1. It might not be straightforward since JTIs seem to be populated on getTokenMetadata request and there doesn't seem to be a way to pass flattenedActionGroups to that call. I may be seeing the complete picture here, but something like updateJTIs(FlattenedAGs) from PrivilegeEvaluator to update jtis and then use that to populate pluginIdToActionPrivileges which will then be used to create PrivilegeEvalContext?

nibix · 2025-06-26T06:03:02Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenRepository.java

+    public Map<String, RoleV7> getJtis() {
+        return jtis;
+    }


IMHO, this map should be kept private and managed only by this class.

nibix · 2025-06-26T06:05:56Z

src/integrationTest/java/org/opensearch/test/framework/ApiTokenConfig.java

+    public XContentBuilder toXContent(XContentBuilder xContentBuilder, Params params) throws IOException {
+        xContentBuilder.startObject();
+        xContentBuilder.field("enabled", enabled);
+        xContentBuilder.field("signing_key", signing_key);


Is this a hs512 key?

i think it fails in ApiTokenAuthenticator if it is anything lower than 512 bits.

nibix · 2025-06-26T06:11:00Z

src/main/java/org/opensearch/security/http/ApiTokenAuthenticator.java

+    public Boolean isRequestAllowed(final SecurityRequest request) {
+        Matcher matcher = PATTERN_PATH_PREFIX.matcher(request.path());
+        final String suffix = matcher.matches() ? matcher.group(2) : null;
+        if (isAccessToRestrictedEndpoints(request, suffix)) {
+            final OpenSearchException exception = ExceptionUtils.invalidUsageOfApiTokenException();
+            log.error(exception.toString());
+            return false;
+        }
+        return true;
+    }


This feels like a fragile way to deny certain endpoints, especially with the hardcoded path prefixes.

Also, do I understand it correctly that the goal of this code is that we cannot call the "issue API token" API with API tokens?

Shouldn't rest-admin-only restriction block access to endpoints anyway?

DarshitChanpura

Thank you @cwperks for taking this over. Left some comments around testing and general usage.

DarshitChanpura · 2025-06-26T18:14:57Z

src/main/java/org/opensearch/security/action/apitokens/ApiToken.java

+    public ApiToken(String name, List<String> clusterPermissions, List<IndexPermission> indexPermissions, Long expiration) {
+        this.creationTime = Instant.now();
+        this.name = name;
+        this.clusterPermissions = clusterPermissions;
+        this.indexPermissions = indexPermissions;
+        this.expiration = expiration;
+    }
+
+    public ApiToken(
+        String name,
+        List<String> clusterPermissions,
+        List<IndexPermission> indexPermissions,
+        Instant creationTime,
+        Long expiration
+    ) {
+        this.name = name;
+        this.clusterPermissions = clusterPermissions;
+        this.indexPermissions = indexPermissions;
+        this.creationTime = creationTime;
+        this.expiration = expiration;
+    }
+


nit:
can be combined into 1 constructor:

public ApiToken( String name, List<String> clusterPermissions, List<IndexPermission> indexPermissions, Instant creationTime, // nullable Long expiration) { this.name = name; this.clusterPermissions = clusterPermissions; this.indexPermissions = indexPermissions; this.creationTime = (creationTime != null) ? creationTime : Instant.now(); this.expiration = expiration; }

Can the name field be null?

DarshitChanpura · 2025-06-26T18:19:02Z

src/main/java/org/opensearch/security/action/apitokens/ApiToken.java

+     * Expected class structure
+     * {
+     *   name: "token_name",
+     *   jti: "encrypted_token",


should this field be stored in the object?

DarshitChanpura · 2025-06-26T18:29:52Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenAction.java

+                String name = (String) requestBody.get(NAME_FIELD);
+                long expiration = (Long) requestBody.getOrDefault(
+                    EXPIRATION_FIELD,
+                    Instant.now().toEpochMilli() + TimeUnit.DAYS.toMillis(30)


should we impose an upper limit on expiry?

DarshitChanpura · 2025-06-26T18:51:28Z

src/main/java/org/opensearch/security/action/apitokens/ApiToken.java

+
+    public ApiToken(String name, List<String> clusterPermissions, List<IndexPermission> indexPermissions, Long expiration) {
+        this.creationTime = Instant.now();
+        this.name = name;


Should this be UUID instead of name? or does the name field have any association with users?

DarshitChanpura · 2025-06-26T18:52:53Z

src/main/java/org/opensearch/security/action/apitokens/ApiTokenRepository.java

+    private final List<TokenListener> tokenListener = new ArrayList<>();
+    private static final Logger log = LogManager.getLogger(ApiTokenRepository.class);
+
+    private final Map<String, RoleV7> jtis = new ConcurrentHashMap<>();


+1. It might not be straightforward since JTIs seem to be populated on getTokenMetadata request and there doesn't seem to be a way to pass flattenedActionGroups to that call. I may be seeing the complete picture here, but something like updateJTIs(FlattenedAGs) from PrivilegeEvaluator to update jtis and then use that to populate pluginIdToActionPrivileges which will then be used to create PrivilegeEvalContext?

DarshitChanpura · 2025-06-26T20:09:25Z

src/integrationTest/java/org/opensearch/security/privileges/ApiTokenTest.java

+    }
+
+    @Test
+    public void shouldNotAuthenticateWithInvalidExpiration() {


we should add a case to test against expired token

DarshitChanpura · 2025-06-26T20:11:48Z

src/integrationTest/java/org/opensearch/test/framework/ApiTokenConfig.java

+    public XContentBuilder toXContent(XContentBuilder xContentBuilder, Params params) throws IOException {
+        xContentBuilder.startObject();
+        xContentBuilder.field("enabled", enabled);
+        xContentBuilder.field("signing_key", signing_key);


i think it fails in ApiTokenAuthenticator if it is anything lower than 512 bits.

DarshitChanpura · 2025-06-26T20:15:28Z

src/test/java/org/opensearch/security/identity/SecurityTokenManagerTest.java

@@ -337,4 +339,25 @@ public void testCreateJwtWithBadRoles() {
        });
        assertThat(exception.getMessage(), is("java.lang.IllegalArgumentException: Roles cannot be null"));
    }
+
+    @Test
+    public void issueApiToken_success() throws Exception {


we should add a test for failure path

DarshitChanpura · 2025-06-26T20:16:28Z

src/test/java/org/opensearch/security/authtoken/jwt/JwtVendorTest.java

+        Settings settings = Settings.builder().put("signing_key", tooShortKey).build();
+        final Throwable exception = assertThrows(OpenSearchException.class, () -> { new JwtVendor(settings); });
+
+        assertThat(exception.getMessage(), containsString("The secret length must be at least 256 bits"));


shouldn't signing key at minimum of 512 bits, based on ApiTokenAuthenticator.MINIMUM_SIGNING_KEY_BIT_LENGTH

DarshitChanpura · 2025-06-26T20:23:47Z

src/integrationTest/java/org/opensearch/security/privileges/ApiTokenTest.java

+            throw new RuntimeException(ex);
+        }
+    }
+}


we should add test to check for index permissions, i.e. ability to search from, write to an index.

derek-ho and others added 23 commits November 14, 2024 10:47

Merge branch 'main' of github.com:opensearch-project/security into HEAD

6ae7090

Scaffolding for POST/DELETE/GET api tokens calls (opensearch-project#…

3177c34

…4921) Signed-off-by: Derek Ho <[email protected]>

Adds JTI and expiration field support for API Tokens (opensearch-proj…

dacdae5

…ect#4967) Signed-off-by: Derek Ho <[email protected]>

Merge branch 'main' of github.com:opensearch-project/security into HEAD

e255e14

Signed-off-by: Derek Ho <[email protected]>

Merge branch 'main' of github.com:opensearch-project/security into HEAD

190bfec

Api token authc/z implementation with Cache (opensearch-project#4992)

79f0c46

Signed-off-by: Derek Ho <[email protected]>

Subset of permissions check on creation (opensearch-project#5012)

a8b4ac1

Signed-off-by: Derek Ho <[email protected]>

Merge branch 'main' of github.com:opensearch-project/security into HEAD

3776667

Change API token index actions to use action listeners and limit to 1…

8750e8b

…00 tokens outstanding (opensearch-project#5147) Signed-off-by: Derek Ho <[email protected]>

Merge branch 'main' into feature/api-tokens-cwperx

7b8b069

Fix naming

12c0f9c

Signed-off-by: Craig Perkins <[email protected]>

Use one PrivilegesEvaluatorContext

896e9e2

Signed-off-by: Craig Perkins <[email protected]>

Handle authz

97db90d

Signed-off-by: Craig Perkins <[email protected]>

fix unit tests

362e67f

Signed-off-by: Craig Perkins <[email protected]>

Fix tests

fa98ae2

Signed-off-by: Craig Perkins <[email protected]>

Merge branch 'main' into feature/api-tokens-cwperx

f3cd485

Add integrationTests for API Token

68107ff

Signed-off-by: Craig Perkins <[email protected]>

Add more integration tests

f5b965a

Signed-off-by: Craig Perkins <[email protected]>

Add token prefix

ba93aa3

Signed-off-by: Craig Perkins <[email protected]>

Merge branch 'main' into feature/api-tokens-cwperx

e35d3ef

Rebase with main

c028420

Signed-off-by: Craig Perkins <[email protected]>

Merge branch 'main' into feature/api-tokens-cwperx

109c1ef

Fix compilation issues

3a71078

Signed-off-by: Craig Perkins <[email protected]>

cwperks requested review from DarshitChanpura, derek-ho, nibix, peternied, RyanL1997, reta and shikharj05 as code owners June 25, 2025 17:56

cwperks requested a review from willyborankin as a code owner June 25, 2025 17:56

cwperks changed the title ~~Feature/api tokens cwperx~~ Introduce API Tokens with cluster_permissions and index_permissions directly associated with the token Jun 25, 2025

Add to CHANGELOG

dad7551

Signed-off-by: Craig Perkins <[email protected]>

nibix reviewed Jun 26, 2025

View reviewed changes

DarshitChanpura mentioned this pull request Jun 26, 2025

Feature/api tokens #5225

Closed

5 tasks

DarshitChanpura reviewed Jun 26, 2025

View reviewed changes


		private final Map<String, RoleV7> jtis = new ConcurrentHashMap<>();

		void reloadApiTokensFromIndex(ActionListener<Void> listener) {

Introduce API Tokens with cluster_permissions and index_permissions directly associated with the token #5443

Are you sure you want to change the base?

Introduce API Tokens with cluster_permissions and index_permissions directly associated with the token #5443

Conversation

cwperks commented Jun 25, 2025

Description

Issues Resolved

Check List

Uh oh!

codecov bot commented Jun 25, 2025

Codecov Report

Uh oh!

nibix left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DarshitChanpura left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Introduce API Tokens with `cluster_permissions` and `index_permissions` directly associated with the token #5443

Introduce API Tokens with `cluster_permissions` and `index_permissions` directly associated with the token #5443