Field-level security

The easiest way to get started with document- and field-level security is open OpenSearch Dashboards and choose Security. Then choose Roles, create a new role, and review the Index permissions section.

Table of contents

  1. Include or exclude fields
    2. roles.yml
  2. Interaction with document-level security

You have two options when you configure field-level security: include or exclude fields. If you include fields, users see only those fields when they retrieve a document. For example, if you include the , title, and year fields, a search result might look like this:

If you exclude fields, users see everything but those fields when they retrieve a document. For example, if you exclude those same fields, the same search result might look like this:

You can specify field-level security settings using OpenSearch Dashboards, roles.yml, and the REST API.

  • To exclude fields in roles.yml or the REST API, add ~ before the field name.

  • Field names support wildcards (*).

    Wildcards are especially useful for excluding subfields. For example, if you index a document that has a string (e.g. {"title": "Thor"}), OpenSearch creates a field of type text, but it also creates a title.keyword subfield of type keyword. In this example, to prevent unauthorized access to data in the title field, you must also exclude the title.keyword subfield. Use title* to match all fields that begin with title.

  1. Choose a role and Add index permission.
  2. Choose an index pattern.

If you map a user to multiple roles, we recommend that those roles use either include or exclude statements for each index. The security plugin evaluates field-level security settings using the operator, so combining include and exclude statements can lead to neither behavior working properly.

For example, in the movies index, if you include actors, title, and year in one role, exclude actors, title, and genres in another role, and then map both roles to the same user, a search result might look like this:

relies on OpenSearch queries, which means that all fields in the query must be visible in order for it to work properly. If you use field-level security in conjunction with document-level security, make sure you don’t restrict access to the fields that document-level security uses.