Skip to content

Commit b30434b

Browse files
authored
Add tech writer review.
1 parent a8f0fc1 commit b30434b

File tree

1 file changed

+99
-121
lines changed

1 file changed

+99
-121
lines changed

_security/access-control/resources.md

Lines changed: 99 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,115 @@
11
---
22
layout: default
3-
title: Resource Sharing and Access Control
3+
title: Sharing resources between access roles
44
parent: Access control
55
nav_order: 130
66
---
77

8-
# Resource Sharing and Access Control
8+
# Sharing resources between access roles
9+
910
**Introduced 3.0**
1011
{: .label .label-purple }
1112

13+
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/).
14+
{: .warning}
15+
16+
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:
17+
18+
- Share and revoke access as a resource owner.
19+
- View and manage all resources as a super-admin.
20+
- Define custom shareable resources through a standardized Service Provider Interface (SPI).
21+
22+
## Enabling the resource sharing extension
23+
24+
To enable the resource sharing extension, follow these steps.
1225

13-
Available from version 3.0.0 on fresh clusters only.
14-
{: .info }
26+
### Plugin settings
1527

16-
Marked experimental and is disabled by default.
17-
{: .warning }
28+
To enable resource sharing, add the following settings to `opensearch.yaml`:
1829

19-
To enable, set:
2030
```yaml
2131
plugins.security.resource_sharing.enabled: true
32+
plugins.security.system_indices.enabled: true
2233
```
23-
{: .note }
34+
{% include copy.html %}
2435
25-
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)
36+
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).
2637
{: .tip }
2738
28-
## 1. Overview
39+
### Cluster permissions
2940
30-
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.
41+
The Security plugin must have the following access:
3142
32-
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:
43+
- Permissions to make share, verify, and list requests.
44+
- Shared access to all cluster components, or be the owner of the cluster.
3345
34-
Resource owners share and revoke access
46+
To grant the resource sharing extension these permissions, add the following role to `roles.yaml`:
3547

36-
Super-admins view and manage all resources
48+
```yaml
49+
sample_full_access:
50+
cluster_permissions:
51+
- 'cluster:admin/sample-resource-plugin/*'
3752
38-
Plugin authors define custom shareable resources via a standardized SPI interface
53+
sample_read_access:
54+
cluster_permissions:
55+
- 'cluster:admin/sample-resource-plugin/get'
56+
```
57+
{% include copy.html %}
3958

40-
---
59+
## Resource sharing components
4160

42-
## 2. Components
61+
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.
4362

44-
### 2.1 `opensearch-security-spi`
63+
### opensearch-security-spi
4564

46-
A Service Provider Interface (SPI) that:
65+
The `opensearch-security-spi` component:
4766

4867
- Defines `ResourceSharingExtension` for plugin implementations.
4968
- Tracks registered resource plugins at startup.
5069
- Exposes a `ResourceSharingClient` for performing share, revoke, verify, and list operations.
5170

52-
#### Plugin Requirements
53-
54-
##### 1. Feature Flag and Protection
55-
- Enable `plugins.security.resource_sharing.enabled: true`
56-
- Resource indices must be system indices with system index protection enabled (`plugins.security.system_indices.enabled: true`).
57-
58-
##### 2. Build Configuration
59-
Add to `build.gradle`:
60-
```gradle
61-
compileOnly group: 'org.opensearch', name: 'opensearch-security-spi', version: "${opensearch_build}"
62-
opensearchplugin {
63-
name '<your-plugin>'
64-
description '<description>'
65-
classname '<your.classpath>'
66-
extendedPlugins = ['opensearch-security;optional=true']
67-
}
68-
```
69-
70-
##### 3. SPI Registration
71-
Create `src/main/resources/META-INF/services/org.opensearch.security.spi.ResourceSharingExtension` containing your implementation’s fully qualified class name:
72-
```
73-
com.example.MyResourceSharingExtension
74-
```
71+
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:
7572

76-
---
73+
```
74+
com.example.MyResourceSharingExtension
75+
```
76+
{% include copy.html %}
77+
78+
### API
7779

78-
## 3. API Design
80+
All sharing metadata is stored in the `.opensearch_resource_sharing` system index, as shown in the following table.
7981

80-
All sharing metadata is stored in the system index `.opensearch_resource_sharing`.
82+
| Field | Type | Description |
83+
| :--- | :--- | :--- |
84+
| `source_idx` | String | The system index holding the resource |
85+
| `resource_id` | String | The resource ID |
86+
| `created_by` | Object | The name of the user who created the resource |
87+
| `share_with` | Object | A map of `action-groups` to access definitions |
8188

