Document-Level Security restricts which individual documents inside an index a specific user is allowed to see, rather than granting or denying access to the whole index at once.

Start with the plain-English definition

Elasticsearch stores information as JSON documents inside containers called indices, and controls who can do what through a security model built around users and roles. A role is a named set of permissions, such as which indices can be searched, which can be written to, and which administrative actions are allowed. Ordinarily, a role’s permissions apply to an entire index at once: a user either can search a given index, or cannot.

Document-Level Security adds a finer layer underneath that index-level permission. Instead of a role simply saying “this user can search the patient-records index,” a DLS-enabled role says “this user can search the patient-records index, but only see the documents matching this specific condition,” such as documents belonging to their own department. The condition is expressed as a query, evaluated automatically and invisibly for every single search that role’s users run.

Why DLS is invisible to the end user

A defining trait of DLS is that it does not require the searching application or the end user to do anything differently. The same search request, sent by two different users with two different roles, simply returns two different result sets, filtered automatically before those results ever leave the cluster. Nobody has to remember to add an extra filter to their query for security to be enforced.

The three jobs DLS is used for

A few numbers worth remembering

The big picture

Here is the whole story in one diagram. A user authenticates, their roles are resolved, and any DLS query attached to those roles for the target index is silently combined with the user’s own search before it ever touches the actual data.

