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.

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.

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. When you assign a user multiple roles, the permissions are ORed together. This means if you assign one role that restricts access to particular fields in an index, and another that doesn’t specify any field level access restrictions for that index, the user will have access to all fields. The same is true for document level permissions.

For example, let’s say role_a only grants access to the address field of the documents in index1, but doesn’t specify any document restrictions. Conversely, role_b limits access to a subset of the documents in index1, but 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.

Field Level Security

edit

To enable field level security, you specify the fields that each role can access in the role definition. You list the allowed fields in the fields entry. (Omitting the fields entry disables field-level security.) Fields are associated with a particular index or index pattern and operate in conjunction with the privileges specified for the indices.

POST /_shield/role/my_fls_role
{
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["read"], 
      "fields": [ "title", "body" ]
    }
  ]
}

Users with document and field level security enabled for an index should not perform write operations.

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.

For example, the following customer_care role grants read access to six fields in any index:

POST /_shield/role/customer_care
{
  "indices": [
    {
      "names": [ "*" ],
      "privileges": ["read"],
      "fields": [
            "issue_id",
            "description",
            "customer_handle",
            "customer_email",
            "customer_address",
            "customer_phone"
      ]
    }
  ]
}

Specifying Field Names in a Role

edit

Within the indices.fields array, you can use wildcards and regular expressions to refer to multiple fields:

Wildcards - by default you can use simple wildcard matching where * is a placeholder for zero or more characters, ? is a placeholder for a single character and \ can be used as an escape character.
Regular Expressions - to match more complex patterns you can enable regular expressions by wrapping the pattern within a pair of forward slashes (/). Regular expressions are based on Lucene’s regexp automaton syntax. Any pattern starting with / and not ending with / is considered to be malformed.

For example, the following role is the same as the previous role:

POST /_shield/role/customer_care
{
  "indices": [
    {
      "names": [ "*" ],
      "privileges": ["read"],
      "fields": [
            "issue_id",
            "description",
            "customer_*"
      ]
    }
  ]
}

If the documents in your index are more complex and contain JSON objects, use dot notion to specify the accessible fields.

For example, if you have the following customer document:

{
  "customer": {
    "handle": "Jim",
    "email": "jim@mycompany.com",
    "phone": "555-555-5555"
  }
}

To allow access to only the handle field, specify customer.handle in the fields entry:

POST /_shield/role/my_role
{
  "indices": [
    {
      "names": [ "*" ],
      "privileges": ["read"],
      "fields": [ "customer.handle" ]
    }
  ]
}

To allow access to the entire customer object, you can use a wildcard

POST /_shield/role/my_role
{
  "indices": [
    {
      "names": [ "*" ],
      "privileges": ["read"],
      "fields": [ "customer.*" ]
    }
  ]
}

Document Level Security

edit

Enabling document level security restricts which documents can be accessed from any document based API. You use a query to specify the documents that can be accessed. To enable document level security, include a query entry in the role definition. (Omitting query entry disables document-level security.) The query is associated with a particular index or index pattern and operates in conjunction with the privileges specified for the indices.

POST /_shield/role/my_dls_role
{
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["read"], 
      "query": {"term" : {"department_id" : "12"}} 
    }
  ]
}

	Users with document and field level security enabled for an index should not perform write operations.
	Any query from the Elasticsearch query-dsl can be use for the `query` entry. This query restricts access to only those documents whose `department_id` is `12`.

Multiple Roles with Document and Field Level Security

edit

A user can have many roles and each role can define different permissions on the same index. Document and field level security take into account each role held by a user and combine permissions as follows:

Document level security combines each document level security query for a particular index with an OR operation. This means that a document can be accessed if it matches any of the role queries. If one role grants access to an index with document level security disabled, and another restricts access to partcular documents in the index, a user with both roles can access any document in the index.

Field level security will take into account each role held by the user and combine all of the fields listed into a single set for each index. If a role grants access to an index without field level security and another grants access with field level security, field level security will not be applied; the user with both roles will have access to all of the fields in the documents in the index.

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