82-
| Field | Type | Description |
83-
| ------------- | ------ | ------------------------------------------- |
84-
| `source_idx` | String | System index holding the resource |
85-
| `resource_id` | String | Unique resource identifier |
86-
| `created_by` | Object | Creator information |
87-
| `share_with` | Object | Map of action-groups to access definitions |
89+
#### Java client APIs
8890

89-
### 3.1 Document Structure
91+
Use the following classes when interacting with the extension through the Java client:
92+
93+
```java
94+
ResourceSharingClient client = ResourceSharingClientAccessor.getResourceSharingClient();
95+
96+
// Verify access
97+
client.verifyResourceAccess(resourceId, indexName, listener);
98+
99+
// Share resource
100+
client.share(resourceId, indexName, recipients, listener);
101+
102+
// Revoke access
103+
client.revoke(resourceId, indexName, recipients, listener);
104+
105+
// List accessible IDs
106+
client.getAccessibleResourceIds(indexName, listener);
107+
```
108+
{% include copy.html %}
109+
110+
### Document structure
111+
112+
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:
90113

91114
```json
92115
{
@@ -104,92 +127,47 @@ All sharing metadata is stored in the system index `.opensearch_resource_sharing
104127
}
105128
}
106129
```
130+
{% include copy.html %}
107131

108-
### 3.2 Java Client APIs
132+
## Action groups
109133

110-
```java
111-
ResourceSharingClient client = ResourceSharingClientAccessor.getResourceSharingClient();
112-
113-
// 1. Verify access
114-
client.verifyResourceAccess(resourceId, indexName, listener);
134+
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:
115135

116-
// 2. Share resource
117-
client.share(resourceId, indexName, recipients, listener);
118-
119-
// 3. Revoke access
120-
client.revoke(resourceId, indexName, recipients, listener);
121-
122-
// 4. List accessible IDs
123-
client.getAccessibleResourceIds(indexName, listener);
124-
```
125-
126-
---
127-
128-
## 4. Action Groups
129-
130-
- Action-groups define permission levels (currently only default).
131-
- To make a resource public, use wildcards:
132-
```json
133-
{
134-
"share_with": {
135-
"default": {
136-
"users": ["*"],
137-
"roles": ["*"],
138-
"backend_roles": ["*"]
139-
}
136+
```json
137+
{
138+
"share_with": {
139+
"default": {
140+
"users": ["*"],
141+
"roles": ["*"],
142+
"backend_roles": ["*"]
140143
}
141144
}
142-
```
143-
- To keep a resource private (only owner and super-admin):
144-
```json
145-
{ "share_with": {} }
146-
```
147-
148-
---
149-
150-
## 5. User and Admin Setup
151-
152-
### 5.1 Cluster Permissions
153-
154-
In `roles.yml`, grant plugin API permissions:
155-
156-
```yaml
157-
sample_full_access:
158-
cluster_permissions:
159-
- 'cluster:admin/sample-resource-plugin/*'
160-
161-
sample_read_access:
162-
cluster_permissions:
163-
- 'cluster:admin/sample-resource-plugin/get'
145+
}
164146
```
147+
{% include copy.html %}
165148

166-
### 5.2 Access Rules
149+
To keep a resource private, keep the `share_with` array empty:
167150

168-
1. Must have plugin API permission to call share, verify, or list.
169-
2. Resource must be shared or the user must be the owner to grant access.
170-
3. No additional index permissions are needed; system indices are protected.
151+
```json
152+
{ "share_with": {} }
153+
```
154+
{% include copy.html %}
171155

172-
---
156+
## Restrictions
173157

174-
## 6. Restrictions
158+
Before implementing resource sharing and access control, be aware of the following limitations that help maintain security and consistency across the system:
175159

176160
- Only resource owners or super-admins can share or revoke access.
177-
- Resources must reside in system indices.
161+
- Resources must reside in system indexes.
178162
- Disabling system index protection exposes resources to direct index-level access.
179163

180-
---
164+
## Best practices
181165

182-
## 7. Best Practices
166+
To ensure secure and efficient implementation of resource sharing and access control, follow these recommended practices:
183167

184168
- Declare and register extensions correctly.
185169
- Use the SPI client APIs instead of manual index queries.
186170
- Enable only on fresh 3.0.0+ clusters to avoid upgrade issues.
187-
- Grant minimal required scope when sharing.
188-
189-
---
190-
191-
## 8. Additional Notes
171+
- Grant minimal required permissions when sharing resources.
192172

193-
- Requires `plugins.security.resource_sharing.enabled: true`.
194-
- Relies on system index protection (`plugins.security.system_indices.enabled: true`).
195-
- Experimental feature subject to future API changes.
173+
These practices help maintain security, improve maintainability, and prevent potential issues during upgrades or system changes.

0 commit comments

Comments
 (0)