[role="xpack"] [[field-and-document-access-control]] === 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. NOTE: 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. [IMPORTANT] ===================================================================== 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. See <>. ===================================================================== [[field-level-security]] ==== Field 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 <>). The following role definition grants read access only to the `category`, `@timestamp`, and `message` fields in all the `events-*` indices. [source,js] -------------------------------------------------- { "indices": [ { "names": [ "events-*" ], "privileges": [ "read" ], "field_security" : { "grant" : [ "category", "@timestamp", "message" ] } } ] } -------------------------------------------------- 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. You can also specify field expressions. For example, the following example grants read access to all fields that start with an `event_` prefix: [source,js] -------------------------------------------------- { "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: [source,js] -------------------------------------------------- { "customer": { "handle": "Jim", "email": "jim@mycompany.com", "phone": "555-555-5555" } } -------------------------------------------------- The following role definition enables only read access to the customer `handle` field: [source,js] -------------------------------------------------- { "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: [source,js] -------------------------------------------------- { "indices" : [ { "names" : [ "*" ], "privileges" : [ "read" ], "field_security" : { "grant" : [ "customer.*" ] } } ] } -------------------------------------------------- You can deny permission to access fields with the following syntax: [source,js] -------------------------------------------------- { "indices" : [ { "names" : [ "*" ], "privileges" : [ "read" ], "field_security" : { "grant" : [ "*"], "except": [ "customer.handle" ] } } ] } -------------------------------------------------- The following rules apply: * The absence of `field_security` in a role is equivalent to * access. * If permission has been granted explicitly to some fields, you can specify denied fields. The denied fields must be a subset of the fields to which permissions were granted. * Defining denied and granted fields implies access to all granted fields except those which match the pattern in the denied fields. For example: [source,js] -------------------------------------------------- { "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. ===== Field Level Security and Roles When a user has several roles that specify field level permissions, the resulting field level permissions per index are the union of the individual role permissions. For example, if these two roles are merged: [source,js] -------------------------------------------------- { // 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*" ] } } ] } -------------------------------------------------- The resulting permission is equal to: [source,js] -------------------------------------------------- { // role 1 + role 2 ... "indices" : [ { "names" : [ "*" ], "privileges" : [ "read" ], "field_security" : { "grant": [ "a.*" ], "except" : [ "a.b.c*" ] } } ] } -------------------------------------------------- [[document-level-security]] ==== Document level security 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: [source,js] -------------------------------------------------- { "indices": [ { "names": [ "events-*" ], "privileges": [ "read" ], "query": "{\"match\": {\"category\": \"click\"}}" } ] } -------------------------------------------------- NOTE: Omitting the `query` entry entirely disables document level security for the respective indices permission entry. The specified `query` expects the same format as if it was defined in the search request and supports the full {es} {ref}/query-dsl.html[Query DSL]. For example, the following role grants read access only to the documents whose `department_id` equals `12`: [source,js] -------------------------------------------------- { "indices" : [ { "names" : [ "*" ], "privileges" : [ "read" ], "query" : { "term" : { "department_id" : 12 } } } ] } -------------------------------------------------- NOTE: `query` also accepts queries written as string values. [[templating-role-query]] ===== Templating a role query You can use Mustache templates in a role query to insert the username of the current authenticated user into the role. Like other places in {es} that support templating or scripting, you can specify inline, stored, or file-based templates and define custom parameters. You access the details for the current authenticated user through the `_user` parameter. For example, the following role query uses a template to insert the username of the current authenticated user: [source,js] -------------------------------------------------- { "indices" : [ { "names" : [ "my_index" ], "privileges" : [ "read" ], "query" : { "template" : { "source" : { "term" : { "acl.username" : "{{_user.username}}" } } } } } ] } -------------------------------------------------- You can access the following information through the `_user` variable: [options="header"] |====== | Property | Description | `_user.username` | The username of the current authenticated user. | `_user.full_name` | If specified, the full name of the current authenticated user. | `_user.email` | If specified, the email of the current authenticated user. | `_user.roles` | If associated, a list of the role names of the current authenticated user. | `_user.metadata` | If specified, a hash holding custom metadata of the current authenticated user. |====== You can also access custom user metadata. For example, if you maintain a `group_id` in your user metadata, you can apply document level security based on the `group.id` field in your documents: [source,js] -------------------------------------------------- { "indices" : [ { "names" : [ "my_index" ], "privileges" : [ "read" ], "query" : { "template" : { "source" : { "term" : { "group.id" : "{{_user.metadata.group_id}}" } } } } } ] } -------------------------------------------------- [[set-security-user-processor]] ===== Set security user ingest processor If an index is shared by many small users it makes sense to put all these users into the same index. Having a dedicated index or shard per user is wasteful. To guarantee that a user reads only their own documents, it makes sense to set up document level security. In this scenario, each document must have the username or role name associated with it, so that this information can be used by the role query for document level security. This is a situation where the `set_security_user` ingest processor can help. NOTE: Document level security doesn't apply to write APIs. You must use unique ids for each user that uses the same index, otherwise they might overwrite other users' documents. The ingest processor just adds properties for the current authenticated user to the documents that are being indexed. The `set_security_user` processor attaches user-related details (such as `username`, `roles`, `email`, `full_name` and `metadata` ) from the current authenticated user to the current document by pre-processing the ingest. When you index data with an ingest pipeline, user details are automatically attached to the document. For example: [source,js] -------------------------------------------------- PUT shared-logs/log/1?pipeline=my_pipeline_id { ... } -------------------------------------------------- Read the {ref}/ingest.html[ingest docs] for more information about setting up a pipeline and other processors. [[set-security-user-options]] .Set Security User Options [options="header"] |====== | Name | Required | Default | Description | `field` | yes | - | The field to store the user information into. | `properties` | no | [`username`, `roles`, `email`, `full_name`, `metadata`] | Controls what user related properties are added to the `field`. |====== The following example adds all user details for the current authenticated user to the `user` field for all documents that are processed by this pipeline: [source,js] -------------------------------------------------- { "processors" : [ { "set_security_user": { "field": "user" } } ] } -------------------------------------------------- [[multiple-roles-dls-fls]] ==== Multiple roles with document and field level security 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.