RBAC is a way of granting permission indirectly, through roles, instead of handing permissions to individual people one by one.

The one-sentence answer

Elasticsearch is a search and analytics engine that stores data across servers called nodes. Role-based access control is Elasticsearch’s primary authorization method: it works by assigning privileges to named roles, and then assigning those roles to users or groups, so that what a person can do is determined entirely by which roles they carry.

Two words matter enormously here, and they are easy to confuse. Authentication answers “who are you?” — it is the login step, checking a username and password, a certificate, or a token. Authorization answers “what are you allowed to do, now that we know who you are?” RBAC lives entirely on the authorization side. It never decides whether a login attempt is genuine; it only decides what a successfully logged-in identity is permitted to touch.

Why indirection is the whole point

It would technically be possible to grant permissions directly to each individual person: “Priya can read the orders index,” “Sam can write to the logs index,” and so on, one line per person. This approach collapses almost immediately in any organization bigger than a handful of people. When fifty analysts all need the same access, you would have to write and maintain fifty nearly identical permission entries. When that access needs to change, you would have to edit all fifty, and inevitably a few get missed.

RBAC solves this by inserting one layer of indirection. You define a role once — say, analyst_read_only — describing exactly what that role can do. Then you assign that one role to as many users as need it. Changing what analysts are allowed to do means editing the role definition a single time, and every user holding that role is updated automatically and consistently.

What RBAC is not

• It is not encryption. RBAC controls who can ask for data through the API; encryption protects data at rest on disk and in transit over the network. Elasticsearch uses both, but they solve different problems.
• It is not the same as a network firewall. A firewall decides which machines can even reach the cluster over the network. RBAC decides, once a connection and a login have already succeeded, what that authenticated identity may do.
• It is not audit logging, although the two work well together. RBAC prevents actions; audit logging records what actually happened, including attempts that RBAC blocked.

Without access control, every person and application with a valid connection could read, change, or delete anything stored in the cluster.

The problem: one cluster, many audiences

A modern Elasticsearch deployment rarely serves just one purpose. The same cluster might store application logs that developers need to debug an outage, security events that only the security team should see, customer records that must stay restricted under privacy regulations, and business dashboards that executives check every morning. These audiences overlap in the systems they use but not in what they should be allowed to see or change.

Without RBAC, a single set of credentials that can search would, by default, be able to search everything, and depending on the surrounding setup, potentially write or delete data too. A support engineer looking up a single customer’s order history could, in principle, also see every other customer’s private data, or accidentally trigger a bulk delete meant for a completely different index.

The cost of getting this wrong

Overly broad access is not a theoretical risk. A single set of overshared credentials, if leaked through a misconfigured application, a committed configuration file, or a compromised laptop, can expose or destroy far more than the credentials were ever meant to touch. Many real-world data exposure incidents trace back not to a sophisticated attack, but to a database or search cluster that granted broad access “to keep things simple,” and later paid for that simplicity all at once.

flowchart LR
  A["Single shared superuser credential"] --> B["Used by many applications and people"]
  B --> C["One credential leaks or is misused"]
  C --> D["Attacker or mistake can read every index"]
  D --> E["Attacker or mistake can write or delete every index"]
  E --> F["Full data breach or full data loss"]

RBAC breaks this chain early. A support engineer’s credentials, scoped to a narrow role, simply cannot read the security index even if those credentials are compromised, because the role attached to them never granted that permission in the first place. The damage from any single leaked credential is limited to exactly what that credential’s roles allowed, which is the entire purpose of the design.

The principle of least privilege

This idea — giving every identity the smallest set of permissions it genuinely needs to do its job, and nothing more — is called the principle of least privilege. RBAC is the mechanism Elasticsearch provides to actually implement that principle in practice, rather than it staying a nice idea nobody enforces. Roles are how “the smallest set of permissions needed” gets written down, stored, and applied consistently, forever, without depending on every administrator remembering to be careful by hand.

