Users and roles

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.

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.

Unless you need to create new reserved or hidden users, 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.

---

Table of contents

1. Create users
   1. OpenSearch Dashboards
   2. internal_users.yml
   3. REST API
2. Create roles
   1. OpenSearch Dashboards
   2. roles.yml
   3. REST API
3. Map users to roles
   1. OpenSearch Dashboards
   2. roles_mapping.yml
   3. REST API
4. Predefined roles
5. Sample roles
   1. Set up a read-only user in OpenSearch Dashboards
   2. Set up a bulk access role in OpenSearch Dashboards

---

Create users

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.

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.

Create roles

Just like users, you can create roles using OpenSearch Dashboards, roles.yml, or the REST API.

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 indices, 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.

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

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.

Sample roles

The following examples demonstrate how you might set up a read-only role and a bulk access role.

Set up a read-only user in OpenSearch Dashboards

Create a new read_only_index role:

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

Map three roles to the read-only user:

1. Choose the Mapped users tab and Manage mapping.
2. For Internal users, add your read-only user.
3. Choose Map.
4. Repeat these steps for the opensearch_dashboards_user and opensearch_dashboards_read_only roles.

Set up 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.