flowchart LR
  U["User logs in"] --> R["Roles resolved
e.g. cardiology-staff"]
  R --> D["DLS query attached to role
e.g. department = cardiology"]
  U --> Q["User's own search query"]
  Q --> C["Combined query:
user's search AND DLS restriction"]
  D --> C
  C --> M["Matching engine"]
  M --> Res["Filtered results returned"]

Read the diagram left to right. The user never sees or writes the DLS restriction themselves — it comes entirely from their assigned role. Their own search query is combined with that restriction, and only documents satisfying both ever reach the matching engine at all, let alone the final results.

What DLS does not do

Index-level access control alone forces an uncomfortable choice between duplicating data across many indices or accepting that everyone with index access sees everything in it.

Four situations where index-level control alone falls short

The alternative nobody wants: an index per tenant

Without DLS, the traditional workaround is creating a completely separate index for each tenant, department, or region needing isolated visibility. This works, but it multiplies operational overhead: more indices to manage, more shards consuming cluster resources, more mapping and template consistency to maintain, and a real risk of configuration drift between them over time as the number of separate indices grows into the hundreds or thousands.

A short history of access control in Elasticsearch

Three ideas underpin everything else in this guide: what a role actually is, what a role query means, and how a user’s overall access is determined when they may hold several roles at once.

Roles: the basic unit of permission

A role is a named, reusable bundle of permissions: which index patterns can be accessed, what actions are allowed against them, such as reading or writing, and optionally, a DLS restriction and a field-level security restriction layered on top. A user is assigned one or more roles, either directly or through an external identity system mapped into Elasticsearch’s security layer.

Role queries: the mechanism behind DLS

The DLS restriction attached to a role is itself expressed as a role query: an ordinary Elasticsearch query, of the same kind used in a normal search request, but stored as part of the role definition rather than sent by the end user. Because it uses the same query capabilities available everywhere else in Elasticsearch, a role query can range from a simple exact match on a department field to a more elaborate condition combining several fields together.

Combining multiple roles: the union rule

A user frequently holds more than one role at once. When two or more of a user’s roles each grant access to the same index, but with different DLS restrictions, Elasticsearch does not require both restrictions to match at the same time. Instead, it treats the combination as a union: a document is visible if it satisfies at least one of the applicable roles’ restrictions, not only if it satisfies all of them simultaneously.

Without showing configuration syntax directly, this chapter describes the pieces a DLS setup is built from, and how they fit together conceptually.

The building blocks

Where roles and users actually connect

A role definition on its own restricts nothing until it is assigned to at least one user. That assignment can happen directly, by explicitly listing a role on a user’s account, or indirectly, through role mapping rules that automatically assign roles based on attributes coming from an external identity provider, such as a department field supplied during single sign-on. Either way, the DLS restriction itself is defined once, on the role, and then applies uniformly to every user who ends up holding that role.

One role, reused across many users

Following one search request from arrival to filtered result shows exactly where and how DLS enforcement fits inside the broader query execution pipeline.

Step by step

sequenceDiagram
  participant Client
  participant Auth as Authentication
  participant Roles as Role Resolution
  participant Node as Coordinating Node
  Client->>Auth: Request with credentials
  Auth->>Roles: Identity confirmed
  Roles->>Roles: Resolve roles and DLS queries
  Roles->>Node: Effective permissions and restrictions
  Node->>Node: Combine restriction with user's query
  Node->>Node: Match only documents satisfying both
  Node-->>Client: Filtered results

Why enforcement happens before matching, not after

A crucial design point is that DLS restrictions are applied as part of the matching process itself, not as an afterthought filtering an already-retrieved result list. This matters for both correctness and performance: pagination, aggregations, and result counts all reflect the restricted view consistently, rather than a raw total that then gets trimmed down inconsistently after the fact.

Zooming out from one request’s internal mechanics to the whole user journey shows how DLS fits alongside authentication and authorization as a complete access control story.

The three stages of the overall flow

flowchart TD
  A["User authenticates"] --> B["Roles and attributes resolved"]
  B --> C["Role definitions loaded,
including DLS role queries"]
  C --> D["User issues a search"]
  D --> E["DLS restriction silently applied"]
  E --> F["Filtered results returned"]
  F --> G["User issues another search later"]
  G --> E

How this interacts with external identity providers

Many organizations manage user identity through an external system, such as a corporate directory or a single sign-on provider, rather than creating individual user accounts directly inside Elasticsearch. Role mapping rules translate attributes coming from that external system, such as a department or group membership claim, into the appropriate Elasticsearch roles at login time, which is what then determines which DLS role queries apply for that session going forward.

DLS applies consistently across the whole session

Chapter 3 introduced the role query as the mechanism behind DLS. This chapter looks more closely at what kinds of restrictions are practical, and exactly how they behave when several apply at once.

Common shapes of a role query

DLS applies to reads; writes need separate handling

By default, DLS restrictions govern what a user can see when searching or retrieving documents. They do not automatically prevent a user from writing a document that falls outside their own restriction, unless separate write-time validation, such as an ingest pipeline check or application-level enforcement, is also put in place. This distinction matters enough that Chapter 11 covers it as a specific security consideration in its own right.

How restrictions from several roles truly combine

Expanding on the union rule introduced in Chapter 3: when a user holds multiple roles, each granting access to the same index with its own DLS query, Elasticsearch effectively evaluates “does this document satisfy role A’s restriction, or role B’s restriction, or any other applicable role’s restriction,” and shows the document if any single one of them is satisfied. This is a logical or, not a logical and, across roles.

DLS is often deployed alongside a closely related feature, field-level security, and understanding how the two combine avoids a common source of confusion.

Two different questions, two different features

The two features are independent and commonly used together on the same role: a role might restrict a billing clerk to only documents belonging to their own assigned accounts through DLS, while separately hiding clinical notes fields on those same documents through field-level security, since a billing clerk may need visibility into an account’s existence without needing its full medical detail.

Caching considerations specific to DLS

Elasticsearch’s query and request caches are aware of security context, so cached results for one role’s restricted view are not served to a user under a different role that would see a different set of documents. This keeps caching safe, but it does mean that a cluster serving many distinct roles against the same index benefits less from a single shared cache than a cluster where everyone sees identical, unrestricted results, since the cache effectively has to maintain separate entries per distinct restriction.

What an interviewer may ask

Because DLS is part of the security layer rather than a separate service, its availability story is tightly coupled to the cluster’s own normal resilience, with a few DLS-specific details worth knowing.

Role and DLS definitions are cluster metadata

Role definitions, including any attached DLS role queries, are stored as part of the cluster’s own security configuration, which is replicated and persisted the same way other critical cluster metadata is. A node restart, a master election, or a shard relocation does not affect which DLS restrictions apply, since every node involved in serving a request consults the same consistently replicated role definitions.

What can actually go wrong operationally

flowchart TD
  A["User's department changes"] --> B["Role mapping updated centrally"]
  B --> C{"User has an active long-lived credential?"}
  C -->|"Yes"| D["Old credential still enforces old restriction until rotated"]
  C -->|"No"| E["Next login picks up new role and restriction immediately"]
  D --> F["Rotate or revoke old credential"]
  F --> E

Reliability comes from treating role changes as real deployments

DLS is itself a security feature, so this chapter looks specifically at how it can be undermined, misconfigured, or bypassed if not set up with care.

The union-rule risk, revisited

Writes are generally not restricted by DLS alone

As noted in Chapter 7, DLS by default governs visibility on read operations, not write operations. A role permitting a user to write to an index does not automatically prevent them from writing a document that falls outside their own DLS restriction, unless separate validation is layered in, such as an ingest pipeline enforcing that a written document’s ownership field matches the writer’s own identity. Treating DLS as a complete write-time access control on its own is a mistake worth avoiding.

Superuser and administrative access bypasses DLS by design

Certain built-in administrative privileges are intentionally allowed to bypass DLS restrictions entirely, since cluster operators and certain administrative tools genuinely need full visibility to do their jobs, such as reindexing or diagnosing cluster health. This is by design, not a flaw, but it does mean that the set of accounts and service credentials holding such elevated privileges deserves the same tight control and auditing as any other powerful administrative capability.

Role queries themselves can be a subtle information channel

Because DLS enforcement is invisible by design, visibility into whether it is working correctly has to come from deliberate logging and monitoring, not from casual observation.

What to watch

A practical DLS verification habit

Whenever a DLS-related role is created or changed, logging in as a representative test user under that exact role, and confirming both that expected documents are visible and that specific known-restricted documents are not, catches misconfigurations immediately. This mirrors the same before-and-after verification discipline recommended for other sensitive configuration changes throughout Elasticsearch operations.

flowchart LR
  A["Role created or changed"] --> B["Log in as representative test user"]
  B --> C["Run known test searches"]
  C --> D{"Expected documents visible,
restricted documents hidden?"}
  D -->|"Yes"| E["Deploy with confidence"]
  D -->|"No"| F["Investigate role query and role combination"]

DLS behaves consistently across self-managed, Elastic Cloud, and Kubernetes-based deployments, since it is a security-layer feature rather than an infrastructure-specific one.

Roles as infrastructure-as-code

Because a DLS misconfiguration can have serious consequences, most mature deployments manage role definitions, including their DLS restrictions, the same way they manage any other sensitive infrastructure configuration: stored in version control, applied through an automated and reviewed deployment pipeline, and never edited ad hoc directly against a live cluster without that same review.

Years of production DLS usage have surfaced patterns worth copying, and an equally memorable set of habits worth avoiding.

Patterns worth copying

Anti-patterns to avoid

A concise, practical checklist distilled from the chapters above, organized as habits to lean into and habits to actively avoid.

Every DLS decision trades one good thing for another. Naming the trade-off explicitly leads to better decisions than treating any single approach as automatically correct.

There is no universally correct choice in this table — only the choice that fits how many distinct visibility groups exist, how sensitive the data actually is, and how much ongoing operational discipline a given team can realistically sustain around reviewing and testing roles.

DLS’s design choices make far more sense once seen against how organizations actually use it to solve concrete access-control problems at scale.

Beyond the fundamentals, a couple of advanced mechanisms make DLS considerably more practical to operate at scale, particularly for large or structurally complex datasets.

Templated role queries: one role, many users

Rather than writing a separate role for every individual user or tenant, a role query can be written to automatically substitute values from the currently authenticated user’s own identity or attributes at the moment a search runs. This is what allows a single shared role, such as “tenant-scoped access,” to correctly restrict a thousand different tenant users to a thousand different, individually correct subsets of data, without maintaining a thousand separate role definitions.