105 lines
4.1 KiB
Plaintext
105 lines
4.1 KiB
Plaintext
[[setting-up-field-and-document-level-security]]
|
|
=== 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 permissions restrict access to particular fields within a document.
|
|
Document level security permissions restrict access to particular documents within an index.
|
|
|
|
Field and document level permissions are specified separately, but a role can define both field and document level permissions.
|
|
Field and document level security permissions can be configured on a per-index basis.
|
|
|
|
==== Field Level Security
|
|
|
|
To enable field level security, you specify the fields that each role can access in the `roles.yml` file.
|
|
You list the allowed fields with the `fields` option. Fields are associated with a particular index or index pattern and
|
|
operate in conjunction with the privileges specified for the indices.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
<role_name>:
|
|
indices:
|
|
<index_permission_expression>:
|
|
privileges: <privileges>
|
|
fields:
|
|
- <allowed_field_1>
|
|
- <allowed_field_2>
|
|
- <allowed_field_N>
|
|
--------------------------------------------------
|
|
|
|
To allow access to the `_all` meta field, you must explicitly list it as an allowed field. Access to the following meta fields
|
|
is always allowed: _id, _type, _parent, _routing, _timestamp, _ttl, _size and _index. If you specify an empty list of fields,
|
|
only these meta fields are accessible.
|
|
|
|
NOTE: Omitting the fields entry entirely disables field-level security.
|
|
|
|
For example, the following `customer_care` role grants read access to six fields in any index:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
customer_care:
|
|
indices:
|
|
'*':
|
|
privileges: read
|
|
fields:
|
|
- issue_id
|
|
- description
|
|
- customer_handle
|
|
- customer_email
|
|
- customer_address
|
|
- customer_phone
|
|
--------------------------------------------------
|
|
|
|
===== Limitations
|
|
|
|
When field level security is enabled for an index:
|
|
|
|
* The get, multi get, termsvector and multi termsvector APIs aren't executed in real time. The realtime option for these APIs is forcefully set to false.
|
|
* The query cache and the request cache are disabled for search requests.
|
|
* The update API is blocked. An update request needs to be executed via a role that doesn't have field level security enabled.
|
|
|
|
==== Document Level Security
|
|
|
|
Enabling document level security restricts which documents can be accessed from any Elasticsearch query API.
|
|
To enable document level security, you use a query to specify the documents that each role can access in the `roles.yml` file.
|
|
You specify the document query with the `query` option. The document query is associated with a particular index or index pattern and
|
|
operates in conjunction with the privileges specified for the indices.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
<role_name>:
|
|
indices:
|
|
<index_permission_expression>:
|
|
privileges: <privileges>
|
|
query:
|
|
<query>
|
|
--------------------------------------------------
|
|
|
|
NOTE: Omitting the `query` entry entirely disables document-level security.
|
|
|
|
The `query` should follow the same format as if a query was defined in the request body of a search request,
|
|
but here the format is YAML. Any query from the query-dsl can be defined in the `query` entry.
|
|
|
|
For example, the following `customer_care` role grants read access to all indices, but restricts access to documents whose `department_id` equals `12`.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
customer_care:
|
|
indices:
|
|
'*':
|
|
privileges: read
|
|
query:
|
|
term:
|
|
department_id: 12
|
|
--------------------------------------------------
|
|
|
|
Alternatively the query can also be defined in JSON as a string. This makes it easier to define queries that already have
|
|
been defined in the JSON body of search request body elsewhere.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
customer_care:
|
|
indices:
|
|
'*':
|
|
privileges: read
|
|
query: '{"term" : {"field2" : "value2"}}''
|
|
-------------------------------------------------- |