Setting Up Field and Document Level Security

To enable field level security, you specify the fields that each role can access as part of the indices permissions in a role definition. This binds field level security 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 starting with 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": "[email protected]",
    "phone": "555-555-5555"
  }
}

The following role definition only allows 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 only enable read access to the customer data:

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

Similar to granting field permissions the permission to access fields can be denied with the following syntax:

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

The following rules apply:

Absence of "field_security" in a role is equivalent to * access. Denied fields may only be provided if permission has been granted explicitly to other fields. The exceptions given must be a subset of the fields that permissions have been granted to. Denied and granted fields defined implies access to all granted fields except those which match the pattern in denied fields. Example:

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

In the above example all fields with the prefix "customer." are allowed except for "customer.handle".

An empty array for grant (eg. "grant" : []) means that no fields are granted access to.

{
  // 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, you specify a query that matches all the accessible documents as part of the indices permissions within a role definition. This binds document level security 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 ELasticsearch’s full Query DSL.

For example, the following role grants read access to all indices, but restricts access to documents whose department_id equals 12.

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

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

{
  "indices" : [
    {
      "names" : [ "my_index" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "inline" : {
            "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 will take into account each role held by the user, and combine 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 will not be applied; the user with both roles will have access to all of the documents in the index.

Field level security will take into account each role the user has and combine 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 will not be applied for that index; the user with both roles will have access to all of the fields in in the index.