Creating Cluster Users and Granting Permissions

How the Feature Works

CSS security-mode clusters implement fine-grained access control based on the opendistro_security plugin. With the RBAC model at its core, this plugin implements authorization through the chain of users → role mappings → roles → permissions.

Figure 1 RBAC authorization model

RBAC answers the question "Who can do what in the cluster?", while Tenant addresses the question "What OpenSearch Dashboards objects can users see and edit?" RBAC and Tenant work together to provide fine-grained access control. RBAC determines the operations that users can perform on cluster resources, while Tenant controls the visibility and sharing of OpenSearch Dashboards resources, such as dashboards and visualizations. Three tenant types are available to define the visibility of Kibana resources.

Constraints

• Usernames, role names, and tenant names must be unique.
• You are advised not to use the same name for indexes and users. This helps avoid permission management confusion.

Prerequisites

• The security mode has been enabled for your cluster. Only security-mode OpenSearch clusters support user permission management.
• You have obtained the administrator account. The username is admin and the password is the administrator password configured when the cluster was created.

Logging In to the Security Page of OpenSearch Dashboards

Log in to the Security page of Kibana using the administrator account to manage cluster permissions.

1. Log in to the CSS management console.
2. In the navigation pane on the left, choose Clusters > OpenSearch.
3. In the cluster list, find the target cluster, and click Dashboards in the Operation column to log in to OpenSearch Dashboards using the admin account.
4. After successful login, choose Security from the navigation pane on the left. The permission management page is displayed.

Creating a User

Create a new cluster user. The user can then be mapped to roles to be granted the corresponding permissions.

1. On the Security page, choose Internal users from the navigation pane on the left.
2. On the Internal Users page, click Create internal user.
3. On the Create internal user page, configure the required parameters.

   Table 3 User configuration

   Parameter	Mandatory (Yes/No)	Description
   Username	Yes	Username. In this example, enter test.
   Password/Re-enter password	Yes	Enter and confirm the login password. The two passwords must be identical.
   Backend roles	No	Backend role names from an external authentication system (such as LDAP or SAML). Backend roles are used to map external users to security roles. For details, click Learn more on the page.
   Attributes	No	Custom user attributes. They can be used as dynamic variables in document-level security (DLS) queries to implement fine-grained data access control based on user attributes. For details, click Learn more on the page.

4. Click Create.

   After the user is created, it is displayed in the Internal Users list.

Creating a Role and Defining Its Permissions

Define a role and specify the operations that the role is allowed to perform on clusters and indexes, as well as the scope of these operations. The permissions defined in the role can then be granted to users by mapping the role to them.

The system provides multiple predefined roles (such as kibana_user and readall). If the predefined roles meet your requirements, you are advised to use them directly instead of creating new ones.

1. On the Security page, choose Roles from the navigation pane on the left.
2. On the Roles page, click Create Role.
3. On the Create Role page, configure the required parameters.

   Table 4 Role configuration

   Parameter	Mandatory (Yes/No)	Description
   Name	Yes	Role name. In this example, enter role_test.
   Cluster permissions	No	Cluster-level permissions. Select a predefined action group, such as cluster_monitor (read-only cluster monitoring) or cluster_manage (cluster management). In this example, select cluster_monitor. The cluster_monitor action group allows users to view cluster status in read-only mode, including cluster health, node information, and statistics, but does not allow modification operations. Leaving this parameter blank means not to grant any cluster-level permissions.
   Index Permissions	No	Index-level permissions. Set the following parameters: Index: Mandatory. The index name or wildcard pattern to which permissions are granted, such as my_store or logs-*. Index permissions: Mandatory. Operations allowed on the index, such as read and write. Document Level Security: Optional. Sets document-level filters so that users with this role can only access documents that meet the specified conditions. Field Level Security: Optional. Sets field allowlists or blocklists to control which fields are visible to users. Anonymization: Optional. Specifies fields that need to be anonymized to protect data security.
   Tenant Permissions	No	Tenant permissions. Tenant patterns: Specifies tenant spaces that users can access, such as global_tenant or custom tenant names. Permissions: Tenant space permissions, which can be Read only or Read and Write.

4. Click Create.

   After the role is created, it is displayed in the Roles list.

Mapping Roles to Users

Map roles to users to grant users all permissions associated with the mapped roles.

1. On the Security > Roles page, click a role name, such as role_test. The role details page is displayed.
2. Click the Mapped users tab and then click Manage mapping.
3. On the Map user page, click the drop-down list box next to Users and select the target user, for example, test.
   

   A role can be mapped to multiple users. You can also use Backend roles to batch-map user groups from external authentication systems.

