Permissions

Each permission in the Security plugin controls access to some action that the OpenSearch cluster can perform, such as indexing a document or checking cluster health.

Most permissions are self-describing. For example, cluster:admin/ingest/pipeline/get lets you retrieve information about ingest pipelines. In many cases, a permission correlates to a specific REST API operation, such as GET _ingest/pipeline.

Despite this correlation, permissions do not directly map to REST API operations. Operations such as POST _bulk and GET _msearch can access many indexes and perform many actions in a single request. Even a simple request, such as GET _cat/nodes, performs several actions in order to generate its response.

In short, controlling access to the REST API is insufficient. Instead, the Security plugin controls access to the underlying OpenSearch actions.

For example, consider the following _bulk request:

  1. POST _bulk
  2. { "delete": { "_index": "test-index", "_id": "tt2229499" } }
  3. { "index": { "_index": "test-index", "_id": "tt1979320" } }
  4. { "title": "Rush", "year": 2013 }
  5. { "create": { "_index": "test-index", "_id": "tt1392214" } }
  6. { "title": "Prisoners", "year": 2013 }
  7. { "update": { "_index": "test-index", "_id": "tt0816711" } }
  8. { "doc" : { "title": "World War Z" } }

For this request to succeed, you must have the following permissions for test-index:

  • indices:data/write/bulk*
  • indices:data/write/delete
  • indices:data/write/index
  • indices:data/write/update

These permissions also allow you add, update, or delete documents (e.g. PUT test-index/_doc/tt0816711), because they govern the underlying OpenSearch actions of indexing and deleting documents rather than a specific API path and HTTP method.

Test permissions

If you want a user to have the absolute minimum set of permissions necessary to perform some function—the principle of least privilege—the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the Security plugin is very explicit about which permissions are missing. Consider this request and response:

  1. GET _cat/shards?v
  2. {
  3. "error": {
  4. "root_cause": [{
  5. "type": "security_exception",
  6. "reason": "no permissions for [indices:monitor/stats] and User [name=test-user, backend_roles=[], requestedTenant=null]"
  7. }]
  8. },
  9. "status": 403
  10. }

Create a user and a role, map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds.

Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See Default action groups for descriptions of the permissions that each group grants.

System index permissions

System index permissions are unique among other permissions in that they extend some traditional admin-only accessibility to non-admin users. These permissions give normal users the ability to modify any system index specified in the role or roles to which they are mapped. The exception to this is the security system index, .opendistro_security, which is used to store the Security plugin’s configuration YAML files and remains accessible only to admins with an admin certificate.

Along with standard index permissions, you specify system index permissions in the roles.yml configuration file under index_permissions (see roles.yml). This involves a two-step process: 1) adding the system index in the index_patterns section and 2) specifying system:admin/system_index in the role’s allowed_actions section.

For example, the system index permission that gives a user permission to modify the system index that stores configurations for the Alerting plugin is defined by the index pattern .opendistro-alerting-config, and its allowed action is defined as system:admin/system_index. The following role shows how this system index permission is configured along with other attributes:

  1. alerting-role:
  2. reserved: true
  3. hidden: false
  4. cluster_permissions:
  5. - 'cluster:admin/opendistro/alerting/alerts/ack'
  6. - 'cluster:admin/opendistro/alerting/alerts/get'
  7. index_permissions:
  8. - index_patterns:
  9. - .opendistro-alerting-config
  10. - allowed_actions:
  11. - 'system:admin/system_index'

copy

System index permissions also work with the wildcard to include all variations of a partial system index name. This can be useful, but it should be used with caution to avoid giving unintentional access to system indexes. When specifying system indexes for roles, keep the following considerations in mind:

  • Specifying the full name of a system index limits access to only that index: .opendistro-alerting-config.
  • Specifying a partial name for a system index along with the wildcard provides access to all system indexes that begin with that name: .opendistro-anomaly-detector*.
  • Although not recommended—given the wide-reaching access granted by this role definition—using * for the index pattern along with system:admin/system_index as an allowed action grants access to all system indexes.

    Entering the wildcard * by itself under allowed_actions does not automatically grant access to system indexes. The allowed action system:admin/system_index must be explicitly added.

