You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
12
25
13
-
Available from version 3.0.0 on fresh clusters only.
14
-
{: .info }
26
+
### Plugin settings
15
27
16
-
Marked experimental and is disabled by default.
17
-
{: .warning }
28
+
To enable resource sharing, add the following settings to `opensearch.yaml`:
18
29
19
-
To enable, set:
20
30
```yaml
21
31
plugins.security.resource_sharing.enabled: true
32
+
plugins.security.system_indices.enabled: true
22
33
```
23
-
{: .note }
34
+
{% include copy.html %}
24
35
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).
26
37
{: .tip }
27
38
28
-
## 1. Overview
39
+
### Cluster permissions
29
40
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:
31
42
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.
33
45
34
-
Resource owners share and revoke access
46
+
To grant the resource sharing extension these permissions, add the following role to `roles.yaml`:
35
47
36
-
Super-admins view and manage all resources
48
+
```yaml
49
+
sample_full_access:
50
+
cluster_permissions:
51
+
- 'cluster:admin/sample-resource-plugin/*'
37
52
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 %}
39
58
40
-
---
59
+
## Resource sharing components
41
60
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.
43
62
44
-
### 2.1 `opensearch-security-spi`
63
+
### opensearch-security-spi
45
64
46
-
A Service Provider Interface (SPI) that:
65
+
The `opensearch-security-spi` component:
47
66
48
67
- Defines `ResourceSharingExtension` for plugin implementations.
49
68
- Tracks registered resource plugins at startup.
50
69
- Exposes a `ResourceSharingClient` for performing share, revoke, verify, and list operations.
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:
75
72
76
-
---
73
+
```
74
+
com.example.MyResourceSharingExtension
75
+
```
76
+
{% include copy.html %}
77
+
78
+
### API
77
79
78
-
## 3. API Design
80
+
All sharing metadata is stored in the `.opensearch_resource_sharing` system index, as shown in the following table.
79
81
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 |
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:
90
113
91
114
```json
92
115
{
@@ -104,92 +127,47 @@ All sharing metadata is stored in the system index `.opensearch_resource_sharing
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 (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": ["*"]
140
143
}
141
144
}
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
+
}
164
146
```
147
+
{% include copy.html %}
165
148
166
-
### 5.2 Access Rules
149
+
To keep a resource private, keep the `share_with` array empty:
167
150
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 %}
171
155
172
-
---
156
+
## Restrictions
173
157
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:
175
159
176
160
- 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.
178
162
- Disabling system index protection exposes resources to direct index-level access.
179
163
180
-
---
164
+
## Best practices
181
165
182
-
## 7. Best Practices
166
+
To ensure secure and efficient implementation of resource sharing and access control, follow these recommended practices:
183
167
184
168
- Declare and register extensions correctly.
185
169
- Use the SPI client APIs instead of manual index queries.
186
170
- 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.
0 commit comments