4. Click Map to complete the role mapping.

   After the mapping is successful, the target user test is displayed in the Mapped users list.

Verifying User Permissions

Log in to the cluster as the new user and perform operations to verify that the user's permission configuration has taken effect as expected.

1. Log out of the current admin account and log in to OpenSearch Dashboards again using the username test and the configured password.
2. On Kibana, expand the menu in the upper-left corner, and choose Dev Tools.
3. Run the following two commands to verify that user test has the permissions granted by role role_test, that is, only the cluster_monitor permission.
   • Query cluster health status.

     GET /_cluster/health?pretty

     Expected result: HTTP status code 200 is returned and cluster health information is displayed, indicating that the cluster_monitor permission has taken effect.

   • Create an index.

     PUT /my_test

     Expected result: HTTP status code 403 Forbidden is returned, indicating that user test does not have permission to create indexes and permission isolation is working.

     

     If you need to grant user test the permission to create indexes, add the corresponding permission (for example, indices:admin/create) to Index Permissions of role_test based on the permission name in the 403 error message. You do not need to create a new user.

Common Role Permission Configuration Examples

In real-world scenarios, users in different roles require different levels of permissions. This section provides role permission configurations for some common scenarios. You can refer to these examples when configuring roles.

• Read-only access to index data

  Scenario: Common users need to query data in specified indexes through OpenSearch Dashboards but are not allowed to perform any write, update, or delete operations. They are also not allowed to perform cluster-level operations, preventing accidental operations that may affect production data.

  User permission configuration: Map the user to the role role_index_readonly.

  Table 6 Permission configuration for read-only access to index data

  Configuration Item	Sub-Configuration Item	Description
  Name	-	Role name: role_index_readonly
  Cluster permissions	-	Not configured. No cluster-level permissions are required.
  Index Permissions	Index	Target index name or wildcard.
  	Index permissions	Select the predefined action group read (document read), which includes the following permissions: indices:data/read/search (_search) indices:data/read/get (_get) indices:data/read/mget (_mget) indices:data/read/scroll (_scroll) indices:admin/mappings/fields/get* (view field mappings)

  Permission verification:

  # Expected success (search for documents)
  GET /my_store/_search
  { "query": { "match_all": {} } }
  
  # Expected failure (no write permission)
  POST /my_store/_doc
  { "name": "test" }
  
  # Expected failure (no cluster-level permissions)
  GET /_cluster/health?pretty

• Read/write access to index data

  Scenario: Common users need to write, update, and query data in specified indexes through OpenSearch Dashboards but are not allowed to create or delete indexes or modify index mappings and other structural configurations. This ensures that index structures are managed by dedicated personnel.

  User permission configuration: Map the user to the role role_index_readwrite.

  Table 7 Permission configuration for read/write access to index data

  Configuration Item	Sub-Configuration Item	Description
  Name	-	Role name: role_index_readwrite
  Cluster permissions	-	Not configured. No cluster-level permissions are required.
  Index Permissions	Index	Target index name or wildcard.
  	Index permissions	Select the predefined action groups read (document read) and write (document write). The read action group includes the following permissions: indices:data/read/search (_search) indices:data/read/get (_get) indices:data/read/mget (_mget) indices:data/read/scroll (_scroll) indices:admin/mappings/fields/get* (view field mappings) The write action group includes the following permissions: indices:data/write/index (create/replace documents) indices:data/write/update (update documents) indices:data/write/delete (delete documents) indices:data/write/bulk (batch write)

  Permission verification:

  # Expected success (query documents)
  GET /my_store/_search
  { "query": { "match_all": {} } }
  
  # Expected success (write documents)
  POST /my_store/_doc
  { "product": "laptop", "price": 5999 }
  
  # Expected success (delete a document)
  DELETE /my_store/_doc/1
  
  # Expected failure (no index creation permission)
  PUT /my_store_v2
  
  # Expected failure (no index deletion permission)
  DELETE /my_store
  
  # Expected failure (no cluster-level permissions)
  GET /_cluster/health?pretty

