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

❌ Patch coverage is 71.91011% with 175 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.52%. Comparing base (190b7c7) to head (bdd7d7f).

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	90.58%	2 Missing and 6 partials ⚠️
...search/security/identity/SecurityTokenManager.java	73.91%	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   73.51%   73.52%            
========================================
  Files         438      451    +13     
  Lines       26710    27323   +613     
  Branches     3956     4023    +67     
========================================
+ Hits        19637    20088   +451     
- Misses       5195     5326   +131     
- Partials     1878     1909    +31

Files with missing lines	Coverage Δ
.../opensearch/security/OpenSearchSecurityPlugin.java	`85.50% <100.00%> (+0.12%)`	⬆️
...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	`74.54% <100.00%> (+0.47%)`	⬆️
...h/security/privileges/PrivilegesEvaluatorImpl.java	`83.09% <100.00%> (+0.24%)`	⬆️
...ch/security/securityconf/DynamicConfigFactory.java	`66.66% <100.00%> (+0.21%)`	⬆️
...arch/security/securityconf/DynamicConfigModel.java	`100.00% <ø> (ø)`
...ch/security/securityconf/DynamicConfigModelV7.java	`70.16% <100.00%> (+1.56%)`	⬆️
... and 20 more

... and 11 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?

Removed the first constructor and made it so that creationTime should be supplied by the caller.

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

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

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?

name is not necessarily unique per token, but it is unique per active token. i.e. on a token's expiry you would be able to regenerate a new one with the same perms.

The metadata which includes the perms for the token is stored as a doc in the .opensearch_security_api_tokens index

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

    }
+
+    @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.

we should do this before we merge this.

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

ztomaszewska · 2025-11-21T09:41:27Z

Hi @cwperks ! First I wanted to thank you for your work on this PR. Really appreciate effort you put it in to move forward with this feature! Just wanted to ask whether is there any plan to soon merge your changes? Is there any blocking issues/ any help you would need? It would be really cool to have API tokens feature working :)

cwperks · 2025-11-25T20:43:19Z

I'll resolve the conflicts ASAP and try to push this forward for V1.

Its important to know that this PR will still have a lot of limitations, but paves the way for expansion. For instance, in this PR only the admin can issue tokens.

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

DarshitChanpura

thank you for picking this up @cwperks . Left a few comments. Main comment is addition of e2e test which checks authn+authz with API token,

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

DarshitChanpura · 2025-11-26T20:29:14Z

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

+
+                // First check token count
+                apiTokenRepository.getTokenCount(ActionListener.wrap(tokenCount -> {
+                    if (tokenCount >= 100) {


Let's make this value configurable with default to 100?
maybe maxed at 1k active tokens?

DarshitChanpura · 2025-11-26T20:31:32Z

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

+                    updateRequest,
+                    ActionListener.wrap(
+                        updateResponse -> listener.onResponse(response),
+                        exception -> listener.onFailure(new ApiTokenException("Failed to refresh cache", exception))


this message should be "Failed to update API token"

DarshitChanpura · 2025-11-26T20:37:42Z

CHANGELOG.md

+* Create a mechanism for plugins to explicitly declare actions they need to perform with their assigned PluginSubject ([#5341](https://github.com/opensearch-project/security/pull/5341))
+* Moves OpenSAML jars to a Shadow Jar configuration to facilitate its use in FIPS enabled environments ([#5400](https://github.com/opensearch-project/security/pull/5404))
+* Replaced the standard distribution of BouncyCastle with BC-FIPS ([#5439](https://github.com/opensearch-project/security/pull/5439))
+* Introduce API Tokens with `cluster_permissions` and `index_permissions` directly associated with the token ([#5443](https://github.com/opensearch-project/security/pull/5443))


change log needs to be cleaned up to only add this entry.

DarshitChanpura · 2025-11-26T20:58:20Z

src/main/java/org/opensearch/security/identity/SecurityTokenManager.java

+        if (!issueApiTokenAllowed()) {
+            throw new OpenSearchSecurityException("Api token generation is not enabled.");
+        }
+        final User user = threadPool.getThreadContext().getTransient(ConfigConstants.OPENDISTRO_SECURITY_USER);


doesn't seem like this is used?

DarshitChanpura · 2025-11-26T21:35:54Z

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

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


we should do this before we merge this.

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, RyanL1997, derek-ho, nibix, peternied, 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

nibix mentioned this pull request Jul 17, 2025

Introduced setting for disabling denormalized privilege data structures #5465

Merged

3 tasks

cwperks added 3 commits July 20, 2025 20:37

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

30f4f6f

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

3f11a61

Address PR feedback

eb512e3

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

cwperks added 2 commits November 25, 2025 17:12

Attempt to resolve conflicts

93a0e4f

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

Fix unit test

bdd7d7f

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

DarshitChanpura reviewed Nov 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

Uh oh!

Conversation

cwperks commented Jun 25, 2025

Description

Issues Resolved

Check List

Uh oh!

codecov bot commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Uh oh!

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!

ztomaszewska commented Nov 21, 2025

Uh oh!

cwperks commented Nov 25, 2025

Uh oh!

DarshitChanpura left a comment

Choose a reason for hiding this comment

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

codecov bot commented Jun 25, 2025 •

edited

Loading