The following example shows a role that grants access to all system indexes:

  1. index_permissions:
  2. - index_patterns:
  3. - '*'
  4. - allowed_actions:
  5. - 'system:admin/system_index'

Verifying system index access

You can use the CAT indices operation to see all indexes associated with any index pattern in your permissions configuration and verify that the permissions provide the access you intended. For example, if you want to verify a permission that includes system indexes beginning with the prefix .kibana, you can run the GET /_cat/indices/.kibana* call to return all indexes associated with that prefix.

The following example response shows the three system indexes associated with the index pattern .kibana*:

  1. health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
  2. green open .kibana_1 XmTePICFRoSNf5O5uLgwRw 1 1 220 0 468.3kb 232.1kb
  3. green open .kibana_2 XmTePICFRoSNf5O5uLgwRw 1 1 220 0 468.3kb 232.1kb
  4. green open .kibana_3 XmTePICFRoSNf5O5uLgwRw 1 1 220 0 468.3kb 232.1kb

Enabling system index permissions

Users that have the permission restapi:admin/roles are able to map system index permissions to all users in the same way they would for a cluster or index permission in the roles.yml file. However, to preserve some control over this permission, the plugins.security.system_indices.permission.enabled setting allows you to enable or disable the system index permissions feature. This setting is disabled by default. To enable the system index permissions feature, set plugins.security.system_indices.permissions.enabled to true. For more information about this setting, see Enabling user access to system indexes.

Keep in mind that enabling this feature and mapping system index permissions to normal users gives those users access to indexes that may contain sensitive information and configurations essential to a cluster’s health. We also recommend caution when mapping users to restapi:admin/roles because this permission gives a user not only the ability to assign the system index permission to another user but also the ability to self-assign access to any system index.

do_not_fail_on_forbidden

If a user attempts to query multiple indexes, some of which they lack permissions for, by default they get an error in the OpenSearch Dashboards UI or an exception when using cURL or an API. If you instead want the user to receive the search results for any of the indexes for which they do have permissions, you can set the option do_not_fail_on_forbidden to true in config.yml. See the following example:

  1. _meta:
  2. type: "config"
  3. config_version: 2
  4. config:
  5. dynamic:
  6. http:
  7. anonymous_auth_enabled: false
  8. xff:
  9. enabled: false
  10. internalProxies: "192\\.168\\.0\\.10|192\\.168\\.0\\.11"
  11. do_not_fail_on_forbidden: true
  12. authc:
  13. basic_internal_auth_domain:
  14. ...

It is important to remember that if this option is set to true, then the user is served the data as if it is the complete dataset. There is no indication that some data may be omitted.

do_not_fail_on_forbidden_empty

When a user attempts to view a visualization for which they lack index permissions, they will see error in place of the visualization. To change this behavior to display No results displayed because all values equal 0., you can set do_not_fail_on_forbidden_empty to true in config.yml. This option is only valid if do_not_fail_on_forbidden is also set to true. See the following example:

  1. _meta:
  2. type: "config"
  3. config_version: 2
  4. config:
  5. dynamic:
  6. http:
  7. anonymous_auth_enabled: false
  8. xff:
  9. enabled: false
  10. internalProxies: "192\\.168\\.0\\.10|192\\.168\\.0\\.11"
  11. do_not_fail_on_forbidden: true
  12. do_not_fail_on_forbidden_empty: true
  13. authc:
  14. basic_internal_auth_domain:
  15. ...

Cluster permissions

These permissions are for the cluster and can’t be applied granularly. For example, you either have permissions to take snapshots (cluster:admin/snapshot/create) or you don’t. The cluster permission, therefore, cannot grant a user privileges to take snapshots of a select set of indexes while preventing the user from taking snapshots of others.