• Read-only cluster monitoring

  Scenario: O&M personnel or automated inspection scripts need to periodically collect monitoring data such as cluster health status, node loads, and shard distribution. However, they are not allowed to modify cluster status or perform read/write operations on index data, preventing inspection accounts from being misused.

  User permission configuration: Map the user to the role role_index_monitor.

  Table 8 Permission configuration for read-only cluster monitoring

  Configuration Item	Sub-Configuration Item	Description
  Name	-	Role name: role_index_monitor
  Cluster permissions	-	Select the predefined action group cluster_monitor (read-only cluster monitoring), which includes the following permissions: cluster:monitor/health (cluster health status) cluster:monitor/stats (cluster statistics) cluster:monitor/nodes/info (node information) cluster:monitor/nodes/stats (node statistics) cluster:monitor/task/get (task information) cluster:monitor/pending_tasks (pending tasks)
  Index Permissions	Index	Set to * to view the status of all indexes.
  	Index permissions	Select the predefined action group indices_monitor (read-only index monitoring), which includes the following permissions: indices:monitor/stats (index statistics) indices:monitor/segments (segment information) indices:monitor/recovery (recovery information) indices:monitor/shard_stores (shard storage information)

  Permission verification:

  # Expected success (cluster health status)
  GET /_cluster/health?pretty
  
  # Expected success (index statistics)
  GET /my_store/_stats
  
  # Expected failure (no document query permissions)
  GET /my_store/_search
  { "query": { "match_all": {} } }
  
  # Expected failure (no permission to modify the cluster configuration)
  PUT /_cluster/settings
  { "persistent": { "cluster.routing.allocation.enable": "none" } }

• Index and document management

  Scenario: Microservice applications or data pipeline service accounts need to use REST APIs to perform full index lifecycle management in OpenSearch, including index creation, index deletion, index settings updates, and mapping updates, as well as document CRUD operations. Because these accounts are used by applications rather than human users, it is recommended that you clearly define the data scope to reduce potential data security risks.

  User permission configuration: Map the user to the role role_api_service.

  Table 9 Permission configuration for index and document management

  Configuration Item	Sub-Configuration Item	Description
  Name	-	Role name: role_api_service
  Cluster permissions	-	Not configured. No cluster-level permissions are required for pure data operations.
  Index Permissions	Index	Use wildcards to specify the scope of indexes, for example, log-*.
  	Index permissions	Select the following predefined action groups/permissions: read (document read) write (document write) indices:admin/create (create indexes) indices:admin/delete (delete indexes) indices:admin/settings/update (modify index settings) indices:admin/mapping/put (add or modify index mappings)

  Permission verification:

  # Expected success (create an index)
  PUT /log-v1
  {
    "settings": { "number_of_shards": 3, "number_of_replicas": 1 }
  }
  
  # Expected success (modify index settings)
  PUT /log-v1/_settings
  {
    "index": { "number_of_replicas": 2 }
  }
  
  # Expected success (modify index mappings)
  PUT /log-v1/_mapping
  {
    "properties": { "new_field": { "type": "keyword" } }
  }
  
  # Expected success (write documents)
  POST /log-v1/_doc
  { "user_id": "u001", "action": "login" }
  
  # Expected success (query documents)
  GET /log-v1/_search
  { "query": { "match_all": {} } }
  
  # Expected success (delete a document)
  DELETE /log-v1/_doc/1
  
  # Expected success (delete an index)
  DELETE /log-v1
  
  # Expected failure (no cluster-level permissions)
  GET /_cluster/health?pretty

• Dashboard editing (read/write)

  Scenario: BI developers or O&M engineers need to create and modify dashboards, visualizations, and index patterns in OpenSearch Dashboards.

  User permission configuration: Map the user to roles kibana_user and role_dashboard_editor.

  Table 10 Permission configuration for dashboard editing

  Configuration Item	Sub-Configuration Item	Description
  Name	-	Role name: role_dashboard_editor
  Cluster permissions	-	Not configured. No cluster-level permissions are required.
  Index Permissions	Index	Target index name or wildcard, for example, log-*.
  	Index permissions	Select the predefined action groups read (document read) and write (document write).
  Tenant Permissions	Tenant patterns	Leave this blank or specify a custom tenant name. By default, the role kibana_user has the global_tenant permission, so a custom role does not have to be configured here. To isolate tenant spaces, specify a custom tenant name, for example, test_tenant.
  	Permissions	If a custom tenant is specified, select Read and Write to grant read/write permissions for dashboards in the tenant.

  Permission verification:

  Log in to OpenSearch Dashboards using an account assigned these roles and switch the tenant to Global.

  • You can view, create, and edit dashboards and visualizations.
  • You can create new index patterns.
  • You cannot access the Security page for permission management. (The all_access role is required to access this page.)

FAQ: What predefined roles are available in the system?

• kibana_user: Allows users to create and view dashboards in OpenSearch Dashboards. This role has the global_tenant permissions by default.
• readall: Grants read-only access to all indexes. It is suitable for data analysts.
• all_access: Grants administrator permissions. Assign this role with caution.

On the Roles page, click Learn more to view descriptions of all predefined roles.