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
Copy file name to clipboardExpand all lines: _data-prepper/pipelines/configuration/sinks/opensearch.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -159,7 +159,7 @@ Alternately, rather than admin credentials, you can specify the credentials of a
159
159
- Index: `.opendistro-ism-config`; Index permission: `indices_all`
160
160
- Index: `*`; Index permission: `manage_aliases`
161
161
162
-
For instructions on how to map users to roles, see [Map users to roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#map-users-to-roles).
162
+
For instructions on how to map users to roles, see [Map users to roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#mapping-users-to-roles).
Copy file name to clipboardExpand all lines: _security/access-control/users-roles.md
+80-56Lines changed: 80 additions & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,20 @@
1
1
---
2
2
layout: default
3
-
title: Users and roles
3
+
title: Defining users and roles
4
4
parent: Access control
5
5
nav_order: 85
6
6
redirect_from:
7
7
- /security/access-control/users-roles/
8
8
- /security-plugin/access-control/users-roles/
9
9
---
10
10
11
-
# Users and roles
11
+
# Defining users and roles
12
12
13
-
The Security plugin includes an internal user database. Use this database in place of or in addition to an external authentication system such as LDAP or Active Directory.
13
+
You define users in OpenSearch to control who has access to OpenSearch data. You can use the internal user database to store users, or you can store them in an external authentication system, such as [LDAP or Active Directory]({{site.url}}{{site.baseurl}}/security/authentication-backends/ldap/).
14
14
15
-
Roles are the core way of controlling access to your cluster. Roles contain any combination of cluster-wide permissions, index-specific permissions, document- and field-level security, and tenants. Then you map users to these roles so that users gain those permissions.
15
+
You define roles to determine the scope of a permission or action group. You can create roles with specific privileges, for example, roles that contain any combination of cluster-wide permissions, index-specific permissions, document- and field-level security, and tenants.
16
+
17
+
You can map users to roles during user creation or after users and roles have been defined. This mapping determines the permissions and access levels for each user based on the roles they are assigned.
16
18
17
19
---
18
20
@@ -27,30 +29,13 @@ Roles are the core way of controlling access to your cluster. Roles contain any
27
29
28
30
---
29
31
30
-
## Creating and editing OpenSearch roles
31
-
32
-
You can update OpenSearch by using one of the following methods.
33
-
34
-
### Using the API
35
-
36
-
You can send HTTP requests to OpenSearch-provided endpoints to update security roles, permissions, and associated settings. This method offers granular control and automation capabilities for managing roles.
37
-
38
-
### Using the UI (OpenSearch Dashboards)
39
-
40
-
OpenSearch Dashboards provides a user-friendly interface for managing roles. Roles, permissions, and document-level security settings are configured in the Security section within OpenSearch Dashboards. When updating roles through the UI, OpenSearch Dashboards calls the API in the background to implement the changes.
41
-
42
-
### Editing the `roles.yml` file
32
+
## Defining users
43
33
44
-
If you want more granular control of your security configuration, you can edit roles and their associated permissions in the `roles.yml` file. This method provides direct access to the underlying configuration and can be version controlled for use in collaborative development environments.
45
-
For more information about creating roles, see the [Create roles](https://opensearch.org/docs/latest/security/access-control/users-roles/#create-roles) documentation.
34
+
You can define users by using OpenSearch Dashboards, `internal_users.yml`, or the REST API. When creating users, you can map users to roles by using `internal_users.yml` or the REST API. If you are using OpenSearch Dashboards to define users, follow the steps in the [Map users to roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#mapping-users-to-roles) tutorial.
46
35
47
-
Unless you need to create new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources), we **highly** recommend using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use.
36
+
Unless you are defining new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources), using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings is recommended. The `.yml` files are for initial setup and are not for ongoing use.
48
37
{: .warning }
49
38
50
-
## Create users
51
-
52
-
You can create users using OpenSearch Dashboards, `internal_users.yml`, or the REST API. When creating a user, you can map users to roles using `internal_users.yml` or the REST API, but that feature is not currently available in OpenSearch Dashboards.
53
-
54
39
### OpenSearch Dashboards
55
40
56
41
1. Choose **Security**, **Internal Users**, and **Create internal user**.
@@ -61,7 +46,7 @@ You can create users using OpenSearch Dashboards, `internal_users.yml`, or the R
61
46
62
47
1. Choose **Submit**.
63
48
64
-
### internal_users.yml
49
+
### `internal_users.yml`
65
50
66
51
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#internal_usersyml).
67
52
@@ -71,10 +56,12 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#inter
71
56
See [Create user]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-user).
72
57
73
58
74
-
## Create roles
59
+
## Defining roles
75
60
76
-
Just like users, you can create roles using OpenSearch Dashboards, `roles.yml`, or the REST API.
61
+
Similarly to defining users, you can define roles using OpenSearch Dashboards, `roles.yml`, or the REST API. OpenSearch provides predefined roles and a special read-only role.
77
62
63
+
Unless you are defining new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources), using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings is recommended. The `.yml` files are for initial setup and are not for ongoing use.
64
+
{: .warning }
78
65
79
66
### OpenSearch Dashboards
80
67
@@ -87,7 +74,7 @@ Just like users, you can create roles using OpenSearch Dashboards, `roles.yml`,
87
74
1. Choose **Submit**.
88
75
89
76
90
-
### roles.yml
77
+
### `roles.yml`
91
78
92
79
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).
93
80
@@ -96,7 +83,7 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles
96
83
97
84
See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
98
85
99
-
## Edit roles
86
+
## Editing roles
100
87
101
88
You can edit roles using one of the following methods.
102
89
@@ -107,15 +94,15 @@ You can edit roles using one of the following methods.
107
94
1. Choose **edit role**. Make any necessary updates to the role.
108
95
1. To save your changes, select **Update**.
109
96
110
-
### roles.yml
97
+
### `roles.yml`
111
98
112
99
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).
113
100
114
101
### REST API
115
102
116
103
See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
117
104
118
-
## Map users to roles
105
+
## Mapping users to roles
119
106
120
107
If you didn't specify roles when you created your user, you can map roles to it afterwards.
121
108
@@ -129,7 +116,7 @@ Just like users and roles, you create role mappings using OpenSearch Dashboards,
129
116
1. Choose **Map**.
130
117
131
118
132
-
### roles_mapping.yml
119
+
### `roles_mapping.yml`
133
120
134
121
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles_mappingyml).
135
122
@@ -138,6 +125,65 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles
138
125
139
126
See [Create role mapping]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role-mapping).
140
127
128
+
## Defining read-only roles
129
+
130
+
A read-only role grants a user the ability to read data from the OpenSearch cluster but not to modify or delete any data. The read-only role is useful when you want to provide access to data for reporting, analysis, or visualization purposes without allowing modifications to the data or the cluster itself. This maintains data integrity and prevents accidental or unauthorized changes.
131
+
132
+
As with any role in OpenSearch, a read-only role can be configured using the following methods:
133
+
134
+
- Using OpenSearch Dashboards
135
+
- Modifying the `yml` configuration files
136
+
- Using the Cluster Settings API
137
+
138
+
The simplest way to get familiar with roles and role mappings is to use OpenSearch Dashboards. The interface simplifies creating roles and assigning those roles to users, with an easy-to-navigate workflow.
139
+
{ .tip}
140
+
141
+
### Defining a basic read-only role
142
+
143
+
To create a basic read-only role that allows a user to access OpenSearch Dashboards, view existing dashboards and visualizations, and query different indexes, use the following permissions. These permissions give the user access to all tenants and indexes on the cluster.
144
+
145
+
146
+
#### Cluster permissions
147
+
148
+
For a user requiring read-only access to cluster-wide resources, such as visualizations or dashboards, add the `cluster_composite_ops_ro` permission to that user's role.
149
+
150
+
#### Index permissions
151
+
152
+
A user requiring access to view visualizations will also require access to the index used to create the visualization. To give a user read-only access to all indexes, specify all (`*`) under the **Index** dropdown and **Read** in **Index Permissions**.
153
+
154
+
#### Tenant permissions
155
+
156
+
If you use tenants to split work between teams or projects, use the all (`*`) option followed by the **Read only** option, as shown in the following image.
After setting all permission types and defining the role, you can map the role directly to a user on the role's **Mapped users** tab. Select **Map users** and then choose a user to map to the role, as shown in the following image.
The OpenSearch Dashboards `readonly_mode` functionality is used to give a user access to the `Dashboards` interface only, removing all other UI elements from view.
167
+
168
+
To configure this role, add the following line to your `opensearch_dashboards.yml` file:
Even if the assigned role grants additional privileges or a user is mapped to other roles with write access to indexes, OpenSearch Dashboards restricts this access. Direct access to OpenSearch data using CURL or API is still allowed. OpenSearch Dashboards is not involved in this communication.
173
+
174
+
If a user is mapped to the `readonly_mode` role, all other elements of the UI will be removed, except for `Dashboards`. In the following image, the view on the left shows the screen from the perspective of a user mapped to a `readonly_mode` role. The view on the right shows a user's standard view.
175
+
176
+

