Adds doc for Resource Sharing and Access Control feature #9667

DarshitChanpura · 2025-04-21T17:13:04Z

Description

Adds doc for the newly added Centralized Resource Access Control and Sharing feature.

Issues Resolved

Closes #9652

Version

3.0

Checklist

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

github-actions · 2025-04-21T17:13:17Z

Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged.

Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer.

When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review.

DarshitChanpura · 2025-04-21T17:23:23Z

Local render:
https://github.com/user-attachments/assets/04ddad65-8efb-4ae0-826c-84df96c4b246

DarshitChanpura · 2025-04-21T18:27:30Z

_security/access-control/resources.md

Naarcha-AWS

@DarshitChanpura: Most of this content seemed like implementation notes, so I tried to remove anything related to the development of the extensions or the plugin and make it more user-specific. That being said, is this extension meant only for plugin developers? If so, that would change how where we place the content.

I also have a few technical questions that need clarification.

Naarcha-AWS · 2025-04-23T18:50:18Z

_security/access-control/resources.md

+
+### opensearch-security-spi
+
+The `opensearch-security-spi` component:


Does the SPI component only pertain to plugin developers?

Naarcha-AWS · 2025-04-23T18:50:45Z

_security/access-control/resources.md

+- Tracks registered resource plugins at startup.
+- Exposes a `ResourceSharingClient` for performing share, revoke, verify, and list operations.
+
+You can customize this component based on the SPI implementation. To customize, create an extension file `src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension` containing your SPI's class name:


How does someone know their SPI implementation? What is the implementation based off of?

This is purely for plugin developers. It will be used when a new/existing plugin declares themselves as Resource plugin. Similar model is already in place for JobScheduler.

Naarcha-AWS · 2025-04-23T18:51:41Z

_security/access-control/resources.md

+
+### Document structure
+
+The resource sharing metadata is stored as JSON documents that define ownership, permissions, and access patterns. Each document contains fields that specify the resource location, identifier, creator information, and sharing configuration:


Where would I find or add this document? Is it an API call to the security plugin?

This is not visible to regular users directly as it is hidden behind SystemIndex Protection.

For plugins intending to declare a protected resource, they can retrieve the information about who can access this resources by simply calling security client's hasPermission.

End users will, in future, iterations be able to control who they can share the resource with once plugin implements those APIs and makes the info available via dashboard.

At this point, the documentation intends to serve plugin developers, with allowing admins to optionally opt in to this feature by enabling feature flag.

We are trying to implement a sharing model that doesn't exist in OpenSearch yet. This is the first step by centralizing the sharing information to security, rather than plugins storing it individually.

What would the hasPermission call look like?

Plugins would call the client by passing the id of the resources, the index name where the resource sits and a listener to receive the response. This will then be evaluated on security plugin side and a boolean response will be sent through the listener.

Naarcha-AWS · 2025-04-23T18:52:02Z

_security/access-control/resources.md

+
+- Declare and register extensions correctly.
+- Use the SPI client APIs instead of manual index queries.
+- Enable only on fresh 3.0.0+ clusters to avoid upgrade issues.


What do we mean by "fresh" clusters?

This feature is intended to be enabled only on brand new clusters.

In next iteration, we will add a migration path to enable usage on existing clusters.

DarshitChanpura · 2025-04-23T21:06:21Z

Yes, the extension is meant for plugin developers only. The feature itself toggles the "centralized " vs "non-centralized " approach when it comes to the internal sharing model.

For example, for new cluster, if AD chooses to use this and their filter by backend role setting, all detectors will upon creation be shared with the creators backend roles. However, the difference between old way and the new way is that with new way the sharing information will be stored in central index in security vs with old approach it will be stored in the ad-config index.

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

nibix · 2025-04-28T08:46:09Z

_security/access-control/resources.md

+To grant the resource sharing extension these permissions, add the following role to `roles.yaml`:
+
+```yaml
+sample_full_access:
+  cluster_permissions:
+    - 'cluster:admin/sample-resource-plugin/*'
+
+sample_read_access:
+  cluster_permissions:
+    - 'cluster:admin/sample-resource-plugin/get'
+```
+{% include copy.html %}


To which users shall these roles be assigned to? Anyone who shall be able to do resource sharing?

nibix · 2025-04-28T08:59:19Z

Thank you for this PR!

Like @Naarcha-AWS I also believe that is mostly developer docs; I think we should try to keep user documentation and developer documentation separate.

User documentation for this feature can be very minimalisting IMHO:

