From ada43e3e226cc73eed00b29c738a35896588dab8 Mon Sep 17 00:00:00 2001 From: Darshit Chanpura Date: Mon, 21 Apr 2025 13:10:52 -0400 Subject: [PATCH 1/8] Adds doc for Resource Sharing and Access Control feature Signed-off-by: Darshit Chanpura --- _security/access-control/resources.md | 192 ++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 _security/access-control/resources.md diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md new file mode 100644 index 00000000000..d9386a06146 --- /dev/null +++ b/_security/access-control/resources.md @@ -0,0 +1,192 @@ +--- +layout: default +title: Resource Sharing and Access Control +parent: Access control +nav_order: 130 +--- + +# Resource Sharing and Access Control +**Introduced 3.0** +{: .label .label-purple } + + +Available from version 3.0.0 on fresh clusters only. +{: .info } + +Marked experimental and is disabled by default. +{: .warning } + +To enable, set: +```yaml +plugins.security.resource_sharing.enabled: true +``` +{: .note } + +## 1. Overview + +OpenSearch lacked a fine-grained access control (FGAC) mechanism at the resource level for plugins, forcing each plugin to develop its own custom authorization logic. This lack of standardization led to inconsistent security enforcement, with broad permissions being assigned and an increased risk of unauthorized access. Maintaining separate access control implementations across multiple plugins also resulted in high maintenance overhead. For example, in the Anomaly Detection plugin a user with delete permissions could remove all detectors instead of just their own, illustrating the need for a centralized, standardized solution. + +The Resource Sharing and Access Control extension in the OpenSearch Security Plugin provides fine-grained, resource-level access management for plugin-declared resources. It builds on top of existing index-level authorization to let: + +Resource owners share and revoke access + +Super-admins view and manage all resources + +Plugin authors define custom shareable resources via a standardized SPI interface + +--- + +## 2. Components + +### 2.1 `opensearch-security-spi` + +A Service Provider Interface (SPI) that: + +- Defines `ResourceSharingExtension` for plugin implementations. +- Tracks registered resource plugins at startup. +- Exposes a `ResourceSharingClient` for performing share, revoke, verify, and list operations. + +#### Plugin Requirements + +##### 1. Feature Flag and Protection + - Enable `plugins.security.resource_sharing.enabled: true` + - Resource indices must be system indices with system index protection enabled (`plugins.security.system_indices.enabled: true`). + +##### 2. Build Configuration + Add to `build.gradle`: + ```gradle + compileOnly group: 'org.opensearch', name: 'opensearch-security-spi', version: "${opensearch_build}" + opensearchplugin { + name '' + description '' + classname '' + extendedPlugins = ['opensearch-security;optional=true'] + } + ``` + +##### 3. SPI Registration + Create `src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension` containing your implementation’s fully qualified class name: + ``` + com.example.MyResourceSharingExtension + ``` + +--- + +## 3. API Design + +All sharing metadata is stored in the system index `.opensearch_resource_sharing`. + +| Field | Type | Description | +| ------------- | ------ | ------------------------------------------- | +| `source_idx` | String | System index holding the resource | +| `resource_id` | String | Unique resource identifier | +| `created_by` | Object | Creator information | +| `share_with` | Object | Map of action-groups to access definitions | + +### 3.1 Document Structure + +```json +{ + "source_idx": ".plugins-ml-model-group", + "resource_id": "model-group-123", + "created_by": { + "user": "darshit" + }, + "share_with": { + "default": { + "users": ["user1"], + "roles": ["viewer_role"], + "backend_roles": ["data_analyst"] + } + } +} +``` + +### 3.2 Java Client APIs + +```java +ResourceSharingClient client = ResourceSharingClientAccessor.getResourceSharingClient(); + +// 1. Verify access +client.verifyResourceAccess(resourceId, indexName, listener); + +// 2. Share resource +client.share(resourceId, indexName, recipients, listener); + +// 3. Revoke access +client.revoke(resourceId, indexName, recipients, listener); + +// 4. List accessible IDs +client.getAccessibleResourceIds(indexName, listener); +``` + +--- + +## 4. Action Groups + +- Action-groups define permission levels (currently only default). +- To make a resource public, use wildcards: + ```json + { + "share_with": { + "default": { + "users": ["*"], + "roles": ["*"], + "backend_roles": ["*"] + } + } + } + ``` +- To keep a resource private (only owner and super-admin): + ```json + { "share_with": {} } + ``` + +--- + +## 5. User and Admin Setup + +### 5.1 Cluster Permissions + +In `roles.yml`, grant plugin API permissions: + +```yaml +sample_full_access: + cluster_permissions: + - 'cluster:admin/sample-resource-plugin/*' + +sample_read_access: + cluster_permissions: + - 'cluster:admin/sample-resource-plugin/get' +``` + +### 5.2 Access Rules + +1. Must have plugin API permission to call share, verify, or list. +2. Resource must be shared or the user must be the owner to grant access. +3. No additional index permissions are needed; system indices are protected. + +--- + +## 6. Restrictions + +- Only resource owners or super-admins can share or revoke access. +- Resources must reside in system indices. +- Disabling system index protection exposes resources to direct index-level access. + +--- + +## 7. Best Practices + +- 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. +- Grant minimal required scope when sharing. + +--- + +## 8. Additional Notes + +- Requires `plugins.security.resource_sharing.enabled: true`. +- Relies on system index protection (`plugins.security.system_indices.enabled: true`). +- Experimental feature subject to future API changes. From e850c482bcba94e275a38b85b033bed5f4ef4d97 Mon Sep 17 00:00:00 2001 From: Darshit Chanpura Date: Mon, 21 Apr 2025 14:26:54 -0400 Subject: [PATCH 2/8] Adds a line for onboarding plugin Signed-off-by: Darshit Chanpura --- _security/access-control/resources.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index d9386a06146..747a365d638 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -20,7 +20,10 @@ To enable, set: ```yaml plugins.security.resource_sharing.enabled: true ``` -{: .note } +{: .note } + +Each plugin aiming to support this feature must be onboarded onto it. Plugin developers can refer the [RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md](https://github.com/opensearch-project/security/blob/main/RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md) +{: .tip } ## 1. Overview From b736bd5df72755a6ceeaf6a024f83691e80c983f Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Wed, 23 Apr 2025 13:45:10 -0500 Subject: [PATCH 3/8] Add tech writer review. Signed-off-by: Darshit Chanpura --- _security/access-control/resources.md | 220 ++++++++++++-------------- 1 file changed, 99 insertions(+), 121 deletions(-) diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index 747a365d638..e7024c32339 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -1,92 +1,115 @@ --- layout: default -title: Resource Sharing and Access Control +title: Sharing resources between access roles parent: Access control nav_order: 130 --- -# Resource Sharing and Access Control +# Sharing resources between access roles + **Introduced 3.0** {: .label .label-purple } +This is an experimental feature and we don't recommend using it in a production environment. For updates on the feature's progress or to provide feedback, join the discussion in the [OpenSearch forum](https://forum.opensearch.org/). +{: .warning} + +The Resource Sharing extension in the OpenSearch Security plugin provides fine-grained, resource-level access management for plugin-declared resources. It builds on top of existing index-level authorization to enable you to: + +- Share and revoke access as a resource owner. +- View and manage all resources as a super-admin. +- Define custom shareable resources through a standardized Service Provider Interface (SPI). + +## Enabling the resource sharing extension + +To enable the resource sharing extension, follow these steps. -Available from version 3.0.0 on fresh clusters only. -{: .info } +### Plugin settings -Marked experimental and is disabled by default. -{: .warning } +To enable resource sharing, add the following settings to `opensearch.yaml`: -To enable, set: ```yaml plugins.security.resource_sharing.enabled: true +plugins.security.system_indices.enabled: true ``` -{: .note } +{% include copy.html %} -Each plugin aiming to support this feature must be onboarded onto it. Plugin developers can refer the [RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md](https://github.com/opensearch-project/security/blob/main/RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md) +For information about implementing this feature in your plugin, see [Resource access control for plugins](https://github.com/opensearch-project/security/blob/main/RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md). {: .tip } -## 1. Overview +### Cluster permissions -OpenSearch lacked a fine-grained access control (FGAC) mechanism at the resource level for plugins, forcing each plugin to develop its own custom authorization logic. This lack of standardization led to inconsistent security enforcement, with broad permissions being assigned and an increased risk of unauthorized access. Maintaining separate access control implementations across multiple plugins also resulted in high maintenance overhead. For example, in the Anomaly Detection plugin a user with delete permissions could remove all detectors instead of just their own, illustrating the need for a centralized, standardized solution. +The Security plugin must have the following access: -The Resource Sharing and Access Control extension in the OpenSearch Security Plugin provides fine-grained, resource-level access management for plugin-declared resources. It builds on top of existing index-level authorization to let: +- Permissions to make share, verify, and list requests. +- Shared access to all cluster components, or be the owner of the cluster. -Resource owners share and revoke access +To grant the resource sharing extension these permissions, add the following role to `roles.yaml`: -Super-admins view and manage all resources +```yaml +sample_full_access: + cluster_permissions: + - 'cluster:admin/sample-resource-plugin/*' -Plugin authors define custom shareable resources via a standardized SPI interface +sample_read_access: + cluster_permissions: + - 'cluster:admin/sample-resource-plugin/get' +``` +{% include copy.html %} ---- +## Resource sharing components -## 2. Components +The resource sharing extension consists of key components that work together to provide standardized access management. The primary component is the Service Provider Interface (SPI), which serves as the foundation for plugin integration and resource management. -### 2.1 `opensearch-security-spi` +### opensearch-security-spi -A Service Provider Interface (SPI) that: +The `opensearch-security-spi` component: - Defines `ResourceSharingExtension` for plugin implementations. - Tracks registered resource plugins at startup. - Exposes a `ResourceSharingClient` for performing share, revoke, verify, and list operations. -#### Plugin Requirements - -##### 1. Feature Flag and Protection - - Enable `plugins.security.resource_sharing.enabled: true` - - Resource indices must be system indices with system index protection enabled (`plugins.security.system_indices.enabled: true`). - -##### 2. Build Configuration - Add to `build.gradle`: - ```gradle - compileOnly group: 'org.opensearch', name: 'opensearch-security-spi', version: "${opensearch_build}" - opensearchplugin { - name '' - description '' - classname '' - extendedPlugins = ['opensearch-security;optional=true'] - } - ``` - -##### 3. SPI Registration - Create `src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension` containing your implementation’s fully qualified class name: - ``` - com.example.MyResourceSharingExtension - ``` +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: ---- +``` +com.example.MyResourceSharingExtension +``` +{% include copy.html %} + +### API -## 3. API Design +All sharing metadata is stored in the `.opensearch_resource_sharing` system index, as shown in the following table. -All sharing metadata is stored in the system index `.opensearch_resource_sharing`. +| Field | Type | Description | +| :--- | :--- | :--- | +| `source_idx` | String | The system index holding the resource | +| `resource_id` | String | The resource ID | +| `created_by` | Object | The name of the user who created the resource | +| `share_with` | Object | A map of `action-groups` to access definitions | -| Field | Type | Description | -| ------------- | ------ | ------------------------------------------- | -| `source_idx` | String | System index holding the resource | -| `resource_id` | String | Unique resource identifier | -| `created_by` | Object | Creator information | -| `share_with` | Object | Map of action-groups to access definitions | +#### Java client APIs -### 3.1 Document Structure +Use the following classes when interacting with the extension through the Java client: + +```java +ResourceSharingClient client = ResourceSharingClientAccessor.getResourceSharingClient(); + +// Verify access +client.verifyResourceAccess(resourceId, indexName, listener); + +// Share resource +client.share(resourceId, indexName, recipients, listener); + +// Revoke access +client.revoke(resourceId, indexName, recipients, listener); + +// List accessible IDs +client.getAccessibleResourceIds(indexName, listener); +``` +{% include copy.html %} + +### 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: ```json { @@ -104,92 +127,47 @@ All sharing metadata is stored in the system index `.opensearch_resource_sharing } } ``` +{% include copy.html %} -### 3.2 Java Client APIs +## Action groups -```java -ResourceSharingClient client = ResourceSharingClientAccessor.getResourceSharingClient(); - -// 1. Verify access -client.verifyResourceAccess(resourceId, indexName, listener); +Action groups define permission levels for shared resources, for example, `default`. To share resources across the action groups, use the `share_with` array in that resource's configuration and add wildcards for each default role: -// 2. Share resource -client.share(resourceId, indexName, recipients, listener); - -// 3. Revoke access -client.revoke(resourceId, indexName, recipients, listener); - -// 4. List accessible IDs -client.getAccessibleResourceIds(indexName, listener); -``` - ---- - -## 4. Action Groups - -- Action-groups define permission levels (currently only default). -- To make a resource public, use wildcards: - ```json - { - "share_with": { - "default": { - "users": ["*"], - "roles": ["*"], - "backend_roles": ["*"] - } +```json +{ + "share_with": { + "default": { + "users": ["*"], + "roles": ["*"], + "backend_roles": ["*"] } } - ``` -- To keep a resource private (only owner and super-admin): - ```json - { "share_with": {} } - ``` - ---- - -## 5. User and Admin Setup - -### 5.1 Cluster Permissions - -In `roles.yml`, grant plugin API permissions: - -```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 %} -### 5.2 Access Rules +To keep a resource private, keep the `share_with` array empty: -1. Must have plugin API permission to call share, verify, or list. -2. Resource must be shared or the user must be the owner to grant access. -3. No additional index permissions are needed; system indices are protected. +```json +{ "share_with": {} } +``` +{% include copy.html %} ---- +## Restrictions -## 6. Restrictions +Before implementing resource sharing and access control, be aware of the following limitations that help maintain security and consistency across the system: - Only resource owners or super-admins can share or revoke access. -- Resources must reside in system indices. +- Resources must reside in system indexes. - Disabling system index protection exposes resources to direct index-level access. ---- +## Best practices -## 7. Best Practices +To ensure secure and efficient implementation of resource sharing and access control, follow these recommended practices: - 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. -- Grant minimal required scope when sharing. - ---- - -## 8. Additional Notes +- Grant minimal required permissions when sharing resources. -- Requires `plugins.security.resource_sharing.enabled: true`. -- Relies on system index protection (`plugins.security.system_indices.enabled: true`). -- Experimental feature subject to future API changes. +These practices help maintain security, improve maintainability, and prevent potential issues during upgrades or system changes. From af0d632f0d43a7119973c7575370a956bdad655b Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Wed, 23 Apr 2025 13:49:26 -0500 Subject: [PATCH 4/8] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: Darshit Chanpura --- _security/access-control/resources.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index e7024c32339..f7a6f8902a2 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -21,7 +21,7 @@ The Resource Sharing extension in the OpenSearch Security plugin provides fine-g ## Enabling the resource sharing extension -To enable the resource sharing extension, follow these steps. +To enable the resource sharing extension, set up the plugin and permission settings. ### Plugin settings @@ -131,7 +131,7 @@ The resource sharing metadata is stored as JSON documents that define ownership, ## Action groups -Action groups define permission levels for shared resources, for example, `default`. To share resources across the action groups, use the `share_with` array in that resource's configuration and add wildcards for each default role: +Action groups define permission levels for shared resources. As of OpenSearch 3.0, the only supposted action group for resource sharing is `default`. To share resources across the action groups, use the `share_with` array in that resource's configuration and add wildcards for each default role: ```json { From 90aaf81dcfc91db4c3ff4c49157d146c80079ad0 Mon Sep 17 00:00:00 2001 From: Darshit Chanpura Date: Wed, 23 Apr 2025 20:09:15 -0400 Subject: [PATCH 5/8] Adds experimental to feature-flag key Signed-off-by: Darshit Chanpura --- _security/access-control/resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index f7a6f8902a2..e0bdfac8222 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -28,7 +28,7 @@ To enable the resource sharing extension, set up the plugin and permission setti To enable resource sharing, add the following settings to `opensearch.yaml`: ```yaml -plugins.security.resource_sharing.enabled: true +plugins.security.experimental.resource_sharing.enabled: true plugins.security.system_indices.enabled: true ``` {% include copy.html %} From f3810bdbebc315e9a9222a2e5b873bd343ab5d7b Mon Sep 17 00:00:00 2001 From: Darshit Chanpura Date: Thu, 20 Nov 2025 11:42:50 -0800 Subject: [PATCH 6/8] Adds resource sharing and access control documentation Signed-off-by: Darshit Chanpura --- _security/access-control/resources.md | 365 ++++++++++++++++++++------ 1 file changed, 283 insertions(+), 82 deletions(-) diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index e0bdfac8222..77ad7649156 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -5,27 +5,35 @@ parent: Access control nav_order: 130 --- -# Sharing resources between access roles +# Resource Sharing and Access Control -**Introduced 3.0** +**Introduced 3.3** {: .label .label-purple } -This is an experimental feature and we don't recommend using it in a production environment. For updates on the feature's progress or to provide feedback, join the discussion in the [OpenSearch forum](https://forum.opensearch.org/). -{: .warning} +This feature is **experimental**. +{: .warning } -The Resource Sharing extension in the OpenSearch Security plugin provides fine-grained, resource-level access management for plugin-declared resources. It builds on top of existing index-level authorization to enable you to: +The **Resource Sharing and Access Control** framework in the OpenSearch Security plugin provides *document-level*, fine-grained access management for plugin-defined resources. It extends OpenSearch’s existing role-based access control (RBAC) by letting resource owners explicitly share individual resources with other principals. -- Share and revoke access as a resource owner. -- View and manage all resources as a super-admin. -- Define custom shareable resources through a standardized Service Provider Interface (SPI). +With this feature, you can: -## Enabling the resource sharing extension +- Share or revoke access to your resources. +- Allow users with share permission to redistribute access. +- View and manage all shareable resources as a super administrator. +- Integrate shareable resource types through a standardized **Resource Sharing SPI**. +- Search resource indices with automatic per-user filtering applied by the Security plugin. -To enable the resource sharing extension, set up the plugin and permission settings. +A **resource** is currently defined as a **document stored in a plugin’s system index**, and sharing information is stored in a **central security-managed system index**. -### Plugin settings +--- + +# Enabling resource sharing + +The feature is controlled through the cluster settings configuration. + +## Cluster settings -To enable resource sharing, add the following settings to `opensearch.yaml`: +To enable resource sharing: ```yaml plugins.security.experimental.resource_sharing.enabled: true @@ -33,17 +41,39 @@ plugins.security.system_indices.enabled: true ``` {% include copy.html %} -For information about implementing this feature in your plugin, see [Resource access control for plugins](https://github.com/opensearch-project/security/blob/main/RESOURCE_ACCESS_CONTROL_FOR_PLUGINS.md). -{: .tip } +### Protected resource types + +Administrators must list which resource types use resource-level authorization: + +```yaml +plugins.security.experimental.resource_sharing.protected_types: ["sample-resource", "ml-model"] +``` +{% include copy.html %} + +These types must match the resource types declared by plugins implementing the `ResourceSharingExtension` SPI. + +### Dynamic updates (3.4+) + +Starting with **3.4**, both settings can be updated dynamically: + +```curl +PUT _cluster/settings +{ + "transient": { + "plugins.security.experimental.resource_sharing.enabled": true, + "plugins.security.experimental.resource_sharing.protected_types": ["sample-resource"] + } +} +``` +{% include copy-curl.html %} -### Cluster permissions +In **3.3**, these settings can be updated **only through `opensearch.yml`** and require a restart. -The Security plugin must have the following access: +--- -- Permissions to make share, verify, and list requests. -- Shared access to all cluster components, or be the owner of the cluster. +# Required permissions -To grant the resource sharing extension these permissions, add the following role to `roles.yaml`: +Resource sharing requires plugin-specific cluster permissions. Add the following to `roles.yml`: ```yaml sample_full_access: @@ -56,118 +86,289 @@ sample_read_access: ``` {% include copy.html %} -## Resource sharing components +Users must have both: + +1. Cluster permissions for the plugin APIs +2. Resources shared with them through the sharing APIs + +Sharing alone does **not** grant API access. + +--- + +# Resource sharing components + +The resource sharing framework includes several internal components and APIs. -The resource sharing extension consists of key components that work together to provide standardized access management. The primary component is the Service Provider Interface (SPI), which serves as the foundation for plugin integration and resource management. +## Service Provider Interface (SPI) -### opensearch-security-spi +Plugins integrate through the **`opensearch-security-spi`** package. -The `opensearch-security-spi` component: +Plugins must implement: -- Defines `ResourceSharingExtension` for plugin implementations. -- Tracks registered resource plugins at startup. -- Exposes a `ResourceSharingClient` for performing share, revoke, verify, and list operations. +* `ResourceSharingExtension` + Declares shareable resource types and system indices. +* `ResourceSharingClientAccessor` + Provides access to verification, sharing, and listing 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: +Plugins must also register: ``` -com.example.MyResourceSharingExtension +src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension ``` -{% include copy.html %} -### API +Containing only: -All sharing metadata is stored in the `.opensearch_resource_sharing` system index, as shown in the following table. +``` +com.example.MyResourceSharingExtension +``` -| Field | Type | Description | -| :--- | :--- | :--- | -| `source_idx` | String | The system index holding the resource | -| `resource_id` | String | The resource ID | -| `created_by` | Object | The name of the user who created the resource | -| `share_with` | Object | A map of `action-groups` to access definitions | +{% include copy.html %} -#### Java client APIs +## resource-action-groups.yml -Use the following classes when interacting with the extension through the Java client: +Plugins define access levels using action groups: -```java -ResourceSharingClient client = ResourceSharingClientAccessor.getResourceSharingClient(); +```yaml +resource_types: + sample-resource: + sample_read_only: + allowed_actions: + - "cluster:admin/sample-resource-plugin/get" + + sample_read_write: + allowed_actions: + - "cluster:admin/sample-resource-plugin/*" +``` -// Verify access -client.verifyResourceAccess(resourceId, indexName, listener); +These action groups become the valid “access levels” a user may share. -// Share resource -client.share(resourceId, indexName, recipients, listener); +--- -// Revoke access -client.revoke(resourceId, indexName, recipients, listener); +# Data model -// List accessible IDs -client.getAccessibleResourceIds(indexName, listener); -``` -{% include copy.html %} +All sharing metadata is stored in a dedicated *security-owned* system index. -### Document structure +| Field | Description | +|---------------|------------------------------------------------| +| `resource_id` | Unique identifier of the resource | +| `created_by` | Creator username (and tenant if applicable) | +| `share_with` | Mapping of action-groups to allowed principals | +| `source_idx` | Resource index managed by the plugin | -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: +### Example document ```json { - "source_idx": ".plugins-ml-model-group", "resource_id": "model-group-123", "created_by": { - "user": "darshit" + "user": "darshit", + "tenant": "analytics" }, "share_with": { - "default": { - "users": ["user1"], - "roles": ["viewer_role"], - "backend_roles": ["data_analyst"] + "read_only": { + "users": ["alice"], + "roles": ["data_viewer"], + "backend_roles": ["analytics_backend"] } } } ``` -{% include copy.html %} -## Action groups - -Action groups define permission levels for shared resources. As of OpenSearch 3.0, the only supposted action group for resource sharing is `default`. To share resources across the action groups, use the `share_with` array in that resource's configuration and add wildcards for each default role: +To make a resource public: ```json { "share_with": { - "default": { - "users": ["*"], - "roles": ["*"], - "backend_roles": ["*"] + "read_only": { + "users": ["*"] } } } ``` -{% include copy.html %} +NOTE: Resource will be marked public only if "*" is added to user list. +{: .note} yellow -To keep a resource private, keep the `share_with` array empty: +To keep a resource private: ```json { "share_with": {} } ``` -{% include copy.html %} -## Restrictions +--- + +# Access filtering for plugins + +When plugins perform a search on their system index: + +* The plugin performs the search using its system identity +* Security automatically filters documents based on: + + * resource owner + * shared principals + * privileges + +For example, only documents whose `all_shared_principals` list matches the authenticated user or roles will be returned. + +This filtering is done automatically if the plugin: + +* Implements `IdentityAwarePlugin` +* Uses system identity for index access (no `stashContext`) + +--- + +# Java APIs for plugins + +Plugins call the ResourceSharingClient to enforce access. + +### Verify resource access + +``` +client.verifyAccess(resourceId, resourceIndex, action, listener); +``` + +### List accessible resource IDs + +``` +client.getAccessibleResourceIds(resourceIndex, listener); +``` + +### Check if feature enabled for type + +``` +client.isFeatureEnabledForType(resourceType); +``` + +--- + +# REST APIs + +## 1. Share a resource + +Replace the entire sharing configuration. + +```curl +PUT _plugins/_security/api/resource/share +{ + "resource_id": "123", + "resource_type": "sample-resource", + "share_with": { + "read_only": { + "users": ["alice"], + "roles": ["auditor"] + } + } +} +``` +{% include copy-curl.html %} + +--- + +## 2. Modify sharing configuration + +Add or revoke access. -Before implementing resource sharing and access control, be aware of the following limitations that help maintain security and consistency across the system: +```curl +PATCH/POST _plugins/_security/api/resource/share +{ + "resource_id": "123", + "resource_type": "sample-resource", + "add": { + "read_only": { "users": ["bob"] } + }, + "revoke": { + "read_only": { "users": ["alice"] } + } +} +``` +{% include copy-curl.html %} + +--- + +## 3. Get sharing info -- Only resource owners or super-admins can share or revoke access. -- Resources must reside in system indexes. -- Disabling system index protection exposes resources to direct index-level access. +```curl +GET _plugins/_security/api/resource/share?resource_id=&resource_type= +``` +{% include copy-curl.html %} + +--- + +## 4. List resource types -## Best practices +```curl +GET _plugins/_security/api/resource/types +``` +{% include copy-curl.html %} + +Returns action groups declared by plugins. + +--- -To ensure secure and efficient implementation of resource sharing and access control, follow these recommended practices: +## 5. List accessible resources -- 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. -- Grant minimal required permissions when sharing resources. +```curl +GET _plugins/_security/api/resource/list?resource_type= +``` +{% include copy-curl.html %} + +Returns only resources visible to the caller. + +--- + +## 6. Migration API (admin-only) + +Used once to import legacy plugin-managed sharing metadata. + +```curl +POST _plugins/_security/api/resources/migrate +{ + "source_index": "", + "username_path": "", # e.g. /owner/name + "backend_roles_path": "", # e.g. /owner/backend_roles + "default_owner": "some_user", + "default_access_level": { + "": "" # if resource-index has more than one resource type add more entries + } +} + +``` +{% include copy-curl.html %} + + +--- + +# Restrictions + +* Only owners, super-admins and users with sharing access can share or revoke access. +* All resource indices must be system indices. +* System index protection must be enabled. +* Users still require plugin-level cluster permissions, specifically for creating resources. +* Action-groups must be declared in plugin configuration. + +--- + +# Best practices + +For developers: + +* Use SPI and ResourceSharingClient instead of custom ACL logic. +* Store only consistent resource types in a resource index. +* Use the implicit DLS filtering by running searches under system identity. + +For admins: + +* Enable the feature on fresh clusters first. +* Keep system index protection enabled. +* Share resources minimally and explicitly. + +--- + +# Conclusion + +The Resource Sharing and Access Control framework provides a unified and secure way to implement document-level access control for plugin-defined resources in OpenSearch. It introduces a standardized SPI, central sharing index, and new REST APIs for fine-grained authorization. + +For implementation examples, see the **sample-resource-plugin** in the security plugin repository. +For more detailed documentation on this feature, please see [RESOURCE_SHARING_AND_ACCESS_CONTROL.md](https://github.com/opensearch-project/security/blob/main/RESOURCE_SHARING_AND_ACCESS_CONTROL.md). + +--- -These practices help maintain security, improve maintainability, and prevent potential issues during upgrades or system changes. From 37763a459bb18bdce374982d1f2cab167758493e Mon Sep 17 00:00:00 2001 From: Darshit Chanpura Date: Thu, 20 Nov 2025 15:03:58 -0800 Subject: [PATCH 7/8] Adds dashboards doc and makes minor mods in backend doc file Signed-off-by: Darshit Chanpura --- _dashboards/security/resource-sharing.md | 308 +++++++++++++++++++++++ _security/access-control/resources.md | 14 +- 2 files changed, 315 insertions(+), 7 deletions(-) create mode 100644 _dashboards/security/resource-sharing.md diff --git a/_dashboards/security/resource-sharing.md b/_dashboards/security/resource-sharing.md new file mode 100644 index 00000000000..542fc00688e --- /dev/null +++ b/_dashboards/security/resource-sharing.md @@ -0,0 +1,308 @@ +--- +layout: default +title: Resource Access Management via Dashboards +nav_order: 145 +--- + +# Resource Access Management via Dashboards + +**Introduced 3.3** +{: .label .label-purple } + +Resource Sharing in OpenSearch Dashboards provides **fine-grained, document-level access control** for plugin-defined resources such as ML model groups, anomaly detectors, reports definitions, and other shareable objects. It extends OpenSearch’s role-based access control (RBAC) by allowing resource owners to specify *who* can access a resource and *what level of access* they have. + +This feature is **experimental**. +{: .warning } + +--- + +## How resource sharing works + +A **resource** is a document created by a plugin and stored in a protected system index. Examples: + +- ML model groups and models +- Anomaly detectors +- Reporting definitions +- Workflows (Flow Framework) +- Any plugin-defined resource type + +Default access: + +| User | Access | +|------------------|-----------------------------------------| +| Resource creator | Full access (view, edit, delete, share) | +| Super-admin | Full access | +| Other users | No access unless shared | + +Once a resource is shared with specific users, roles, or backend roles, it becomes visible to those users inside Dashboards. Dashboards automatically filters resource lists based on your identity, permissions, and the resource sharing configuration. + +--- + +# Requirements + +To use resource sharing in Dashboards, you must have: + +### 1. Plugin-level cluster permissions +These are assigned by an administrator. Required for resource creation. + +### 2. Resource-level sharing access +A resource must be shared with you explicitly unless you are the owner or a super-admin. + +### 3. Security plugin settings enabled + +Admins must enable: + +```yaml +plugins.security.experimental.resource_sharing.enabled: true +plugins.security.experimental.resource_sharing.protected_types: [""] +plugins.security.system_indices.enabled: true +```` + +If you do not see sharing options in Dashboards, contact your administrator. +{: .note } + +--- + +# Sharing resources through the Dashboards UI + +On left-hand navigation page, under Management section `Resource Access Management` app must be visible if the resource-sharing feature is enabled. + +## 1. Open a shareable resource + +Click on `Resource Access Management` app. Once the page loads, you will see a drop-down with a label `Select a type...`. + +Select a resource type that you would like to see your accessible resources for. + +## 2. Open the Sharing panel + +Once you select an available resource type, the Resources table will be populated will all resources you have access to. If you do not see any resources, create one or ask admins or resource owners to share them with you. + + +## 3. Choose an access level + +Dashboards retrieves available access levels (action groups) dynamically from OpenSearch. Examples: +* `ad_read_only` +* `ml_read_write` +* `flow_framework_full_access` + +NOTE: These access levels are plugin-specific levels and vary by resource-type. +{: .note } blue + +Choose the level and proceed to next step. + +## 4. Add users, roles, or backend roles + +You can grant access to: + +* Specific users +* Specific roles +* Specific backend roles + +Example inputs: + +* User: `alice` +* Role: `data_viewer` +* Backend role: `engineering_team` + +Wildcards (`*`) are supported and come into effect only for users field which can be used to mark a resource as a publicly accessible at the chosen access level. + +## 5. Save your changes + +Dashboards updates the backend configuration and immediately applies access changes. + +--- + +# Viewing and managing access + +The Sharing panel shows: + +* The **resource owner** +* All users/roles/backend roles with access +* Their access levels +* Whether you can reshare the resource + +A user can share a resource only if: + +* They are the owner +* Or the owner shared the resource with them *and* granted share permission +* Or they are a super-admin + +Removing access immediately hides the resource from affected users. + +--- + +# Listing resources shared with you + +Dashboards automatically displays only the resources you can access. No special actions are required. Visibility is determined by: + +* Ownership +* Sharing configuration +* Plugin cluster permissions +* Role/backend role membership +* Wildcards (`users: ["*"]` for public resources) + +--- + +# Managing resource sharing using Dev Tools + +You can also manage resource sharing directly using the **Dev Tools Console** in Dashboards. These operations can only be performed if you are the owner, a super-admin or have sharing access to the resource. + +All APIs start with: + +``` +_plugins/_security/api/resource +``` + +--- + +## 1. Migration API (admin-only) + +Used once to import legacy plugin-managed sharing metadata. + +``` +POST _plugins/_security/api/resources/migrate +{ + "source_index": "", + "username_path": "", # e.g. /owner/name + "backend_roles_path": "", # e.g. /owner/backend_roles + "default_owner": "some_user", + "default_access_level": { + "": "" # if resource-index has more than one resource type add more entries + } +} + +``` +{% include copy-curl.html %} + +## 2. View sharing configuration + +``` +GET _plugins/_security/api/resource/share?resource_id=&resource_type= +``` +{% include copy-curl.html %} + +--- + +## 3. Share a resource (replace all access) + +This **overwrites** the entire sharing configuration. + +``` +PUT _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "share_with": { + "read_only": { "users": ["bob"] }, + "read_write": { "users": ["charlie"] } + } +} +``` +{% include copy-curl.html %} + +--- + +## 4. Add or revoke access (non-destructive) + +This updates sharing without removing existing access. + +``` +PATCH _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + + "add": { + "read_only": { "users": ["dave"] } + }, + + "revoke": { + "read_write": { "users": ["charlie"] } + } +} +``` +{% include copy-curl.html %} + +--- + +## 5. List all resources you can access + +``` +GET _plugins/_security/api/resource/list?resource_type= +``` +{% include copy-curl.html %} + +--- + +## 6. List all shareable resource types + +``` +GET _plugins/_security/api/resource/types +``` +{% include copy-curl.html %} + +Dashboards uses this to determine supported access levels per resource type. + +--- + +## 7. Making a resource public + +``` +PATCH _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "add": { + "read_only": { "users": ["*"] } + } +} +``` +{% include copy-curl.html %} + +--- + +## 8. Making a resource private + +``` +PUT _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "share_with": {} +} +``` +{% include copy-curl.html %} + +This resets the resource to **owner-only**. + +--- + +# Troubleshooting + +| Issue | Possible cause | Fix | +|----------------------------------------------|----------------------------------------|----------------------------------------------------------------------------| +| `Resource Access Management` app not visible | Feature disabled | Ask admin to enable `resource_sharing.enabled` | +| User can't create resource | Missing plugin API permissions | Ask admin to map to appropriate role | +| User can't access a resource | Resource is not shared with them | Ask owner to share it with them at appropriate access level | +| API returns 403 in Dev Tools | Resource is not shared with them | Ask owner to share it with them at appropriate access level | +| Resource not listed in Dashboards | Resource not marked as protected | Ask admin to mark resource as protected `resource_sharing.protected_types` | +| PATCH does nothing | Access level not defined for that type | Verify plugin’s action-groups | + +--- + +# Summary + +Resource Sharing in Dashboards allows you to: + +* Keep resources private +* Share resources securely with specific users or teams +* Grant read-only or read-write access +* Modify or revoke access at any time +* Automate or batch operations using Dev Tools + +Dashboards provides a simple UI for everyday access management, while Dev Tools offers full control for advanced workflows. + +If resource sharing features are not visible in Dashboards, contact your OpenSearch administrator to enable the capability and assign appropriate permissions. + +Looking for backend concepts, APIs, and YAML setup? See the backend guide: [Resource Sharing and Access Control]({{site.url}}{{site.baseurl}}/security/access-control/resources/) +{: .note} diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index 77ad7649156..62d336fe4cd 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -56,7 +56,7 @@ These types must match the resource types declared by plugins implementing the ` Starting with **3.4**, both settings can be updated dynamically: -```curl +``` PUT _cluster/settings { "transient": { @@ -246,7 +246,7 @@ client.isFeatureEnabledForType(resourceType); Replace the entire sharing configuration. -```curl +``` PUT _plugins/_security/api/resource/share { "resource_id": "123", @@ -267,7 +267,7 @@ PUT _plugins/_security/api/resource/share Add or revoke access. -```curl +``` PATCH/POST _plugins/_security/api/resource/share { "resource_id": "123", @@ -286,7 +286,7 @@ PATCH/POST _plugins/_security/api/resource/share ## 3. Get sharing info -```curl +``` GET _plugins/_security/api/resource/share?resource_id=&resource_type= ``` {% include copy-curl.html %} @@ -295,7 +295,7 @@ GET _plugins/_security/api/resource/share?resource_id=&resource_type= ``` {% include copy-curl.html %} @@ -319,7 +319,7 @@ Returns only resources visible to the caller. Used once to import legacy plugin-managed sharing metadata. -```curl +``` POST _plugins/_security/api/resources/migrate { "source_index": "", From c7adfea1a5e0c69144653c6c2c3b112b0684693b Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 1 Dec 2025 09:31:42 -0500 Subject: [PATCH 8/8] Doc review Signed-off-by: Fanit Kolchina --- _dashboards/management/management-index.md | 1 + _dashboards/management/resource-sharing.md | 137 +++++++ _dashboards/security/resource-sharing.md | 308 --------------- .../anonymous-authentication.md | 2 +- _security/access-control/api.md | 10 +- .../access-control/default-action-groups.md | 2 +- .../access-control/document-level-security.md | 2 +- .../access-control/field-level-security.md | 2 +- _security/access-control/field-masking.md | 2 +- _security/access-control/impersonation.md | 2 +- _security/access-control/permissions.md | 2 +- .../access-control/resource-sharing-api.md | 313 +++++++++++++++ _security/access-control/resources.md | 365 +++++------------- _security/access-control/rest-layer-authz.md | 2 +- _security/access-control/users-roles.md | 2 +- 15 files changed, 572 insertions(+), 580 deletions(-) create mode 100644 _dashboards/management/resource-sharing.md delete mode 100644 _dashboards/security/resource-sharing.md create mode 100644 _security/access-control/resource-sharing-api.md diff --git a/_dashboards/management/management-index.md b/_dashboards/management/management-index.md index 04a72622ae4..575c6d6ff2c 100644 --- a/_dashboards/management/management-index.md +++ b/_dashboards/management/management-index.md @@ -22,3 +22,4 @@ You can access the following applications in **Dashboards Management**: - **[Data Sources]({{site.url}}{{site.baseurl}}/dashboards/management/multi-data-sources/):** The Data Sources tool is used to configure and manage the data sources that OpenSearch uses to collect and analyze data. You can use the tool to specify the source configuration in your copy of the [OpenSearch Dashboards configuration file](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/config/opensearch_dashboards.yml). - **[Saved Objects](https://opensearch.org/blog/enhancement-multiple-data-source-import-saved-object/):** The Saved Objects tool helps you organize and manage your saved objects. Saved objects are files that store data, such as dashboards, visualizations, and maps, for later use. - **[Advanced Settings]({{site.url}}{{site.baseurl}}/dashboards/management/advanced-settings/):** The Advanced Settings tool gives you the flexibility to personalize the behavior of OpenSearch Dashboards. The tool is divided into settings sections, such as General, Accessibility, and Notifications, and you can use it to customize and optimize many of your Dashboards settings. +- **[Resource Access Management]({{site.url}}{{site.baseurl}}/dashboards/management/resource-sharing/):** The Resource Access Management tool provides fine-grained access control for plugin-defined resources such as ML model groups, anomaly detectors, and report definitions. You can share resources with specific users, roles, or backend roles and control their access levels. diff --git a/_dashboards/management/resource-sharing.md b/_dashboards/management/resource-sharing.md new file mode 100644 index 00000000000..b559e1714cd --- /dev/null +++ b/_dashboards/management/resource-sharing.md @@ -0,0 +1,137 @@ +--- +layout: default +title: Resource access management +parent: Dashboards Management +nav_order: 55 +--- + +# Resource access management +**Introduced 3.3** +{: .label .label-purple } + +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). +{: .warning} + +Resource sharing in OpenSearch Dashboards provides fine-grained, document-level access control for plugin-defined resources such as ML model groups, anomaly detectors, report definitions, and other shareable objects. This feature extends OpenSearch's role-based access control by allowing resource owners to specify who can access a resource and what level of access they have, including read-only or read-write permissions. OpenSearch Dashboards offers a simple UI for everyday access management, while the Dev Tools console enables automation or batch operations for advanced workflows. + +If resource sharing features are not visible in OpenSearch Dashboards, contact your OpenSearch administrator to enable the capability and assign appropriate permissions. +{: .note} + +A **resource** is a document created by a plugin and stored in a protected system index, for example: + +- ML model groups and models +- Anomaly detectors +- Reporting definitions +- Flow framework workflows +- Any plugin-defined resource type + +The following table lists the default resource access, which is determined by the user's role and relationship to the resource. + +| User | Access | +|------------------|-----------------------------------------| +| Resource creator | Full access (view, edit, delete, share) | +| Super-admin | Full access | +| Other users | No access unless shared | + +Once a resource is shared with specific users, roles, or backend roles, it becomes visible to those users in OpenSearch Dashboards. OpenSearch Dashboards automatically filters resource lists based on your identity, permissions, and the resource sharing configuration. + +## Prerequisites + +To use resource sharing in OpenSearch Dashboards, you must fulfill the following prerequisites: + +* **Plugin-level cluster permissions**: Assigned by an administrator; required for creating resources. +* **Resource-level sharing access**: The resource must be explicitly shared with you unless you are the owner or a super-admin. +* **Security plugin settings enabled**: Administrators must enable the following in the configuration: + ```yaml + plugins.security.experimental.resource_sharing.enabled: true + plugins.security.experimental.resource_sharing.protected_types: [""] + plugins.security.system_indices.enabled: true + ``` + {% include copy.html %} + + For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). + +# Sharing resources using OpenSearch Dashboards + +Follow these steps to share resources in OpenSearch Dashboards: + +1. Open a shareable resource: + + * In the left navigation, under the **Management** section, select **Resource Access Management** (visible only if resource sharing is enabled). + * From the resource type dropdown list, choose the resource type you want to view or manage. The **Resources** table automatically displays all resources you have access to. If no resources appear, create one or ask an administrator or resource owner to share it with you. + +1. Choose an access level. OpenSearch Dashboards dynamically retrieves available access levels (action groups) from OpenSearch, for example: + + * `ad_read_only` + * `ml_read_write` + * `flow_framework_full_access` + Access levels are plugin-specific and vary by resource type. + {: .note} + +1. Add users, roles, or backend roles: + * Specific users (for example, `alice`) + * Specific roles (for example, `data_viewer`) + * Specific backend roles (for example, `engineering_team`) + + Wildcards (`*`) are supported for the users field to make a resource publicly accessible at the chosen access level. + {: .note} + +1. Select **Save** to update the backend configuration. Changes are applied immediately. + + +## Viewing and managing access + +Follow these steps to view and manage access for a resource in OpenSearch Dashboards: + +1. Open the **Sharing** panel: + + * Navigate to the **Resource Access Management** app and select a resource from the **Resources** table. The panel displays: + * The resource owner. + * All users, roles, and backend roles with access. + * Their assigned access levels. + * Whether you have permission to reshare the resource. + +1. Determine sharing permissions. You can share a resource only if you meet one of the following conditions: + + * You are the owner of the resource. + * The owner shared the resource with you and granted share permission. + * You are a superadmin. + +1. Add or remove users, roles, or backend roles as needed. Removing access immediately hides the resource from the affected users. + +## Listing resources shared with you + +OpenSearch Dashboards automatically shows only the resources you have access to. No additional actions are required. + +Resource visibility is determined by: + +* **Ownership** – You are the owner of the resource. +* **Sharing configuration** – The resource has been explicitly shared with you. +* **Plugin cluster permissions** – You have the necessary permissions for the resource’s plugin. +* **Role or backend role membership** – Your roles grant access to the resource. +* **Public resources** – Resources shared with all users using wildcards (for example, `users: ["*"]`). + + +## Managing resource sharing using APIs + +You can manage resource sharing programmatically using REST APIs. These operations can only be performed if you are the owner, a superadmin, or have sharing access to the resource. You can use the command line or the **Dev Tools** console to send API requests. + +For complete API documentation including endpoints, parameters, and examples, see [Resource sharing APIs]({{site.url}}{{site.baseurl}}/security/access-control/resource-sharing-api/). + +## Troubleshooting + +Use the following table to troubleshoot the following common issues. + +| Issue | Possible cause | Fix | +|----------------------------------------------|----------------------------------------|----------------------------------------------------------------------------| +| `Resource Access Management` app not visible | Feature disabled | Ask admin to enable `resource_sharing.enabled` | +| User can't create resource | Missing plugin API permissions | Ask admin to map to appropriate role | +| User can't access a resource | Resource is not shared with them | Ask owner to share it with them at appropriate access level | +| API returns 403 in Dev Tools | Resource is not shared with them | Ask owner to share it with them at appropriate access level | +| Resource not listed in OpenSearch Dashboards | Resource not marked as protected | Ask admin to mark resource as protected `resource_sharing.protected_types` | +| PATCH does nothing | Access level not defined for that type | Verify plugin’s action-groups | + +## Related documentation + +- [Resource sharing and access control]({{site.url}}{{site.baseurl}}/security/access-control/resources/) - Backend concepts, configuration, and setup +- [Resource sharing APIs]({{site.url}}{{site.baseurl}}/security/access-control/resource-sharing-api/) - REST API reference for programmatic management \ No newline at end of file diff --git a/_dashboards/security/resource-sharing.md b/_dashboards/security/resource-sharing.md deleted file mode 100644 index 542fc00688e..00000000000 --- a/_dashboards/security/resource-sharing.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -layout: default -title: Resource Access Management via Dashboards -nav_order: 145 ---- - -# Resource Access Management via Dashboards - -**Introduced 3.3** -{: .label .label-purple } - -Resource Sharing in OpenSearch Dashboards provides **fine-grained, document-level access control** for plugin-defined resources such as ML model groups, anomaly detectors, reports definitions, and other shareable objects. It extends OpenSearch’s role-based access control (RBAC) by allowing resource owners to specify *who* can access a resource and *what level of access* they have. - -This feature is **experimental**. -{: .warning } - ---- - -## How resource sharing works - -A **resource** is a document created by a plugin and stored in a protected system index. Examples: - -- ML model groups and models -- Anomaly detectors -- Reporting definitions -- Workflows (Flow Framework) -- Any plugin-defined resource type - -Default access: - -| User | Access | -|------------------|-----------------------------------------| -| Resource creator | Full access (view, edit, delete, share) | -| Super-admin | Full access | -| Other users | No access unless shared | - -Once a resource is shared with specific users, roles, or backend roles, it becomes visible to those users inside Dashboards. Dashboards automatically filters resource lists based on your identity, permissions, and the resource sharing configuration. - ---- - -# Requirements - -To use resource sharing in Dashboards, you must have: - -### 1. Plugin-level cluster permissions -These are assigned by an administrator. Required for resource creation. - -### 2. Resource-level sharing access -A resource must be shared with you explicitly unless you are the owner or a super-admin. - -### 3. Security plugin settings enabled - -Admins must enable: - -```yaml -plugins.security.experimental.resource_sharing.enabled: true -plugins.security.experimental.resource_sharing.protected_types: [""] -plugins.security.system_indices.enabled: true -```` - -If you do not see sharing options in Dashboards, contact your administrator. -{: .note } - ---- - -# Sharing resources through the Dashboards UI - -On left-hand navigation page, under Management section `Resource Access Management` app must be visible if the resource-sharing feature is enabled. - -## 1. Open a shareable resource - -Click on `Resource Access Management` app. Once the page loads, you will see a drop-down with a label `Select a type...`. - -Select a resource type that you would like to see your accessible resources for. - -## 2. Open the Sharing panel - -Once you select an available resource type, the Resources table will be populated will all resources you have access to. If you do not see any resources, create one or ask admins or resource owners to share them with you. - - -## 3. Choose an access level - -Dashboards retrieves available access levels (action groups) dynamically from OpenSearch. Examples: -* `ad_read_only` -* `ml_read_write` -* `flow_framework_full_access` - -NOTE: These access levels are plugin-specific levels and vary by resource-type. -{: .note } blue - -Choose the level and proceed to next step. - -## 4. Add users, roles, or backend roles - -You can grant access to: - -* Specific users -* Specific roles -* Specific backend roles - -Example inputs: - -* User: `alice` -* Role: `data_viewer` -* Backend role: `engineering_team` - -Wildcards (`*`) are supported and come into effect only for users field which can be used to mark a resource as a publicly accessible at the chosen access level. - -## 5. Save your changes - -Dashboards updates the backend configuration and immediately applies access changes. - ---- - -# Viewing and managing access - -The Sharing panel shows: - -* The **resource owner** -* All users/roles/backend roles with access -* Their access levels -* Whether you can reshare the resource - -A user can share a resource only if: - -* They are the owner -* Or the owner shared the resource with them *and* granted share permission -* Or they are a super-admin - -Removing access immediately hides the resource from affected users. - ---- - -# Listing resources shared with you - -Dashboards automatically displays only the resources you can access. No special actions are required. Visibility is determined by: - -* Ownership -* Sharing configuration -* Plugin cluster permissions -* Role/backend role membership -* Wildcards (`users: ["*"]` for public resources) - ---- - -# Managing resource sharing using Dev Tools - -You can also manage resource sharing directly using the **Dev Tools Console** in Dashboards. These operations can only be performed if you are the owner, a super-admin or have sharing access to the resource. - -All APIs start with: - -``` -_plugins/_security/api/resource -``` - ---- - -## 1. Migration API (admin-only) - -Used once to import legacy plugin-managed sharing metadata. - -``` -POST _plugins/_security/api/resources/migrate -{ - "source_index": "", - "username_path": "", # e.g. /owner/name - "backend_roles_path": "", # e.g. /owner/backend_roles - "default_owner": "some_user", - "default_access_level": { - "": "" # if resource-index has more than one resource type add more entries - } -} - -``` -{% include copy-curl.html %} - -## 2. View sharing configuration - -``` -GET _plugins/_security/api/resource/share?resource_id=&resource_type= -``` -{% include copy-curl.html %} - ---- - -## 3. Share a resource (replace all access) - -This **overwrites** the entire sharing configuration. - -``` -PUT _plugins/_security/api/resource/share -{ - "resource_id": "model-group-123", - "resource_type": "ml-model-group", - "share_with": { - "read_only": { "users": ["bob"] }, - "read_write": { "users": ["charlie"] } - } -} -``` -{% include copy-curl.html %} - ---- - -## 4. Add or revoke access (non-destructive) - -This updates sharing without removing existing access. - -``` -PATCH _plugins/_security/api/resource/share -{ - "resource_id": "model-group-123", - "resource_type": "ml-model-group", - - "add": { - "read_only": { "users": ["dave"] } - }, - - "revoke": { - "read_write": { "users": ["charlie"] } - } -} -``` -{% include copy-curl.html %} - ---- - -## 5. List all resources you can access - -``` -GET _plugins/_security/api/resource/list?resource_type= -``` -{% include copy-curl.html %} - ---- - -## 6. List all shareable resource types - -``` -GET _plugins/_security/api/resource/types -``` -{% include copy-curl.html %} - -Dashboards uses this to determine supported access levels per resource type. - ---- - -## 7. Making a resource public - -``` -PATCH _plugins/_security/api/resource/share -{ - "resource_id": "model-group-123", - "resource_type": "ml-model-group", - "add": { - "read_only": { "users": ["*"] } - } -} -``` -{% include copy-curl.html %} - ---- - -## 8. Making a resource private - -``` -PUT _plugins/_security/api/resource/share -{ - "resource_id": "model-group-123", - "resource_type": "ml-model-group", - "share_with": {} -} -``` -{% include copy-curl.html %} - -This resets the resource to **owner-only**. - ---- - -# Troubleshooting - -| Issue | Possible cause | Fix | -|----------------------------------------------|----------------------------------------|----------------------------------------------------------------------------| -| `Resource Access Management` app not visible | Feature disabled | Ask admin to enable `resource_sharing.enabled` | -| User can't create resource | Missing plugin API permissions | Ask admin to map to appropriate role | -| User can't access a resource | Resource is not shared with them | Ask owner to share it with them at appropriate access level | -| API returns 403 in Dev Tools | Resource is not shared with them | Ask owner to share it with them at appropriate access level | -| Resource not listed in Dashboards | Resource not marked as protected | Ask admin to mark resource as protected `resource_sharing.protected_types` | -| PATCH does nothing | Access level not defined for that type | Verify plugin’s action-groups | - ---- - -# Summary - -Resource Sharing in Dashboards allows you to: - -* Keep resources private -* Share resources securely with specific users or teams -* Grant read-only or read-write access -* Modify or revoke access at any time -* Automate or batch operations using Dev Tools - -Dashboards provides a simple UI for everyday access management, while Dev Tools offers full control for advanced workflows. - -If resource sharing features are not visible in Dashboards, contact your OpenSearch administrator to enable the capability and assign appropriate permissions. - -Looking for backend concepts, APIs, and YAML setup? See the backend guide: [Resource Sharing and Access Control]({{site.url}}{{site.baseurl}}/security/access-control/resources/) -{: .note} diff --git a/_security/access-control/anonymous-authentication.md b/_security/access-control/anonymous-authentication.md index cb2f951546c..f5aecd9a00c 100644 --- a/_security/access-control/anonymous-authentication.md +++ b/_security/access-control/anonymous-authentication.md @@ -2,7 +2,7 @@ layout: default title: Anonymous authentication parent: Access control -nav_order: 145 +nav_order: 130 --- # Anonymous authentication diff --git a/_security/access-control/api.md b/_security/access-control/api.md index c0b39ecbe24..03fa8bf3622 100644 --- a/_security/access-control/api.md +++ b/_security/access-control/api.md @@ -11,8 +11,6 @@ redirect_from: The Security plugin REST API lets you programmatically create and manage users, roles, role mappings, action groups, and tenants. ---- - #### Table of contents 1. TOC {:toc} @@ -2008,3 +2006,11 @@ HTTP/1.1 200 OK content-type: application/json; charset=UTF-8 content-length: 45 ``` + +--- + +## Resource sharing +**Introduced 3.3** +{: .label .label-purple } + +For managing resource-level access control and sharing plugin-defined resources such as ML models and anomaly detectors, see [Resource sharing APIs]({{site.url}}{{site.baseurl}}/security/access-control/resource-sharing-api/). \ No newline at end of file diff --git a/_security/access-control/default-action-groups.md b/_security/access-control/default-action-groups.md index c50ed40a1bf..ee7bd404771 100644 --- a/_security/access-control/default-action-groups.md +++ b/_security/access-control/default-action-groups.md @@ -2,7 +2,7 @@ layout: default title: Default action groups parent: Access control -nav_order: 115 +nav_order: 80 redirect_from: - /security/access-control/default-action-groups/ - /security-plugin/access-control/default-action-groups/ diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index b17b60e147b..06f85453dd4 100644 --- a/_security/access-control/document-level-security.md +++ b/_security/access-control/document-level-security.md @@ -2,7 +2,7 @@ layout: default title: Document-level security parent: Access control -nav_order: 85 +nav_order: 90 redirect_from: - /security/access-control/document-level-security/ - /security-plugin/access-control/document-level-security/ diff --git a/_security/access-control/field-level-security.md b/_security/access-control/field-level-security.md index 24b1f3744f1..577f7c61bce 100644 --- a/_security/access-control/field-level-security.md +++ b/_security/access-control/field-level-security.md @@ -2,7 +2,7 @@ layout: default title: Field-level security parent: Access control -nav_order: 90 +nav_order: 95 redirect_from: - /security/access-control/field-level-security/ - /security-plugin/access-control/field-level-security/ diff --git a/_security/access-control/field-masking.md b/_security/access-control/field-masking.md index fc7a8bed517..f8d377b9254 100644 --- a/_security/access-control/field-masking.md +++ b/_security/access-control/field-masking.md @@ -2,7 +2,7 @@ layout: default title: Field masking parent: Access control -nav_order: 95 +nav_order: 100 redirect_from: - /security/access-control/field-masking/ - /security-plugin/access-control/field-masking/ diff --git a/_security/access-control/impersonation.md b/_security/access-control/impersonation.md index 4bf7ab689d3..f4d51157dbf 100644 --- a/_security/access-control/impersonation.md +++ b/_security/access-control/impersonation.md @@ -2,7 +2,7 @@ layout: default title: User impersonation parent: Access control -nav_order: 100 +nav_order: 105 redirect_from: - /security/access-control/impersonation/ - /security-plugin/access-control/impersonation/ diff --git a/_security/access-control/permissions.md b/_security/access-control/permissions.md index 287bdb23ccf..1c233486345 100644 --- a/_security/access-control/permissions.md +++ b/_security/access-control/permissions.md @@ -2,7 +2,7 @@ layout: default title: Permissions parent: Access control -nav_order: 110 +nav_order: 75 redirect_from: - /security-plugin/access-control/permissions/ --- diff --git a/_security/access-control/resource-sharing-api.md b/_security/access-control/resource-sharing-api.md new file mode 100644 index 00000000000..be97c74c9d8 --- /dev/null +++ b/_security/access-control/resource-sharing-api.md @@ -0,0 +1,313 @@ +--- +layout: default +title: Resource sharing APIs +parent: Resource sharing and access control +grand_parent: Access control +nav_order: 10 +--- + +# Resource sharing APIs +**Introduced 3.3** +{: .label .label-purple } + +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). +{: .warning} + +The Resource Sharing APIs provide programmatic access to manage fine-grained, document-level access control for plugin-defined resources. These APIs allow you to share resources, manage access permissions, and automate resource sharing workflows. + +You can manage resource sharing directly using these REST APIs. Operations can only be performed if you are the owner, a superadmin, or have sharing access to the resource. + +## Migrate legacy sharing metadata + +Imports legacy plugin-managed sharing metadata. This API is intended for administrators to run once during system migration. + +### Endpoint + +```json +POST _plugins/_security/api/resources/migrate +``` + +### Request body fields + +The following table lists the available request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `source_index` | String | The source index containing legacy sharing metadata. Required. | +| `username_path` | String | A JSON path to the owner name (for example, `/owner/name`). Required. | +| `backend_roles_path` | String | A JSON path to backend roles (for example, `/owner/backend_roles`). Required. | +| `default_owner` | String | The default owner for resources without explicit ownership. Required. | +| `default_access_level` | Object | The default access levels by resource type. Add additional entries if the resource index contains multiple resource types. Required. | + +### Example request + +```json +POST _plugins/_security/api/resources/migrate +{ + "source_index": "legacy-sharing-index", + "username_path": "/owner/name", + "backend_roles_path": "/owner/backend_roles", + "default_owner": "admin", + "default_access_level": { + "ml-model-group": "read_only", + "anomaly-detector": "read_write" + } +} +``` +{% include copy-curl.html %} + +### Required permissions + +If you use the Security plugin, make sure you have the appropriate permissions: `restapi:admin/resource_sharing/migrate`. + +## Get sharing configuration + +Retrieves the current sharing configuration for a specific resource. + +### Endpoint + +```json +GET _plugins/_security/api/resource/share +``` + +### Query parameters + +The following table lists the available query parameters. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `resource_id` | String | The unique identifier of the resource. Required. | +| `resource_type` | String | The type of the resource (for example, `ml-model-group`). Required. | + +### Example request + +```json +GET _plugins/_security/api/resource/share?resource_id=model-group-123&resource_type=ml-model-group +``` +{% include copy-curl.html %} + +### Example response + +```json + +``` + +### Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | + +### Required permissions + +If you use the Security plugin, make sure you have the appropriate permissions: `cluster:admin/security/resource/share`. + +## Replace resource sharing configuration + +Completely replaces the sharing configuration for a resource. This operation overwrites all existing sharing settings. + +### Endpoint + +```json +PUT _plugins/_security/api/resource/share +``` + +### Request body fields + +The following table lists the available request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `resource_id` | String | The unique identifier of the resource. Required. | +| `resource_type` | String | The type of the resource. Required. | +| `share_with` | Object | Sharing configuration organized by access level. Each access level can contain `users`, `roles`, and `backend_roles` arrays. Required. | + +### Example request: Share with specific users and roles + +```json +PUT _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "share_with": { + "read_only": { + "users": ["bob"], + "roles": ["data_viewer"] + }, + "read_write": { + "users": ["charlie"], + "backend_roles": ["ml_team"] + } + } +} +``` +{% include copy-curl.html %} + +### Example request: Make a resource private + +```json +PUT _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "share_with": {} +} +``` +{% include copy-curl.html %} + +### Required permissions + +If you use the Security plugin, make sure you have the appropriate permissions: `cluster:admin/security/resource/share`. + +## Update resource sharing configuration + +Adds or removes access without affecting existing sharing configuration. This operation is non-destructive and preserves current access settings. + +### Endpoint + +```json +PATCH _plugins/_security/api/resource/share +``` + +### Request body fields + +The following table lists the available request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `resource_id` | String | The unique identifier of the resource. Required. | +| `resource_type` | String | The type of the resource. Required. | +| `add` | Object | Access to add, organized by access level. Optional. | +| `revoke` | Object | Access to remove, organized by access level. Optional. | + +### Example request: Add and revoke access simultaneously + +```json +PATCH _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "add": { + "read_only": { "users": ["dave"] } + }, + "revoke": { + "read_write": { "users": ["charlie"] } + } +} +``` +{% include copy-curl.html %} + +### Example request: Make a resource public + +```json +PATCH _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "add": { + "read_only": { "users": ["*"] } + } +} +``` +{% include copy-curl.html %} + +### Example request: Remove specific access + +```json +PATCH _plugins/_security/api/resource/share +{ + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "revoke": { + "read_write": { "users": ["charlie"] } + } +} +``` +{% include copy-curl.html %} + +### Required permissions + +If you use the Security plugin, make sure you have the appropriate permissions: `cluster:admin/security/resource/share`. + +## List accessible resources + +Returns all resources of a specific type that you have access to view or manage. + +### Endpoint + +```json +GET _plugins/_security/api/resource/list +``` + +### Query parameters + +The following table lists the available query parameters. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `resource_type` | String | The type of resources to list. Required. | + +### Example request + +```json +GET _plugins/_security/api/resource/list?resource_type=ml-model-group +``` +{% include copy-curl.html %} + +### Example response + +```json + +``` + +### Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | + +### Required permissions + +This API requires authenticated access but does not require specific cluster permissions. + +## List resource types + +Returns all available shareable resource types and their supported access levels. OpenSearch Dashboards uses this API to determine supported access levels per resource type. + +### Endpoint + +```json +GET _plugins/_security/api/resource/types +``` + +### Example request + +```json +GET _plugins/_security/api/resource/types +``` +{% include copy-curl.html %} + +### Example response + +```json + +``` + +### Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | + +### Required permissions + +This API requires authenticated access but does not require specific cluster permissions. + + +## Related documentation + +- [Resource sharing and access control]({{site.url}}{{site.baseurl}}/security/access-control/resources/) - Backend concepts, configuration, and setup +- [Resource access management]({{site.url}}{{site.baseurl}}/dashboards/management/resource-sharing/) - UI workflows and user guidance \ No newline at end of file diff --git a/_security/access-control/resources.md b/_security/access-control/resources.md index 62d336fe4cd..172486279db 100644 --- a/_security/access-control/resources.md +++ b/_security/access-control/resources.md @@ -1,62 +1,59 @@ --- layout: default -title: Sharing resources between access roles +title: Resource sharing and access control parent: Access control -nav_order: 130 +nav_order: 110 +has_children: true +has_toc: false --- -# Resource Sharing and Access Control +# Resource sharing and access control **Introduced 3.3** {: .label .label-purple } -This feature is **experimental**. -{: .warning } +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/). +{: .warning} -The **Resource Sharing and Access Control** framework in the OpenSearch Security plugin provides *document-level*, fine-grained access management for plugin-defined resources. It extends OpenSearch’s existing role-based access control (RBAC) by letting resource owners explicitly share individual resources with other principals. +The resource sharing and access control framework in the OpenSearch Security plugin provides *document-level*, fine-grained access management for plugin-defined resources. It extends OpenSearch's existing role-based access control by letting resource owners explicitly share individual resources with other principals. -With this feature, you can: +A _resource_ is a document stored in a plugin's system index. Resource sharing information is stored in a central security-managed system index. -- Share or revoke access to your resources. -- Allow users with share permission to redistribute access. -- View and manage all shareable resources as a super administrator. -- Integrate shareable resource types through a standardized **Resource Sharing SPI**. -- Search resource indices with automatic per-user filtering applied by the Security plugin. +Resource sharing requires coordination between plugin developers, administrators, and users. Plugin developers must first implement resource sharing support in their plugins and define the resource types that can be shared (such as `ml-model-group` or `anomaly-detector`). Once plugins with resource sharing support are installed, administrators enable the feature cluster-wide and configure the resource types that use resource-level authorization. Finally, users can create and share resources through the UI or APIs, provided they have the necessary cluster permissions. -A **resource** is currently defined as a **document stored in a plugin’s system index**, and sharing information is stored in a **central security-managed system index**. +This documentation is intended for **users** and **administrators** who want to configure and use resource sharing. If you are a **plugin developer** implementing resource sharing support for your plugin, see the [developer documentation](https://github.com/opensearch-project/security/blob/main/RESOURCE_SHARING_AND_ACCESS_CONTROL.md). ---- +Resource sharing enables the following operations: -# Enabling resource sharing +- **Resource owners** can share or revoke access to their resources. +- **Resource owners** can allow users with share permission to redistribute access. +- **Administrators** with superadmin privileges can view and manage all shareable resources. +- **All users** can search resource indexes with automatic per-user filtering applied by the Security plugin. -The feature is controlled through the cluster settings configuration. +## Configuring resource sharing -## Cluster settings +Resource sharing is disabled by default. To configure resource sharing, follow these steps. -To enable resource sharing: +Before configuring resource sharing, ensure that the plugins you want to use with resource sharing have implemented resource sharing support. If you need to add resource sharing support to a plugin, see the [developer documentation](https://github.com/opensearch-project/security/blob/main/RESOURCE_SHARING_AND_ACCESS_CONTROL.md). +{: .note} -```yaml -plugins.security.experimental.resource_sharing.enabled: true -plugins.security.system_indices.enabled: true -``` -{% include copy.html %} - -### Protected resource types +### Step 1: Enable resource sharing -Administrators must list which resource types use resource-level authorization: +To enable resource sharing, add the following settings to the `opensearch.yml` file: ```yaml -plugins.security.experimental.resource_sharing.protected_types: ["sample-resource", "ml-model"] +plugins.security.experimental.resource_sharing.enabled: true +plugins.security.system_indices.enabled: true ``` {% include copy.html %} -These types must match the resource types declared by plugins implementing the `ResourceSharingExtension` SPI. +For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/). -### Dynamic updates (3.4+) +In OpenSearch 3.3, these settings can be updated only through `opensearch.yml` and require a cluster restart. -Starting with **3.4**, both settings can be updated dynamically: +Starting with OpenSearch 3.4, you can update both resource sharing settings dynamically without restarting the cluster: -``` +```json PUT _cluster/settings { "transient": { @@ -67,101 +64,77 @@ PUT _cluster/settings ``` {% include copy-curl.html %} -In **3.3**, these settings can be updated **only through `opensearch.yml`** and require a restart. - ---- +### Step 2: Configure protected resource types -# Required permissions - -Resource sharing requires plugin-specific cluster permissions. Add the following to `roles.yml`: +Specify the resource types that use resource-level authorization by listing them in the protected types configuration. This setting determines the plugin-defined resources that use the sharing and access control framework: ```yaml -sample_full_access: - cluster_permissions: - - 'cluster:admin/sample-resource-plugin/*' - -sample_read_access: - cluster_permissions: - - 'cluster:admin/sample-resource-plugin/get' +plugins.security.experimental.resource_sharing.protected_types: ["sample-resource", "ml-model"] ``` {% include copy.html %} -Users must have both: - -1. Cluster permissions for the plugin APIs -2. Resources shared with them through the sharing APIs - -Sharing alone does **not** grant API access. - ---- - -# Resource sharing components - -The resource sharing framework includes several internal components and APIs. - -## Service Provider Interface (SPI) +The resource types you specify must match exactly the resource types supported by your installed plugins. To discover the resource types available in your cluster, follow these steps: -Plugins integrate through the **`opensearch-security-spi`** package. +1. **Enable resource sharing** with an empty `protected_types` configuration initially. +2. **Use the [List resource types API]({{site.url}}{{site.baseurl}}/security/access-control/resource-sharing-api/#list-resource-types)** to discover all available resource types from your installed plugins. +3. **Update your `protected_types` configuration** with the resource types you want to enable. -Plugins must implement: +## Example resource types -* `ResourceSharingExtension` - Declares shareable resource types and system indices. -* `ResourceSharingClientAccessor` - Provides access to verification, sharing, and listing operations. +The following are example resource types available for resource sharing: -Plugins must also register: +- **ML Commons plugin:** + - `ml-model-group` - Machine learning model groups -``` -src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension -``` +- **Anomaly Detection plugin:** + - `anomaly-detector` - Anomaly detection jobs + - `forecaster` - Time series forecasting jobs -Containing only: +Example configuration after discovering available types: +```yaml +plugins.security.experimental.resource_sharing.protected_types: ["ml-model-group", "anomaly-detector", "forecaster"] ``` -com.example.MyResourceSharingExtension -``` - {% include copy.html %} -## resource-action-groups.yml +## Required permissions -Plugins define access levels using action groups: +To access shared resources through plugin APIs, users need cluster-level permissions for those specific plugins. Administrators should configure appropriate roles in `roles.yml`. The following example shows the configuration for a `sample-resource-plugin`: ```yaml -resource_types: - sample-resource: - sample_read_only: - allowed_actions: - - "cluster:admin/sample-resource-plugin/get" - - sample_read_write: - allowed_actions: - - "cluster:admin/sample-resource-plugin/*" +sample_full_access: + cluster_permissions: + - 'cluster:admin/sample-resource-plugin/*' + +sample_read_access: + cluster_permissions: + - 'cluster:admin/sample-resource-plugin/get' ``` +{% include copy.html %} -These action groups become the valid “access levels” a user may share. +Resource sharing does not automatically grant API access. To access a resource using the API, users must have both: ---- +1. Cluster permissions for the plugin APIs. +2. Resources shared with them through the sharing APIs. -# Data model +## Data model -All sharing metadata is stored in a dedicated *security-owned* system index. +All sharing metadata (listed in the following table) is stored in a dedicated *security-owned* system index. | Field | Description | -|---------------|------------------------------------------------| -| `resource_id` | Unique identifier of the resource | -| `created_by` | Creator username (and tenant if applicable) | -| `share_with` | Mapping of action-groups to allowed principals | -| `source_idx` | Resource index managed by the plugin | +|:---|:---| +| `resource_id` | The unique identifier of the resource. | +| `created_by` | The resource creator username (and tenant, if applicable). | +| `share_with` | The mapping of action groups to allowed principals. | +| `source_idx` | The resource index managed by the plugin. | -### Example document +This example shows a resource with ID `model-group-123` created by the user `bob` in the `analytics` tenant. The resource is shared with specific users, roles, and backend roles with read-only access: ```json { "resource_id": "model-group-123", "created_by": { - "user": "darshit", + "user": "bob", "tenant": "analytics" }, "share_with": { @@ -173,202 +146,72 @@ All sharing metadata is stored in a dedicated *security-owned* system index. } } ``` +{% include copy.html %} -To make a resource public: - -```json -{ - "share_with": { - "read_only": { - "users": ["*"] - } - } -} -``` -NOTE: Resource will be marked public only if "*" is added to user list. -{: .note} yellow - -To keep a resource private: - -```json -{ "share_with": {} } -``` - ---- - -# Access filtering for plugins - -When plugins perform a search on their system index: - -* The plugin performs the search using its system identity -* Security automatically filters documents based on: - - * resource owner - * shared principals - * privileges - -For example, only documents whose `all_shared_principals` list matches the authenticated user or roles will be returned. - -This filtering is done automatically if the plugin: - -* Implements `IdentityAwarePlugin` -* Uses system identity for index access (no `stashContext`) - ---- - -# Java APIs for plugins - -Plugins call the ResourceSharingClient to enforce access. - -### Verify resource access - -``` -client.verifyAccess(resourceId, resourceIndex, action, listener); -``` - -### List accessible resource IDs - -``` -client.getAccessibleResourceIds(resourceIndex, listener); -``` - -### Check if feature enabled for type - -``` -client.isFeatureEnabledForType(resourceType); -``` - ---- - -# REST APIs - -## 1. Share a resource - -Replace the entire sharing configuration. +In this example: -``` -PUT _plugins/_security/api/resource/share -{ - "resource_id": "123", - "resource_type": "sample-resource", - "share_with": { - "read_only": { - "users": ["alice"], - "roles": ["auditor"] - } - } -} -``` -{% include copy-curl.html %} +- Users: `alice` can access the resource. ---- +- Roles: Any user assigned the `data_viewer` role can access the resource. -## 2. Modify sharing configuration +- Backend roles: Any user mapped to the `analytics_backend` backend role can access the resource. -Add or revoke access. +To make this resource public, set `users` to `["*"]`: -``` -PATCH/POST _plugins/_security/api/resource/share +```json +PATCH _plugins/_security/api/resource/share { - "resource_id": "123", - "resource_type": "sample-resource", + "resource_id": "model-group-123", + "resource_type": "ml-model-group", "add": { - "read_only": { "users": ["bob"] } - }, - "revoke": { - "read_only": { "users": ["alice"] } + "read_only": { "users": ["*"] } } } ``` {% include copy-curl.html %} ---- - -## 3. Get sharing info - -``` -GET _plugins/_security/api/resource/share?resource_id=&resource_type= -``` -{% include copy-curl.html %} - ---- - -## 4. List resource types - -``` -GET _plugins/_security/api/resource/types -``` -{% include copy-curl.html %} - -Returns action groups declared by plugins. - ---- - -## 5. List accessible resources - -``` -GET _plugins/_security/api/resource/list?resource_type= -``` -{% include copy-curl.html %} - -Returns only resources visible to the caller. +To keep a resource private, make the `share_with` object empty: ---- - -## 6. Migration API (admin-only) - -Used once to import legacy plugin-managed sharing metadata. - -``` -POST _plugins/_security/api/resources/migrate +```json +PUT _plugins/_security/api/resource/share { - "source_index": "", - "username_path": "", # e.g. /owner/name - "backend_roles_path": "", # e.g. /owner/backend_roles - "default_owner": "some_user", - "default_access_level": { - "": "" # if resource-index has more than one resource type add more entries - } + "resource_id": "model-group-123", + "resource_type": "ml-model-group", + "share_with": {} } - ``` {% include copy-curl.html %} +## REST APIs ---- +You can use resource sharing API operations to share resources, manage access permissions, and automate resource sharing workflows. -# Restrictions +For complete API documentation, see [Resource sharing APIs]({{site.url}}{{site.baseurl}}/security/access-control/resource-sharing-api/). -* Only owners, super-admins and users with sharing access can share or revoke access. -* All resource indices must be system indices. -* System index protection must be enabled. -* Users still require plugin-level cluster permissions, specifically for creating resources. -* Action-groups must be declared in plugin configuration. - ---- +## Requirements and limitations -# Best practices +To ensure proper resource sharing and access control, the following requirements and limitations apply: -For developers: - -* Use SPI and ResourceSharingClient instead of custom ACL logic. -* Store only consistent resource types in a resource index. -* Use the implicit DLS filtering by running searches under system identity. +* Only resource owners, superadmins, or users explicitly granted sharing permissions can share or revoke access. +* All resources must reside in system indexes. +* System index protection must be enabled. +* Users still require plugin-level cluster permissions, including permission to create resources. +* Action groups must be defined in the plugin configuration. -For admins: -* Enable the feature on fresh clusters first. -* Keep system index protection enabled. -* Share resources minimally and explicitly. +## Best practices ---- +When managing resource sharing, administrators should follow these best practices: -# Conclusion +- Enable resource sharing on new clusters before usage. -The Resource Sharing and Access Control framework provides a unified and secure way to implement document-level access control for plugin-defined resources in OpenSearch. It introduces a standardized SPI, central sharing index, and new REST APIs for fine-grained authorization. +- Keep system index protection enabled. -For implementation examples, see the **sample-resource-plugin** in the security plugin repository. -For more detailed documentation on this feature, please see [RESOURCE_SHARING_AND_ACCESS_CONTROL.md](https://github.com/opensearch-project/security/blob/main/RESOURCE_SHARING_AND_ACCESS_CONTROL.md). +- Share resources minimally and explicitly to maintain security and control. ---- +## Related documentation +- [Resource sharing APIs]({{site.url}}{{site.baseurl}}/security/access-control/resource-sharing-api/) - REST API reference for programmatic management +- [Resource access management]({{site.url}}{{site.baseurl}}/dashboards/management/resource-sharing/) - UI workflows and user guidance +- [Sample resource plugin](https://github.com/opensearch-project/security/tree/main/src/test/java/org/opensearch/security/resources/sample) - Implementation examples in the security plugin repository +- [Developer documentation](https://github.com/opensearch-project/security/blob/main/RESOURCE_SHARING_AND_ACCESS_CONTROL.md) - Detailed technical documentation for plugin developers, users, and administrators diff --git a/_security/access-control/rest-layer-authz.md b/_security/access-control/rest-layer-authz.md index b882cf04e09..1c2c2cd06fd 100644 --- a/_security/access-control/rest-layer-authz.md +++ b/_security/access-control/rest-layer-authz.md @@ -2,7 +2,7 @@ layout: default title: REST layer authorization parent: Access control -nav_order: 80 +nav_order: 85 --- diff --git a/_security/access-control/users-roles.md b/_security/access-control/users-roles.md index 2910477182d..d5e115d5a21 100644 --- a/_security/access-control/users-roles.md +++ b/_security/access-control/users-roles.md @@ -2,7 +2,7 @@ layout: default title: Defining users and roles parent: Access control -nav_order: 85 +nav_order: 70 redirect_from: - /security/access-control/users-roles/ - /security-plugin/access-control/users-roles/