Document level security

Document level security

Document level security restricts the documents that users have read access to. In particular, it restricts which documents can be accessed from document-based read APIs.

To enable document level security, you use a query to specify the documents that each role can access. The document query is associated with a particular data stream, index, or wildcard (*) pattern and operates in conjunction with the privileges specified for the data streams and indices.

The specified document query:

• Expects the same format as if it was defined in the search request
• Supports templating a role query that can access the details of the currently authenticated user
• Accepts queries written as either string values or nested JSON
• Supports the majority of the Elasticsearch Query Domain Specific Language (DSL), with some limitations for field and document level security

Omitting the query parameter entirely disables document level security for the respective indices permission entry.

The following role definition grants read access only to documents that belong to the click category within all the events-* data streams and indices:

resp = client.security.put_role(
    name="click_role",
    indices=[
        {
            "names": [
                "events-*"
            ],
            "privileges": [
                "read"
            ],
            "query": "{\"match\": {\"category\": \"click\"}}"
        }
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "click_role",
  indices: [
    {
      names: ["events-*"],
      privileges: ["read"],
      query: '{"match": {"category": "click"}}',
    },
  ],
});
console.log(response);

POST /_security/role/click_role
{
  "indices": [
    {
      "names": [ "events-*" ],
      "privileges": [ "read" ],
      "query": "{\"match\": {\"category\": \"click\"}}"
    }
  ]
}

You can write this same query using nested JSON syntax:

resp = client.security.put_role(
    name="click_role",
    indices=[
        {
            "names": [
                "events-*"
            ],
            "privileges": [
                "read"
            ],
            "query": {
                "match": {
                    "category": "click"
                }
            }
        }
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "click_role",
  indices: [
    {
      names: ["events-*"],
      privileges: ["read"],
      query: {
        match: {
          category: "click",
        },
      },
    },
  ],
});
console.log(response);

POST _security/role/click_role
{
  "indices": [
    {
      "names": [ "events-*" ],
      "privileges": [ "read" ],
      "query": {
        "match": {
          "category": "click"
        }
      }
    }
  ]
}

The following role grants read access only to the documents whose department_id equals 12:

resp = client.security.put_role(
    name="dept_role",
    indices=[
        {
            "names": [
                "*"
            ],
            "privileges": [
                "read"
            ],
            "query": {
                "term": {
                    "department_id": 12
                }
            }
        }
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "dept_role",
  indices: [
    {
      names: ["*"],
      privileges: ["read"],
      query: {
        term: {
          department_id: 12,
        },
      },
    },
  ],
});
console.log(response);

POST /_security/role/dept_role
{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "query" : {
        "term" : { "department_id" : 12 }
      }
    }
  ]
}