Cross-references to API documentation in the permissions that follow are only intended to provide an understanding of the permissions. As stated at the beginning of this section, permissions often correlate to APIs but do not map directly to them.

Cluster wide index permissions

PermissionDescription
indices:admin/template/deletePermission to delete index templates.
indices:admin/template/getPermission to get index templates.
indices:admin/template/putPermission to create index templates.
indices:data/read/scrollPermission to scroll through data. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/scroll/clearPermission to clear the scroll object. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/mgetPermission to run multiple GET operations in one request.
indices:data/read/mgetPermission to run multiple GET operations in one request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/msearchPermission to run multiple search requests in a single API request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/msearch/templatePermission to bundle multiple search templates and send them to your OpenSearch cluster in a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/mtvPermission to retrieve multiple term vectors with a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/mtvPermission to retrieve multiple term vectors with a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/search/template/renderPermission to render search templates. This setting must be configured as both a cluster- and index-level permission.
indices:data/write/bulkPermission to run a bulk request. This setting must be configured as both a cluster- and index-level permission.
indices:data/write/bulk*Permission to run a bulk request. This setting must be configured as both a cluster- and index-level permission.
indices:data/write/reindexPermission to run a reindex operation.

Ingest API permissions

See Ingest APIs.

  • cluster:admin/ingest/pipeline/delete
  • cluster:admin/ingest/pipeline/get
  • cluster:admin/ingest/pipeline/put
  • cluster:admin/ingest/pipeline/simulate
  • cluster:admin/ingest/processor/grok/get

Anomaly detection permissions

See Anomaly Detection API.

  • cluster:admin/opendistro/ad/detector/delete
  • cluster:admin/opendistro/ad/detector/info
  • cluster:admin/opendistro/ad/detector/jobmanagement
  • cluster:admin/opendistro/ad/detector/preview
  • cluster:admin/opendistro/ad/detector/run
  • cluster:admin/opendistro/ad/detector/search
  • cluster:admin/opendistro/ad/detector/stats
  • cluster:admin/opendistro/ad/detector/write
  • cluster:admin/opendistro/ad/detector/validate
  • cluster:admin/opendistro/ad/detectors/get
  • cluster:admin/opendistro/ad/result/search
  • cluster:admin/opendistro/ad/result/topAnomalies
  • cluster:admin/opendistro/ad/tasks/search

Alerting permissions

See Alerting API.

  • cluster:admin/opendistro/alerting/alerts/ack
  • cluster:admin/opendistro/alerting/alerts/get
  • cluster:admin/opendistro/alerting/destination/delete
  • cluster:admin/opendistro/alerting/destination/email_account/delete
  • cluster:admin/opendistro/alerting/destination/email_account/get
  • cluster:admin/opendistro/alerting/destination/email_account/search
  • cluster:admin/opendistro/alerting/destination/email_account/write
  • cluster:admin/opendistro/alerting/destination/email_group/delete
  • cluster:admin/opendistro/alerting/destination/email_group/get
  • cluster:admin/opendistro/alerting/destination/email_group/search
  • cluster:admin/opendistro/alerting/destination/email_group/write
  • cluster:admin/opendistro/alerting/destination/get
  • cluster:admin/opendistro/alerting/destination/write
  • cluster:admin/opendistro/alerting/monitor/delete
  • cluster:admin/opendistro/alerting/monitor/execute
  • cluster:admin/opendistro/alerting/monitor/get
  • cluster:admin/opendistro/alerting/monitor/search
  • cluster:admin/opendistro/alerting/monitor/write
  • cluster:admin/opensearch/alerting/remote/indexes/get

Asynchronous Search permissions

See Asynchronous search.

  • cluster:admin/opendistro/asynchronous_search/stats
  • cluster:admin/opendistro/asynchronous_search/delete
  • cluster:admin/opendistro/asynchronous_search/get
  • cluster:admin/opendistro/asynchronous_search/submit

