Document-level security (DLS)

Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the Document level security section:

This query specifies that for the role to have access to a document, its genres field must include Comedy.

A typical request to the _search API includes { "query": { ... } } around the query, but in this case, you only need to specify the query itself.

PUT _plugins/_security/api/roles/public_data
{
    "*"
  ],
  "index_permissions": [{
    "index_patterns": [
      "pub*"
    ],
    "dls": "{\"term\": { \"public\": true}}",
    "allowed_actions": [
      "read"
}

These queries can be as complex as you want, but we recommend keeping them simple to minimize the performance impact that the document-level security feature has on the cluster.

A number of variables exist that you can use to enforce rules based on the properties of a user. For example, ${user.name} is replaced with the name of the current user.

This rule allows a user to read any document where the username is a value of the readable_by field:

This table lists substitutions.

User definition

PUT _plugins/_security/api/internalusers/user1
  "password": "asdf",
  "backend_roles": ["abac"],
  "attributes": {
    "permissions": "\"att1\", \"att2\", \"att3\""
  }
}

Role definition

You can perform term-level lookup queries (TLQs) with document-level security (DLS) using either of two modes: adaptive or filter level. The default mode is adaptive, where OpenSearch automatically switches between Lucene-level or filter-level mode depending on whether or not there is a TLQ. DLS queries without TLQs are executed in Lucene-level mode, whereas DLS queries with TLQs are executed in filter-level mode.

By default, the security plugin detects if a DLS query contains a TLQ or not and chooses the appropriate mode automatically at runtime.

To learn more about OpenSearch queries, see .

plugins.security.dls.mode: filter-level

DLS evaluation modes