177
+
178
+
Mapping a user to only the `readonly_mode` role does not allow them to view relevant indexes or existing dashboards. Read access to indexes and dashboards requires separate permissions.
179
+
{: .note }
180
+
181
+
182
+
If a user is also mapped to any role listed under `plugins.security.restapi.roles_enabled` in `opensearch.yml`, for example, `all_access` or `security_rest_api_access`, then `readonly_mode` is ignored, giving them access to the standard UI elements.
183
+
184
+
### Additional permissions
185
+
186
+
If a user requires permissions in addition to those included in the `read_only` role, such as for alerting or anomaly detection tasks, you can assign predefined roles, such as `alerting_read_access` or `anomaly_read_access`.
141
187
142
188
## Predefined roles
143
189
@@ -177,31 +223,9 @@ The Security plugin includes several predefined roles that serve as useful defau
177
223
For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in [Default action groups]({{site.url}}{{site.baseurl}}/security/access-control/default-action-groups/).
178
224
179
225
180
-
## Sample roles
181
-
182
-
The following examples demonstrate how you might set up a read-only role and a bulk access role.
183
-
184
-
### Set up a read-only user in OpenSearch Dashboards
185
-
186
-
Create a new `read_only_index` role:
187
-
188
-
1. Open OpenSearch Dashboards.
189
-
1. Choose **Security**, **Roles**.
190
-
1. Create a new role named `read_only_index`.
191
-
1. For **Cluster permissions**, add the `cluster_composite_ops_ro` action group.
192
-
1. For **Index Permissions**, add an index pattern. For example, you might specify `my-index-*`.
193
-
1. For index permissions, add the `read` action group.
194
-
1. Choose **Create**.
195
-
196
-
Map three roles to the read-only user:
197
-
198
-
1. Choose the **Mapped users** tab and **Manage mapping**.
199
-
1. For **Internal users**, add your read-only user.
200
-
1. Choose **Map**.
201
-
1. Repeat these steps for the `opensearch_dashboards_user` and `opensearch_dashboards_read_only` roles.
202
-
226
+
## Example
203
227
204
-
### Set up a bulk access role in OpenSearch Dashboards
228
+
The following tutorial describes the steps for creating a bulk access role in OpenSearch Dashboards.
Copy file name to clipboardExpand all lines: _security/authentication-backends/client-auth.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,11 +41,11 @@ clientcert_auth_domain:
41
41
type: noop
42
42
```
43
43
44
-
## Assigning roles to your common name
44
+
## Assigning roles to a certificate's common name
45
45
46
-
You can now assign your certificate's common name (CN) to a role. For this step, you must know your certificate's CN and the role you want to assign to. To get a list of all predefined roles in OpenSearch, refer to our [list of predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#predefined-roles). If you want to first create a role, refer to [how to create a role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#create-users), and then map your certificate's CN to that role.
46
+
You can now assign your certificate's common name (CN) to a role. This step requires you to identify the certificate's CN and the role you want to assign it to. To view a list of all predefined OpenSearch roles, see [Predefined roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#predefined-roles). To get started, first [define a role]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#defining-roles) and then map your certificate's CN to that role.
47
47
48
-
After deciding which role you want to map your certificate's CN to, you can use [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#map-users-to-roles), [`roles_mapping.yml`]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles_mappingyml), or the [REST API]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role-mapping) to map your certificate's CN to the role. The following example uses the `REST API` to map the common name `CLIENT1` to the role `readall`.
48
+
After determining which role to map to your certificate's CN, you can use [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#mapping-users-to-roles), [`roles_mapping.yml`]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles_mappingyml), or the [REST API]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role-mapping) to map the role. The following example uses the `REST API` to map the CN `CLIENT1` to the role `readall`.
Copy file name to clipboardExpand all lines: _security/configuration/yaml.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -165,7 +165,7 @@ plugins.security.restapi.password_validation_error_message: "Password must be mi
165
165
166
166
In addition, a score-based password strength estimator allows you to set a threshold for password strength when creating a new internal user or updating a user's password. This feature makes use of the [zxcvbn library](https://github.com/dropbox/zxcvbn) to apply a policy that emphasizes a password's complexity rather than its capacity to meet traditional criteria such as uppercase keys, numerals, and special characters.
167
167
168
-
For information about creating users, see [Create users]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#create-users).
168
+
For information about defining users, see [Defining users]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#defining-users).
169
169
170
170
This feature is not compatible with users specified as reserved. For information about reserved resources, see [Reserved and hidden resources]({{site.url}}{{site.baseurl}}/security/access-control/api#reserved-and-hidden-resources).
Copy file name to clipboardExpand all lines: _tuning-your-cluster/replication-plugin/permissions.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,7 +32,7 @@ If you don't want to use the default roles, you can combine individual replicati
32
32
The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#create-replication-rule) operations are special cases. They involve background processes on the leader and follower clusters that must be associated with roles. When you perform one of these actions, you must explicitly pass the `leader_cluster_role` and
33
33
`follower_cluster_role` in the request, which OpenSearch then uses in all backend replication tasks.
34
34
35
-
To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#map-users-to-roles).
35
+
To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For a tutorial, see [Mapping users to roles]({{site.url}}{{site.baseurl}}/security/access-control/users-roles/#mapping-users-to-roles).
36
36
37
37
Then add those roles to the request, and sign it with the appropriate credentials:
0 commit comments