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.

Document and Field Level Security is disabled by default. Set shield.dls_fls.enabled to true in elasticsearch.yml to enable it. You cannot submit _bulk update requests when document and field level security is enabled.

Field Level Security

edit

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.

<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.

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:

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:

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:

{
  "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:

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:

my_role:
  indices:
    '*':
      privileges: read
      fields:
        - customer.*

Limitations

edit

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

edit

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.

<role_name>:
  indices:
    <index_permission_expression>:
      privileges: <privileges>
      query:
        <query>

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.

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.

customer_care:
  indices:
    '*':
      privileges: read
      query: '{"term" : {"department_id" : "12"}}''

« Mapping Users and Groups to Roles Submitting Requests on Behalf of Other Users »