You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Defining users and roles

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.

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.

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.

---

Table of contents

• Defining users
  • OpenSearch Dashboards
  • internal_users.yml
  • REST API
• Defining roles
  • OpenSearch Dashboards
  • roles.yml
  • REST API
• Editing roles
  • OpenSearch Dashboards
  • roles.yml
  • REST API
• Mapping users to roles
  • OpenSearch Dashboards
  • roles_mapping.yml
  • REST API
• Defining read-only roles
  • Defining a basic read-only role
  • OpenSearch Dashboards readonly_mode
  • Additional permissions
• Predefined roles
• Example

---

Defining users

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

Unless you are defining new reserved or hidden users, 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.

OpenSearch Dashboards

1. Choose Security, Internal Users, and Create internal user.
2. Provide a username and password. The Security plugin automatically hashes the password and stores it in the .opendistro_security index.

3. If desired, specify user attributes.

   Attributes are optional user properties that you can use for variable substitution in index permissions or document-level security.

4. Choose Submit.

internal_users.yml

See YAML files.

REST API

See Create user.

Defining roles

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.

Unless you are defining new reserved or hidden users, 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.

OpenSearch Dashboards

1. Choose Security, Roles, and Create role.
2. Provide a name for the role.

3. Add permissions as desired.

   For example, you might give a role no cluster permissions, read permissions to two indexes, unlimited permissions to a third index, and read permissions to the analysts tenant.

4. Choose Submit.

roles.yml

See YAML files.

REST API

See Create role.

Editing roles

You can edit roles using one of the following methods.

OpenSearch Dashboards

1. Choose Security > Roles. In the Create role section, select Explore existing roles.
2. Select the role you want to edit.
3. Choose edit role. Make any necessary updates to the role.
4. To save your changes, select Update.

roles.yml

See YAML files.

REST API

See Create role.

Mapping users to roles

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

Just like users and roles, you create role mappings using OpenSearch Dashboards, roles_mapping.yml, or the REST API.

OpenSearch Dashboards

1. Choose Security, Roles, and a role.
2. Choose the Mapped users tab and Manage mapping.
3. Specify users or external identities (also known as backend roles).
4. Choose Map.

roles_mapping.yml

See YAML files.

REST API

See Create role mapping.

Defining read-only roles

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.

As with any role in OpenSearch, a read-only role can be configured using the following methods:

• Using OpenSearch Dashboards
• Modifying the yml configuration files
• Using the Cluster Settings API

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. { .tip}

Defining a basic read-only role

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.

Cluster permissions

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.

Index permissions

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.

Tenant permissions

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.

OpenSearch Dashboards readonly_mode

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.

To configure this role, add the following line to your opensearch_dashboards.yml file:

opensearch_security.readonly_mode.roles: [new_role]

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.

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.

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.

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.

Additional permissions

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.

Predefined roles

The Security plugin includes several predefined roles that serve as useful defaults.

For more detailed summaries of the permissions for each role, reference their action groups against the descriptions in Default action groups.

Example

The following tutorial describes the steps for creating a bulk access role in OpenSearch Dashboards.

Create a new bulk_access role:

1. Open OpenSearch Dashboards.
2. Choose Security, Roles.
3. Create a new role named bulk_access.
4. For Cluster permissions, add the cluster_composite_ops action group.
5. For Index Permissions, add an index pattern. For example, you might specify my-index-*.
6. For index permissions, add the write action group.
7. Choose Create.

Map the role to your user:

1. Choose the Mapped users tab and Manage mapping.
2. For Internal users, add your bulk access user.
3. Choose Map.