170 lines
6.3 KiB
Plaintext
170 lines
6.3 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
|
|
--------------------------------------------------
|
|
|
|
Also wildcard field expressions can be added to the `fields` options in the `roles.yml` file. For example the following
|
|
example has the same effect as the previous example:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
customer_care:
|
|
indices:
|
|
'*':
|
|
privileges: read
|
|
fields:
|
|
- issue_id
|
|
- description
|
|
- 'customer_*'
|
|
--------------------------------------------------
|
|
|
|
If documents are more complex and contain json objects then the fields with dot notion should be used.
|
|
|
|
Assume the following document:
|
|
|
|
[source,json]
|
|
--------------------------------------------------
|
|
{
|
|
"customer": {
|
|
"handle": "Jim",
|
|
"email": "jim@mycompany.com",
|
|
"phone": "555-555-5555"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
If only access to the `handle` field is allowed then the following role should be setup:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
my_role:
|
|
indices:
|
|
'*':
|
|
privileges: read
|
|
fields:
|
|
- customer.handle
|
|
--------------------------------------------------
|
|
|
|
If access to the entire `customer` object is allowed then the wildcard dot notation can be used to make this easier:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
my_role:
|
|
indices:
|
|
'*':
|
|
privileges: read
|
|
fields:
|
|
- customer.*
|
|
--------------------------------------------------
|
|
|
|
===== 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 document based 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" : {"department_id" : "12"}}''
|
|
--------------------------------------------------
|
|
|
|
===== Limitations
|
|
|
|
When document 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.
|
|
* Document level security isn't applied for APIs that aren't document based oriented. For example this is the case for the field stats API.
|
|
* Document level security doesn't affect global index statistics that relevancy scoring uses. So this means that scores are computed without taking the role query into account.
|
|
Note that, documents not matching with the role query are never returned.
|
|
* The `has_child` and `has_parent` queries aren't supported as role query in the `roles.yml` file.
|
|
The `has_child` and `has_parent` queries can be used in the search API with document level security enabled. |