Notice about experimental status
How to enable
Situation with security disabled/enabled/not present
Necessary permissions
How to use
- IMHO, this will be mostly just referring readers to the docs of the respective plugins utilizing the features.
- Do we have any REST APIs left that are exposed by the security plugin regarding resource sharing? If so, these should be documented.
Did I forget something?

Developer documentation:

A separate documentation target at developers should contain:

Everything that touches Java classes, interfaces, SPIs.

I am not exactly sure where such docs should go to. There is https://docs.opensearch.org/docs/latest/developer-documentation/ but this mostly points to .md files in the git repos. There are just two small documents that are parts of the documentation website. What's the general strategy regarding that? Shall the section on the documentation website be extended? My personal opinion would be that it is better to keep it directly in respective project repos, as this minimizes the gap between code and docs. But that's just IMHO.

Naarcha-AWS · 2025-04-28T21:39:24Z

@nibix: Traditionally, Developer Documentation would belong in the repository where the source code lives, in this case, OpenSearch Security? If that's the correct location @DarshitChanpura, I can try and open a PR against that repo where the classes and such should live.

_security/access-control/resources.md

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

Naarcha-AWS · 2025-05-02T14:29:10Z

Moving this out of 3.0.0

DarshitChanpura requested review from kolchfa-aws, Naarcha-AWS, AMoo-Miki, natebower, dlvenable and epugh as code owners April 21, 2025 17:13

github-actions bot assigned kolchfa-aws Apr 21, 2025

kolchfa-aws assigned Naarcha-AWS and unassigned kolchfa-aws Apr 21, 2025

kolchfa-aws added v3.0.0 release-notes PR: Include this PR in the automated release notes labels Apr 21, 2025

Naarcha-AWS added the Doc review PR: Doc review in progress label Apr 23, 2025

Naarcha-AWS reviewed Apr 23, 2025

View reviewed changes

_security/access-control/resources.md Outdated Show resolved Hide resolved

Naarcha-AWS reviewed Apr 23, 2025

View reviewed changes

_security/access-control/resources.md Outdated Show resolved Hide resolved

Naarcha-AWS suggested changes Apr 23, 2025

View reviewed changes

DarshitChanpura force-pushed the resource-sharing-feature branch from b780759 to e465712 Compare April 24, 2025 15:24

DarshitChanpura and others added 5 commits April 24, 2025 11:25

Adds doc for Resource Sharing and Access Control feature

ada43e3

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Adds a line for onboarding plugin

e850c48

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Add tech writer review.

b736bd5

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Apply suggestions from code review

af0d632

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

Adds experimental to feature-flag key

90aaf81

Signed-off-by: Darshit Chanpura <dchanp@amazon.com>

DarshitChanpura force-pushed the resource-sharing-feature branch from ac67305 to 90aaf81 Compare April 24, 2025 15:26

Merge branch 'main' into resource-sharing-feature

430b2be

nibix reviewed Apr 28, 2025

View reviewed changes

Remove developer specific information.

c6a1132

Naarcha-AWS reviewed May 2, 2025

View reviewed changes

_security/access-control/resources.md Outdated Show resolved Hide resolved

Naarcha-AWS reviewed May 2, 2025

View reviewed changes

_security/access-control/resources.md Outdated Show resolved Hide resolved

Naarcha-AWS added 2 commits May 2, 2025 09:24

Apply suggestions from code review

d72a8b3

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

Remove more developer specific information

08e3e27

Naarcha-AWS approved these changes May 2, 2025

View reviewed changes

Naarcha-AWS added v-TBD and removed v3.0.0 labels May 2, 2025

Naarcha-AWS removed their assignment Jul 8, 2025


		### opensearch-security-spi

		The `opensearch-security-spi` component:


		### Document structure

		The resource sharing metadata is stored as JSON documents that define ownership, permissions, and access patterns. Each document contains fields that specify the resource location, identifier, creator information, and sharing configuration:

Adds doc for Resource Sharing and Access Control feature #9667

Are you sure you want to change the base?

Adds doc for Resource Sharing and Access Control feature #9667

Uh oh!

Conversation

DarshitChanpura commented Apr 21, 2025

Description

Issues Resolved

Version

Checklist

Uh oh!

github-actions bot commented Apr 21, 2025

Uh oh!

DarshitChanpura commented Apr 21, 2025

Uh oh!

DarshitChanpura commented Apr 21, 2025

Uh oh!

Uh oh!

Uh oh!

Naarcha-AWS 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!

DarshitChanpura commented Apr 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nibix commented Apr 28, 2025

Uh oh!

Naarcha-AWS commented Apr 28, 2025

Uh oh!

Uh oh!

Uh oh!

Naarcha-AWS commented May 2, 2025

Uh oh!

Uh oh!