Skip to content

Commit 5f98cb8

Browse files
AntonEliatrastephen-crawfordNaarcha-AWShdhaltervagimeli
authored
Add read-only role page to documents opensearch-project#5783 (opensearch-project#6806)
* adding read-only role page to documents opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * fixing vale errors on read-only page opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * Update _security/access-control/read-only-role.md Co-authored-by: Stephen Crawford <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * Update _security/access-control/read-only-role.md Co-authored-by: Stephen Crawford <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * applying the suggested fixed to read only mode page opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * adding section on restapi roles to readonly_mode opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * adding section on restapi roles to readonly_mode opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * Apply suggestions from code review Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * moving read only role content into Users and Roles page#5783 Signed-off-by: AntonEliatra <[email protected]> * moving read only role content into Users and Roles page#5783 Signed-off-by: AntonEliatra <[email protected]> * moving read only role content into Users and Roles page#5783 Signed-off-by: AntonEliatra <[email protected]> * moving read only role content into Users and Roles page#5783 Signed-off-by: AntonEliatra <[email protected]> * moving read only role content into Users and Roles page#5783 Signed-off-by: AntonEliatra <[email protected]> * Update users-roles.md Made some info architecture changes to topic Signed-off-by: Heather Halter <[email protected]> * Update users-roles.md Tweaked the wording in the 'example' section Signed-off-by: Heather Halter <[email protected]> * Update users-roles.md Signed-off-by: AntonEliatra <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * Update users-roles.md Signed-off-by: AntonEliatra <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * Update _security/access-control/users-roles.md Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Signed-off-by: Heather Halter <[email protected]> * fixing broken links opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * removing duplicate details from user-role page opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * Apply suggestions from code review Co-authored-by: Heather Halter <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * Update users-roles.md Added link to https://opensearch.org/docs/latest/security/authentication-backends/ldap/ Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Apply suggestions from code review Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Apply suggestions from code review Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Apply suggestions from code review Co-authored-by: Melissa Vagi <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update _security/access-control/users-roles.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Apply suggestions from code review Editorial fixes. Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Heather Halter <[email protected]> * Update users-roles.md Editorial fix Signed-off-by: Heather Halter <[email protected]> * Apply suggestions from code review Co-authored-by: Heather Halter <[email protected]> Signed-off-by: AntonEliatra <[email protected]> * adding reference to images opensearch-project#5783 Signed-off-by: AntonEliatra <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: AntonEliatra <[email protected]> --------- Signed-off-by: AntonEliatra <[email protected]> Signed-off-by: Heather Halter <[email protected]> Co-authored-by: Stephen Crawford <[email protected]> Co-authored-by: Naarcha-AWS <[email protected]> Co-authored-by: Heather Halter <[email protected]> Co-authored-by: Melissa Vagi <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
1 parent f65203a commit 5f98cb8

File tree

10 files changed

+86
-62
lines changed

10 files changed

+86
-62
lines changed

_data-prepper/pipelines/configuration/sinks/opensearch.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ Alternately, rather than admin credentials, you can specify the credentials of a
159159
- Index: `.opendistro-ism-config`; Index permission: `indices_all`
160160
- Index: `*`; Index permission: `manage_aliases`
161161

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).
163163

164164
## Amazon OpenSearch Service domain security
165165

_security/access-control/users-roles.md

Lines changed: 80 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
11
---
22
layout: default
3-
title: Users and roles
3+
title: Defining users and roles
44
parent: Access control
55
nav_order: 85
66
redirect_from:
77
- /security/access-control/users-roles/
88
- /security-plugin/access-control/users-roles/
99
---
1010

11-
# Users and roles
11+
# Defining users and roles
1212

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/).
1414

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.
1618

1719
---
1820

@@ -27,30 +29,13 @@ Roles are the core way of controlling access to your cluster. Roles contain any
2729

2830
---
2931

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
4333

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.
4635

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.
4837
{: .warning }
4938

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-
5439
### OpenSearch Dashboards
5540

5641
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
6146

6247
1. Choose **Submit**.
6348

64-
### internal_users.yml
49+
### `internal_users.yml`
6550

6651
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#internal_usersyml).
6752

@@ -71,10 +56,12 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#inter
7156
See [Create user]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-user).
7257

7358

74-
## Create roles
59+
## Defining roles
7560

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.
7762

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 }
7865

7966
### OpenSearch Dashboards
8067

@@ -87,7 +74,7 @@ Just like users, you can create roles using OpenSearch Dashboards, `roles.yml`,
8774
1. Choose **Submit**.
8875

8976

90-
### roles.yml
77+
### `roles.yml`
9178

9279
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).
9380

@@ -96,7 +83,7 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles
9683

9784
See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
9885

99-
## Edit roles
86+
## Editing roles
10087

10188
You can edit roles using one of the following methods.
10289

@@ -107,15 +94,15 @@ You can edit roles using one of the following methods.
10794
1. Choose **edit role**. Make any necessary updates to the role.
10895
1. To save your changes, select **Update**.
10996

110-
### roles.yml
97+
### `roles.yml`
11198

11299
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).
113100

114101
### REST API
115102

116103
See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
117104

118-
## Map users to roles
105+
## Mapping users to roles
119106

120107
If you didn't specify roles when you created your user, you can map roles to it afterwards.
121108

@@ -129,7 +116,7 @@ Just like users and roles, you create role mappings using OpenSearch Dashboards,
129116
1. Choose **Map**.
130117

131118

132-
### roles_mapping.yml
119+
### `roles_mapping.yml`
133120

134121
See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles_mappingyml).
135122

@@ -138,6 +125,65 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles
138125

139126
See [Create role mapping]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role-mapping).
140127

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.
157+
158+
![creating role]({{site.url}}{{site.baseurl}}/images/role_creation_read_only.png)
159+
160+
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.
161+
162+
![mapping users]({{site.url}}{{site.baseurl}}/images/mapping-users.png)
163+
164+
### OpenSearch Dashboards `readonly_mode`
165+
166+
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:
169+
170+
```opensearch_security.readonly_mode.roles: [new_role]```
171+
172+
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+
![compare read only mode]({{site.url}}{{site.baseurl}}/images/compare_read_only_mode.png)
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`.
141187

142188
## Predefined roles
143189

@@ -177,31 +223,9 @@ The Security plugin includes several predefined roles that serve as useful defau
177223
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/).
178224

179225

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
203227

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.
205229

206230
Create a new `bulk_access` role:
207231

_security/authentication-backends/client-auth.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,11 @@ clientcert_auth_domain:
4141
type: noop
4242
```
4343

44-
## Assigning roles to your common name
44+
## Assigning roles to a certificate's common name
4545

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.
4747

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`.
4949

5050
**Example request**
5151

_security/configuration/yaml.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ plugins.security.restapi.password_validation_error_message: "Password must be mi
165165

166166
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.
167167

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).
169169

170170
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).
171171
{: .important }

_tuning-your-cluster/replication-plugin/permissions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ If you don't want to use the default roles, you can combine individual replicati
3232
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
3333
`follower_cluster_role` in the request, which OpenSearch then uses in all backend replication tasks.
3434

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).
3636

3737
Then add those roles to the request, and sign it with the appropriate credentials:
3838

images/compare_read_only_mode.png

370 KB
Loading

images/creating-user.png

287 KB
Loading

images/kibanauser.png

45.1 KB
Loading

images/mapping-users.png

238 KB
Loading

images/role_creation_read_only.png

172 KB
Loading

0 commit comments

Comments
 (0)