Eight simple ideas unlock the entire system. Learn these and every later chapter reads easily.

Putting the pieces together

A useful way to hold all of this in your head at once: a user is who someone is. A role is a named bundle of permission. A privilege is one specific kind of allowed action. A permission is that action tied to a specific resource. Roles are built out of permissions, and users are given roles. Nothing is ever granted to a user directly in a well-designed setup; everything flows through the role in between.

Why “union,” not “intersection,” matters

This point trips people up constantly, so it deserves its own callout. If a user holds Role A, which grants read access to the orders index, and Role B, which grants read access to the shipping index, that user can read both indices — the combination of everything each role allows, not merely whatever the two roles happen to share in common. This has a direct and important consequence for security design: adding a role to a user can only ever expand what they can do, never shrink it. There is no equivalent of a role that “takes away” a permission another role granted.

RBAC is not one component. It is several cooperating parts: realms that authenticate, roles that define permission, and a mapping layer that connects the two.

The big picture

Every request that reaches Elasticsearch’s security layer passes through authentication first, and only afterward through authorization. The diagram below shows the full path, from a raw request arriving at the cluster to a final decision on whether it is allowed to proceed.

flowchart TD
  A["Incoming request with credentials"] --> B["Authentication: which realm verifies this identity?"]
  B --> C["Identity confirmed: a user object exists"]
  C --> D["Role resolution: which roles apply to this user?"]
  D --> E["Native or file realm: roles assigned directly"]
  D --> F["External realm: role mapping rules translate groups to roles"]
  E --> G["Combine all resolved roles into one effective permission set"]
  F --> G
  G --> H["Authorization check against the requested action and resource"]
  H --> I["Allowed: request proceeds"]
  H --> J["Denied: request rejected"]

Notice the branch in the middle. Depending on which realm authenticated the user, roles arrive differently. Some realms attach roles to the user directly. Others rely entirely on role mapping to translate an external group membership into Elasticsearch roles. Both paths converge at the same place: one combined, effective set of permissions that the authorization check then measures the incoming request against.

Realms: where identity comes from

The native realm stores users and their role assignments directly inside Elasticsearch itself, managed through the Security API or the Kibana user management screens. The file realm reads users and their role assignments from a file on disk, which is common in simpler, self-managed, or containerized deployments where roles are set as part of basic authentication secrets. External realms — Active Directory, LDAP, SAML, OpenID Connect, Kerberos, and PKI among them — authenticate against systems the organization already runs, and use role mapping rules rather than direct assignment to decide which Elasticsearch roles an authenticated identity receives.

Roles: where permission lives

A role is defined once, independent of any specific realm, as a set of cluster privileges, index privileges (each tied to a pattern of index names), and optionally application privileges and a run_as list. The same role definition can be assigned to a native-realm user, referenced by a file-realm entry, or targeted by a role mapping rule for an external realm — the role itself does not care where the identity holding it came from.

Role mapping: the translation layer

Role mapping matters most for external realms, where Elasticsearch has no native concept of “this LDAP group” or “this SAML attribute.” A role mapping rule says, in effect, “anyone who authenticates through this realm and belongs to this external group should receive these Elasticsearch roles.” This is what lets an organization manage group membership in its existing identity system — Active Directory, for example — while Elasticsearch permissions stay automatically synchronized to it, with no need to create or update individual Elasticsearch users by hand every time someone joins or leaves a team.

Every single request Elasticsearch receives goes through the same sequence of checks before it is allowed to do anything at all.

Step by step

Why the order of these steps matters

Authentication always happens before authorization, without exception, because authorization has no meaning without a confirmed identity to check permissions against. Similarly, index-level authorization always happens before field-level or document-level restrictions are even considered, because there is no point calculating which fields or documents someone can see inside an index they were never allowed to access in the first place. This ordering is what makes the whole system predictable: broader checks always gate narrower ones.