Index State Management permissions

See ISM API.

  • cluster:admin/opendistro/ism/managedindex/add
  • cluster:admin/opendistro/ism/managedindex/change
  • cluster:admin/opendistro/ism/managedindex/remove
  • cluster:admin/opendistro/ism/managedindex/explain
  • cluster:admin/opendistro/ism/managedindex/retry
  • cluster:admin/opendistro/ism/policy/write
  • cluster:admin/opendistro/ism/policy/get
  • cluster:admin/opendistro/ism/policy/search
  • cluster:admin/opendistro/ism/policy/delete

Index rollups permissions

See Index rollups API.

  • cluster:admin/opendistro/rollup/index
  • cluster:admin/opendistro/rollup/get
  • cluster:admin/opendistro/rollup/search
  • cluster:admin/opendistro/rollup/delete
  • cluster:admin/opendistro/rollup/start
  • cluster:admin/opendistro/rollup/stop
  • cluster:admin/opendistro/rollup/explain

Reporting permissions

See Creating reports with the Dashboards interface.

  • cluster:admin/opendistro/reports/definition/create
  • cluster:admin/opendistro/reports/definition/update
  • cluster:admin/opendistro/reports/definition/on_demand
  • cluster:admin/opendistro/reports/definition/delete
  • cluster:admin/opendistro/reports/definition/get
  • cluster:admin/opendistro/reports/definition/list
  • cluster:admin/opendistro/reports/instance/list
  • cluster:admin/opendistro/reports/instance/get
  • cluster:admin/opendistro/reports/menu/download

Transform job permissions

See Transforms APIs

  • cluster:admin/opendistro/transform/index
  • cluster:admin/opendistro/transform/get
  • cluster:admin/opendistro/transform/preview
  • cluster:admin/opendistro/transform/delete
  • cluster:admin/opendistro/transform/start
  • cluster:admin/opendistro/transform/stop
  • cluster:admin/opendistro/transform/explain

Observability permissions

See Observability security.

  • cluster:admin/opensearch/observability/create
  • cluster:admin/opensearch/observability/update
  • cluster:admin/opensearch/observability/delete
  • cluster:admin/opensearch/observability/get

Cross-cluster replication

See Cross-cluster replication security.

  • cluster:admin/plugins/replication/autofollow/update

Reindex

See Reindex document.

  • cluster:admin/reindex/rethrottle

Snapshot repository permissions

See Snapshot APIs.

  • cluster:admin/repository/delete
  • cluster:admin/repository/get
  • cluster:admin/repository/put
  • cluster:admin/repository/verify

Reroute

See Cluster manager task throttling.

  • cluster:admin/reroute

Script permissions

See Script APIs.

  • cluster:admin/script/delete
  • cluster:admin/script/get
  • cluster:admin/script/put

Update settings permission

See Update settings on the Index APIs page.

  • cluster:admin/settings/update

Snapshot permissions

See Snapshot APIs.

  • cluster:admin/snapshot/create
  • cluster:admin/snapshot/delete
  • cluster:admin/snapshot/get
  • cluster:admin/snapshot/restore
  • cluster:admin/snapshot/status
  • cluster:admin/snapshot/status*

Task permissions

See Tasks in the API Reference section.

  • cluster:admin/tasks/cancel
  • cluster:admin/tasks/test
  • cluster:admin/tasks/testunblock

Data source permissions

See Data sources

  • cluster:admin/opensearch/ql/datasources/create
  • cluster:admin/opensearch/ql/datasources/read
  • cluster:admin/opensearch/ql/datasources/update
  • cluster:admin/opensearch/ql/datasources/delete
  • cluster:admin/opensearch/ql/datasources/patch
  • cluster:admin/opensearch/ql/async_query/create
  • cluster:admin/opensearch/ql/async_query/result
  • cluster:admin/opensearch/ql/async_query/delete

