[role="xpack"]
[[field-and-document-access-control]]
=== Setting up field and document level security

You can control access to data within an index by adding field and document level
security permissions to a role. 
<<field-level-security,Field level security permissions>> restrict access to 
particular fields within a document. 
<<document-level-security,Document level security permissions>> restrict access 
to particular documents within an index.

NOTE: Document and field level security is currently meant to operate with
read-only privileged accounts. Users with document and field level
security enabled for an index should not perform write operations.

A role can define both field and document level permissions on a per-index basis.
A role that doesn’t specify field level permissions grants access to ALL fields.
Similarly, a role that doesn't specify document level permissions grants access
to ALL documents in the index.

[IMPORTANT]
=====================================================================
When assigning users multiple roles, be careful that you don't inadvertently
grant wider access than intended. Each user has a single set of field level and
document level permissions per index. See <<multiple-roles-dls-fls>>.
=====================================================================

NOTE: Document- and field-level security disables the
{ref}/shard-request-cache.html[shard request cache].

[[multiple-roles-dls-fls]]
==== Multiple roles with document and field level security

A user can have many roles and each role can define different permissions on the
same index. It is important to understand the behavior of document and field
level security in this scenario.

Document level security takes into account each role held by the user and
combines each document level security query for a given index with an "OR". This
means that only one of the role queries must match for a document to be returned.
For example, if a role grants access to an index without document level security
and another grants access with document level security, document level security
is not applied; the user with both roles has access to all of the documents in
the index.

Field level security takes into account each role the user has and combines
all of the fields listed into a single set for each index. For example, if a
role grants access to an index without field level security and another grants
access with field level security, field level security is not be applied for
that index; the user with both roles has access to all of the fields in the
index.

For example, let's say `role_a` grants access to only the `address` field of the
documents in `index1`; it doesn't specify any document restrictions. Conversely,
`role_b` limits access to a subset of the documents in `index1`; it doesn't
specify any field restrictions. If you assign a user both roles, `role_a` gives
the user access to all documents and `role_b` gives the user access to all
fields.

If you need to restrict access to both documents and fields, consider splitting
documents by index instead.

include::role-templates.asciidoc[]
include::set-security-user.asciidoc[]