Tracing one concrete request end to end shows exactly where each RBAC check happens in practice.

The journey of a search request

Imagine an analyst named Priya, who authenticates through her company’s Active Directory and searches an index called customer-orders, filtered to just her assigned region.

sequenceDiagram
  participant Priya as Priya (Client)
  participant Auth as Authentication (LDAP realm)
  participant Map as Role Mapping
  participant AuthZ as Authorization Engine
  participant Idx as customer-orders Index

  Priya->>Auth: Log in with Active Directory credentials
  Auth-->>Priya: Identity confirmed
  Auth->>Map: Look up Priya's AD group membership
  Map-->>AuthZ: Assign role "regional_analyst"
  Priya->>AuthZ: Search request on customer-orders
  AuthZ->>AuthZ: Check index privilege: read on customer-orders granted
  AuthZ->>AuthZ: Apply document-level security query: region = "APAC"
  AuthZ->>AuthZ: Apply field-level security: hide "internal_margin" field
  AuthZ->>Idx: Execute restricted search
  Idx-->>Priya: Only APAC documents, without internal_margin field

Priya never sees an error and never even realizes most of these checks happened. From her point of view, she searched an index and got sensible results back. Underneath, the effective role she was assigned filtered the results down to her region automatically through document-level security, and hid a sensitive field through field-level security, entirely transparently.

What happens when a check fails

If Priya’s role had never granted read access to customer-orders at all, the request would be rejected at the index-privilege step, well before document-level or field-level security ever entered the picture, and she would receive an authorization error rather than an empty or filtered result. This distinction matters: a role that grants access but restricts it heavily behaves very differently from a role that grants no access at all, even though both can end up limiting what a user actually sees.

The write path looks similar, with higher stakes

A write request — indexing a new document, updating an existing one, or deleting one — follows the same authentication and index-privilege steps, but checks a different privilege (such as write, create, or delete rather than read). Field-level and document-level security interact with writes more carefully: a role restricted with field-level security cannot use the update API or bulk update actions at all, since partially updating a document a user cannot fully see creates ambiguous, unsafe semantics that Elasticsearch deliberately avoids rather than trying to guess the right behavior.

Cluster privileges govern actions that affect the cluster as a whole, rather than any single index.

Reading these privileges the right way

Notice the pattern across almost every category here: a narrow, read-only monitor-style privilege, and a broader manage-style privilege that includes everything the narrower one does, plus the ability to actually change things. This pattern repeats throughout Elasticsearch’s privilege system deliberately, because it lets an administrator grant visibility into cluster health to a much wider group of people — dashboards, on-call engineers, automated monitoring tools — without also handing every one of them the power to change cluster settings or delete data.

Index privileges govern what can be done to the actual data stored in specific indices, aliases, or data streams.

Index privileges are always scoped to a pattern

Unlike cluster privileges, which apply cluster-wide, every index privilege in a role is tied to a pattern of index names, such as logs-* or customer-orders. This is what allows one role to grant broad read access to an entire family of log indices while granting a completely different, much narrower set of privileges to a single sensitive index, all within the same role definition, simply by listing multiple index-privilege blocks with different patterns.

run_as: acting on behalf of someone else

The run_as privilege is different from the others in this chapter because it does not grant access to data directly. Instead, it allows an authenticated user to submit requests on behalf of a different, specified user, with the request then authorized using that second user’s own permissions rather than the original caller’s. This is primarily useful for trusted backend services that need to act on behalf of many different end users without storing or managing separate credentials for every single one of them.

Elasticsearch ships with a substantial library of ready-made roles, covering the most common needs so that not every deployment has to design permissions entirely from scratch.

Why built-in roles exist, and when to use them