Security Analytics permissions

See API tools.

PermissionDescription
cluster:admin/opensearch/securityanalytics/alerts/getPermission to get alerts
cluster:admin/opensearch/securityanalytics/alerts/ackPermission to acknowledge alerts
cluster:admin/opensearch/securityanalytics/detector/getPermission to get detectors
cluster:admin/opensearch/securityanalytics/detector/searchPermission to search detectors
cluster:admin/opensearch/securityanalytics/detector/writePermission to create and update detectors
cluster:admin/opensearch/securityanalytics/detector/deletePermission to delete detectors
cluster:admin/opensearch/securityanalytics/findings/getPermission to get findings
cluster:admin/opensearch/securityanalytics/mapping/getPermission to get field mappings by index
cluster:admin/opensearch/securityanalytics/mapping/view/getPermission to get field mappings by index and view mapped and unmapped fields
cluster:admin/opensearch/securityanalytics/mapping/createPermission to create field mappings
cluster:admin/opensearch/securityanalytics/mapping/updatePermission to update field mappings
cluster:admin/opensearch/securityanalytics/rules/categoriesPermission to get all rule categories
cluster:admin/opensearch/securityanalytics/rule/writePermission to create and update rules
cluster:admin/opensearch/securityanalytics/rule/searchPermission to search for rules
cluster:admin/opensearch/securityanalytics/rules/validatePermission to validate rules
cluster:admin/opensearch/securityanalytics/rule/deletePermission to delete rules

Monitoring permissions

Cluster permissions for monitoring the cluster apply to read-only operations, such as checking cluster health and getting information about usage on nodes or tasks running in the cluster.

See REST API reference.

  • cluster:monitor/allocation/explain
  • cluster:monitor/health
  • cluster:monitor/main
  • cluster:monitor/nodes/hot_threads
  • cluster:monitor/nodes/info
  • cluster:monitor/nodes/liveness
  • cluster:monitor/nodes/stats
  • cluster:monitor/nodes/usage
  • cluster:monitor/remote/info
  • cluster:monitor/state
  • cluster:monitor/stats
  • cluster:monitor/task
  • cluster:monitor/task/get
  • cluster:monitor/tasks/lists

Index templates

The index template permissions are for indexes but apply globally to the cluster.

See Index templates.

  • indices:admin/index_template/delete
  • indices:admin/index_template/get
  • indices:admin/index_template/put
  • indices:admin/index_template/simulate
  • indices:admin/index_template/simulate_index

Index permissions

These permissions apply to an index or index pattern. You might want a user to have read access to all indexes (that is, *), but write access to only a few (for example, web-logs and product-catalog).

