Setting Up Field and Document Level Security

To enable field level security, specify the fields that each role can access as part of the indices permissions in a role definition. Field level security is thus bound to a well-defined set of indices (and potentially a set of documents).

The following role definition grants read access only to the category, @timestamp, and message fields in all the events-* indices.

{
  "indices": [
    {
      "names": [ "events-*" ],
      "privileges": [ "read" ],
      "field_security" : {
        "grant" : [ "category", "@timestamp", "message" ]
      }
    }
  ]
}

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.

You can also specify field expressions. For example, the following example grants read access to all fields that start with an event_ prefix:

{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant" : [ "event_*" ]
      }
    }
  ]
}

Use the dot notations to refer to nested fields in more complex documents. For example, assuming the following document:

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

The following role definition enables only read access to the customer handle field:

{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant" : [ "customer.handle" ]
      }
    }
  ]
}

This is where wildcard support shines. For example, use customer.* to enable only read access to the customer data:

{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant" : [ "customer.*" ]
      }
    }
  ]
}

You can deny permission to access fields with the following syntax:

{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant" : [ "*"],
        "except": [ "customer.handle" ]
      }
    }
  ]
}

The following rules apply:

For example:

{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "except": [ "customer.handle" ],
        "grant" : [ "customer.*" ]
      }
    }
  ]
}

In the above example, users can read all fields with the prefix "customer." except for "customer.handle".

An empty array for grant (for example, "grant" : []) means that access has not been granted to any fields.

{
  // role 1
  ...
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant": [ "a.*" ],
        "except" : [ "a.b*" ]
      }
    }
  ]
}

{
  // role 2
  ...
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant": [ "a.b*" ],
        "except" : [ "a.b.c*" ]
      }
    }
  ]
}

{
  // role 1 + role 2
  ...
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "field_security" : {
        "grant": [ "a.*" ],
        "except" : [ "a.b.c*" ]
      }
    }
  ]
}

Document level security restricts the documents that users have read access to. To enable document level security, specify a query that matches all the accessible documents as part of the indices permissions within a role definition. Document level security is thus bound to a well defined set of indices.

Enabling document level security restricts which documents can be accessed from any document-based read 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.

The following role definition grants read access only to documents that belong to the click category within all the events-* indices:

{
  "indices": [
    {
      "names": [ "events-*" ],
      "privileges": [ "read" ],
      "query": "{\"match\": {\"category\": \"click\"}}"
    }
  ]
}

The specified query expects the same format as if it was defined in the search request and supports the full Elasticsearch Query DSL.

For example, the following role grants read access only to the documents whose department_id equals 12:

{
  "indices" : [
    {
      "names" : [ "*" ],
      "privileges" : [ "read" ],
      "query" : {
        "term" : { "department_id" : 12 }
      }
    }
  ]
}

{
  "indices" : [
    {
      "names" : [ "my_index" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "acl.username" : "{{_user.username}}" }
          }
        }
      }
    }
  ]
}

{
  "indices" : [
    {
      "names" : [ "my_index" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "group.id" : "{{_user.metadata.group_id}}" }
          }
        }
      }
    }
  ]
}

PUT shared-logs/log/1?pipeline=my_pipeline_id
{
  ...
}

{
  "processors" : [
    {
      "set_security_user": {
        "field": "user"
      }
    }
  ]
}

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.