Built-in roles cover the common, well-understood cases that almost every deployment eventually needs: a way for Kibana itself to talk to Elasticsearch, a way for monitoring agents to report health data, a way for an administrator to have full control. Using a built-in role where one genuinely fits saves time and reduces the chance of a hand-written role accidentally missing a permission some internal feature quietly depends on. Built-in roles are also maintained and updated by Elastic itself as new versions add features, which a hand-rolled equivalent role would not automatically receive.

Most real deployments eventually need roles tailored to their own teams, applications, and data sensitivity, beyond what any built-in role covers.

Start from the job, not from the person

The most durable approach to designing custom roles is to name and define them around a job function or responsibility, rather than around any specific individual. A role called billing_read_only or log_ingest_writer describes a function that will outlive any one employee holding it, whereas a role built around one particular person’s exact current needs has to be rebuilt every time that person’s job changes, or when someone new needs equivalent access.

A worked example: a support team role

Consider a customer support team that needs to look up individual customer orders to answer questions, but should never see internal profit margins, should never be able to modify any order data, and should never touch any index outside the orders system entirely. A well-designed role for this team would grant the read index privilege scoped only to an orders-* index pattern, combined with field-level security excluding the internal_margin field, and no cluster privileges beyond perhaps monitor for basic health visibility if their tooling needs it.

flowchart TD
  R["Role: support_read_only"]
  R --> C1["Cluster privilege: monitor (optional, for tooling)"]
  R --> I1["Index privilege: read on pattern orders-*"]
  I1 --> F1["Field-level security: exclude internal_margin"]
  I1 --> D1["Document-level security: none needed, full order visibility within pattern"]

Naming conventions that scale

As the number of custom roles grows, a consistent naming pattern prevents confusion later. Many organizations settle on a scheme like {team-or-system}_{index-scope}_{access-level}, producing names such as support_orders_read or billing_invoices_write. A name that states its scope and access level up front lets anyone reviewing the role list understand, at a glance, roughly what each role is for, without opening every single one to check.

Reviewing roles over time

Roles are not “set once and forget forever.” Job responsibilities shift, new indices appear, old indices get retired, and a role written two years ago may grant access to data patterns that no longer make sense, or fail to cover a new index that logically belongs within its original intent. Periodically reviewing custom roles against what they are actually used for in practice — rather than what someone guessed they might need years earlier — keeps the whole system honest and prevents silent permission creep.

A worked walkthrough: designing a role from a real request

Concepts land better with a concrete story attached. Imagine a data science team asks for “access to the analytics cluster” to build a new churn-prediction model. Taken literally, that request could mean anything from full superuser access to a narrow read-only slice of one index, so the first step is never to write a role, but to ask clarifying questions: which specific indices does the model actually need to read from, does the team need to write any new indices back, does the team need visibility into cluster health, and does any of the underlying data contain fields that should stay hidden from this particular team.

Suppose the answers turn out to be: read access to customer-events-* and customer-profile-*, write access to a new index the team will create themselves called churn-predictions, no need for cluster-wide visibility beyond basic health, and the customer-profile-* indices contain a field called payment_method_token that should never leave the payments team’s own systems.

Translating those answers into a role produces something like this, in plain language rather than raw syntax: a cluster privilege of monitor only; an index privilege of read on the pattern customer-events-* with no field restrictions, since that data was already considered non-sensitive; an index privilege of read on the pattern customer-profile-* with field-level security excluding payment_method_token; and an index privilege of create_index combined with write scoped specifically to the pattern churn-predictions, so the team can create and populate their own output index without touching anyone else’s. Every single privilege in that list traces back directly to something the team actually said they needed, which is exactly the discipline that keeps a role from quietly growing broader than its job requires.

Beyond deciding which indices someone can touch, Elasticsearch can restrict access down to individual fields and individual documents within an index that a role otherwise permits.

Document-level security (DLS)

Document-level security restricts which specific documents inside an otherwise-accessible index a user’s search results are allowed to include. It works by attaching a query to the index permission within a role — the same kind of query you would write in an ordinary search request — and Elasticsearch silently applies that query as a filter on every request the role makes against that index. A role restricted to documents where region equals APAC, for instance, will simply never return documents from any other region, regardless of what the underlying search itself asked for.