PermissionDescription
indices:admin/aliasesPermissions for index aliases.
indices:admin/aliases/getPermission to get index aliases.
indices:admin/analyzePermission to use the Analyze API.
indices:admin/cache/clearPermission to clear cache.
indices:admin/closePermission to close an index.
indices:admin/closePermission to close an index.
indices:admin/createPermission to create indexes.
indices:admin/data_stream/createPermission to create data streams.
indices:admin/data_stream/deletePermission to delete data streams.
indices:admin/data_stream/getPermission to get data streams.
indices:admin/deletePermission to delete indexes.
indices:admin/existsPermission to use exists query.
indices:admin/flushPermission to flush an index.
indices:admin/flushPermission to flush an index.
indices:admin/forcemergePermission to force merge indexes and data streams.
indices:admin/getPermission to get index and mapping.
indices:admin/mapping/putPermission to add new mappings and fields to an index.
indices:admin/mappings/fields/getPermission to get mappings fields.
indices:admin/mappings/fields/getPermission to get mappings fields.
indices:admin/mappings/getPermission to get mappings.
indices:admin/openPermission to open an index.
indices:admin/plugins/replication/index/setup/validatePermission to validate a connection to a remote cluster.
indices:admin/plugins/replication/index/startPermission to start cross-cluster replication.
indices:admin/plugins/replication/index/pausePermission to pause cross-cluster replication.
indices:admin/plugins/replication/index/resumePermission to resume cross-cluster replication.
indices:admin/plugins/replication/index/stopPermission to stop cross-cluster replication.
indices:admin/plugins/replication/index/updatePermission to update cross-cluster replication settings.
indices:admin/plugins/replication/index/status_checkPermission to check the status of cross-cluster replication.
indices:admin/refreshPermission to use the index refresh API.
indices:admin/refreshPermission to use the index refresh API.
indices:admin/resolve/indexPermission to resolve index names, index aliases and data streams.
indices:admin/rolloverPermission to perform index rollover.
indices:admin/seq_no/global_checkpoint_syncPermission to perform a global checkpoint sync.
indices:admin/settings/updatePermission to update index settings.
indices:admin/shards/search_shardsPermission to perform cross cluster search.
indices:admin/upgradePermission for administrators to perform upgrades.
indices:admin/validate/queryPermission to validate a specific query.
indices:data/read/explainPermission to run the Explain API.
indices:data/read/field_capsPermission to run the Field Capabilities API.
indices:data/read/field_capsPermission to run the Field Capabilities API.
indices:data/read/getPermission to read index data.
indices:data/read/mgetPermission to run multiple GET operations in one request.
indices:data/read/mgetPermission to run multiple GET operations in one request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/msearchPermission to run multiple search requests in a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/msearch/templatePermission to bundle multiple search templates and send them to your OpenSearch cluster in a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/mtvPermission to retrieve multiple term vectors with a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/mtvPermission to retrieve multiple term vectors with a single request. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/plugins/replication/file_chunkPermission to check files during segment replication.
indices:data/read/plugins/replication/changesPermission to make changes to segment replication settings.
indices:data/read/scrollPermission to scroll through data. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/scroll/clearPermission to clear the scroll object. This setting must be configured as both a cluster- and index-level permission.
indices:data/read/searchPermission to search data.
indices:data/read/searchPermission to search data.
indices:data/read/search/templatePermission to read a search template.
indices:data/read/tvPermission to retrieve information and statistics for terms in the fields of a particular document.
indices:data/write/deletePermission to delete documents.
indices:data/write/delete/byqueryPermission to delete all documents that match a query.
indices:data/write/plugins/replication/changesPermission to change data replication configurations and settings within indexes.
indices:data/write/bulkPermission to run a bulk request. This setting must be configured as both a cluster- and index-level permission.
indices:data/write/bulk*Permission to run a bulk request. This setting must be configured as both a cluster- and index-level permission.
indices:data/write/indexPermission to add documents to existing indexes. See also Index document.
indices:data/write/updatePermission to update an index.
indices:data/write/update/byqueryPermission to run the script to update all of the documents that match the query.
indices:monitor/data_stream/statsPermission to stream stats.
indices:monitor/recoveryPermission to access recovery stats.
indices:monitor/segmentsPermission to access segment stats.
indices:monitor/settings/getPermission to get mointor settings.
indices:monitor/shard_storesPermission to access shard store stats.
indices:monitor/statsPermission to access monitoring stats.
indices:monitor/upgradePermission to access upgrade stats.

Security REST permissions

Allowing access to these endpoints has the potential to trigger operational changes in the cluster. Proceed with caution.

The following REST API permissions control access to the endpoints. Granting access to any of these APIs allows a user to change fundamental operational components of the Security plugin:

  • restapi:admin/actiongroups
  • restapi:admin/allowlist
  • restapi:admin/internalusers
  • restapi:admin/nodesdn
  • restapi:admin/roles
  • restapi:admin/rolesmapping
  • restapi:admin/ssl/certs/info
  • restapi:admin/ssl/certs/reload
  • restapi:admin/tenants