This filtering can even reference details about the currently authenticated user through templating, so a single role definition can dynamically restrict each user to their own department, region, or account, rather than requiring one hand-written role per department.

Field-level security (FLS)

Field-level security restricts which specific fields within a document a role can see, using grant and except lists, with wildcard patterns supported for both. A role might grant access to an entire customer.* field group while separately excluding the specific customer.tax_id field from within that same group, hiding one sensitive piece of an otherwise visible record.

Field-level security also combines across multiple roles, but unlike document-level security’s OR-based filtering of rows, field visibility combines as a union of allowed fields — a user with two roles sees every field either role individually grants, and again, if any single role has no field restriction configured for an index at all, every field in that index becomes visible through that role, overriding any narrower restriction another role tried to apply.

Interactions with write operations

A role that applies field-level security cannot be used to perform update operations, including the update API and bulk updates, because partially modifying a document containing fields the role cannot even see would create ambiguous, unsafe behavior — Elasticsearch has no sensible way to decide what should happen to fields a role cannot view but a write operation might otherwise touch. Certain other index-management actions, including cloning, shrinking, splitting, and working with certain alias operations, are similarly restricted or disallowed for roles using field-level or document-level security, since these operations reshape or copy an index in ways that do not interact cleanly with per-field or per-document restrictions.

Fields that stay visible no matter what

A small set of internal metadata fields, such as the document identifier and the routing value, remain accessible regardless of any field-level security configuration on a role. This is intentional rather than an oversight: these fields carry structural information Elasticsearch itself needs to locate and manage a document correctly, rather than business data that could be considered sensitive on its own, so restricting them would break normal operation without adding any meaningful protection.

Performance considerations for DLS and FLS

Document-level security is implemented as an additional filter applied to every query against the restricted index, which means it does carry a small, generally modest performance cost compared to an unrestricted query, since Elasticsearch has to evaluate the filter alongside whatever the request itself asked for. Certain advanced search features are deliberately disabled when document-level security is active on a request, including search profiling and suggesters, along with some caching optimizations for particularly complex or templated queries, because these features do not combine safely or efficiently with a per-user filtering layer sitting underneath them.

RBAC is powerful, but it is a design discipline, not a switch you flip once and forget.

RBAC is one layer of a larger security posture. Understanding where it ends, and what picks up from there, prevents a false sense of complete protection.

RBAC assumes authentication already succeeded

Every guarantee RBAC provides rests on the assumption that the identity it is authorizing is genuine. If authentication itself is weak — passwords that never expire, no multi-factor authentication, or overly trusting external identity provider configuration — then RBAC is authorizing an identity that may not actually belong to the person it claims to. A carefully designed set of roles cannot compensate for a front door that was never properly locked.

Credentials and API keys still need their own hygiene

A role that follows the principle of least privilege perfectly still needs the credentials carrying it to be handled responsibly: rotated periodically, never committed into source control, and scoped through API keys with as short a lifetime and as narrow a role attachment as the situation allows. An API key created with an extremely broad role attached defeats much of the purpose of using a scoped API key at all, even though the key mechanism itself is sound.

Auditing closes the loop

RBAC prevents unauthorized actions; audit logging records what was attempted, whether it succeeded or was blocked, and by whom. The two work together: RBAC is the lock, and audit logging is the record of every attempt to turn the handle. A mature security posture treats denied-by-RBAC events in the audit log as worth periodically reviewing, since a pattern of repeated denials against the same sensitive index can be an early signal of either a misconfigured application or a genuine attempted intrusion.

Seeing RBAC applied to genuine, common situations makes the concept concrete rather than abstract.

Practical guidance for building an RBAC setup that stays trustworthy as an organization and its data grow.

Common mistakes to avoid