Before learning the feature, it helps to feel the pain it removes.

Elasticsearch is a search and analytics engine. It stores data as documents, which are like rows in a table or cards in a card box, and it keeps groups of documents together in an index. Companies love it because it can search millions of documents in a blink. The trouble starts when a single index holds information of very different sensitivity.

Think about a customer index in a bank. Each document may hold a customer name, a city, an account type, a phone number, a tax identifier and a risk score. The marketing team wants the city and the account type. The fraud team wants the risk score. The call-centre agent needs the name and phone number to help a caller. Almost nobody needs everything, and handing everything to everybody is a data-leak waiting to happen.

The two clumsy solutions people try first

The first clumsy solution is to make many copies of the data, one index per audience, each with only the allowed fields. This works, but it multiplies storage, doubles the indexing work, and creates the risk that the copies drift apart. If a customer changes their phone number, you must update every copy.

The second clumsy solution is to trust the application. The application sits in front of Elasticsearch, fetches everything, and removes the secret fields before showing the result. That is fragile. One forgotten filter in one new screen, or one developer who queries Elasticsearch directly, and the secret field is exposed.

Field-Level Security, often shortened to FLS, solves both problems. The rules live inside the Elasticsearch cluster, attached to roles, so every path into the data obeys them, whether the request came from a web app, a dashboard, a script or a curious engineer with a command line.

A plain definition first, then the vocabulary you will keep meeting.

Field-Level Security is an Elasticsearch feature that controls which fields of a document a user is allowed to read. You attach a list of permitted fields to a role. When a person holding that role searches, Elasticsearch behaves as if the forbidden fields do not exist at all for that person.

Notice the wording “do not exist”. This is stronger than simply hiding a field in the final output. The forbidden field cannot be read in the results, cannot be used inside a query to filter documents, cannot be used to sort, and cannot be counted in an aggregation. That single design choice is what makes FLS trustworthy, and we will return to it many times.

Words you need to know

Where does FLS sit in the bigger picture?

Elasticsearch offers security in layers. The outer layer decides whether you may talk to the cluster at all. The next layer decides which indices you may touch. FLS is a finer layer that works inside an index and decides which columns you may read. A sibling feature called Document-Level Security works on rows instead of columns. Together they let you cut a single index both horizontally and vertically.

FLS does not stand alone. It is one setting inside Elasticsearch’s role-based access control.

To understand where the field rules live, you need a quick tour of how Elasticsearch decides who can do what. The system has two separate questions. The first is authentication: who are you? The second is authorization: what are you allowed to do? FLS belongs to the second question.

Authentication: proving who you are

Elasticsearch checks your identity through a realm. A realm is simply a source of identities. It can be the built-in native user store, a file, an LDAP or Active Directory directory, a single sign-on system using SAML or OpenID Connect, or an API key. Whichever realm accepts you, the result is the same: Elasticsearch now knows a username and a set of roles.

Authorization: role-based access control

Elasticsearch uses role-based access control, usually written as RBAC. Instead of giving permissions to each person one by one, you give permissions to roles and then attach roles to people. When the accounting team grows from four people to forty, you only add forty names to one role.

What a role can contain

The key point is that field security is a property of an index privilege entry. A role says: “for indices matching these names, allow these actions, and only on these fields”. So the same role can be strict on one index and relaxed on another.

Role mapping: connecting people to roles

When your users come from an outside directory or single sign-on, you use role mappings. A role mapping is a rule such as “anyone in the finance group gets the finance-reader role”. This means FLS scales to large companies, because the identity team manages group membership and the search team manages roles.

The whole feature comes down to two small lists.

Inside an index privilege entry, the field rules are stored in a section called field_security. It has two parts: grant and except. You will usually create them in Kibana’s role screen or through the security API, but the ideas are the same in both places.

The grant list

The grant list names the fields the role may see. Names can be exact, such as name, or they can use a wildcard, such as address.*, which means “everything below address”. A single star means “every field”. If a role has no field security section at all, the role sees every field, so leaving it out is a wide-open choice.

An empty grant list is the opposite extreme. It means no ordinary fields are visible. System-managed metadata, such as the document identifier and the index name, remains available, because Elasticsearch needs it to function.

The except list

The except list removes fields from what the grant list allowed. It exists because it is often easier to say “everything except three secret fields” than to list two hundred safe ones. You combine a broad grant with a narrow except.

Two styles of thinking: allow-list and deny-list

The first style is the allow-list. You name only the fields that are safe and everything else is hidden. This is the safer style, because when a developer adds a new sensitive field next month, it stays hidden by default. The second style is the deny-list. You allow everything and hide named fields. This is convenient, but a newly added secret field is visible to everybody until someone remembers to update the role.

Understanding the mechanism explains every surprising behaviour you will meet later.

Elasticsearch is built on a library called Lucene. Each index is split into pieces called shards, and each shard is a small Lucene index. When you search, every shard reads its own data and returns matches. FLS works at this low level, right where data is read from disk.

A wrapper around the reader

When a user with field rules searches a shard, Elasticsearch wraps the normal reader in a special filtering reader. This wrapper looks at the user’s allowed field names and behaves as if any other field is not part of the index. When the search code asks “does this field exist?”, the wrapper answers no for forbidden fields. When the code asks for stored values, the wrapper leaves out the forbidden ones.

flowchart TD
    A["Search request arrives with user identity"] --> B["Security layer finds the user's roles"]
    B --> C["Roles combined into allowed field patterns for the index"]
    C --> D["Each shard wraps its reader with a field filter"]
    D --> E["Query, sort and aggregation see only allowed fields"]
    E --> F["Stored source is trimmed to allowed fields"]
    F --> G["Coordinating node merges shard results"]
    G --> H["User receives a reduced response"]
        

The diagram shows an important idea. The filtering does not happen at the very end on the assembled answer. It happens inside every shard, before matching, scoring and aggregating. That is why hidden fields cannot leak through side doors such as a filter or a bucket count.

The trimmed source document

Elasticsearch stores the original JSON of each document in a special field called _source. When you fetch a document or run a search, this is usually what you see returned. With FLS active, the source is rebuilt on the fly so that it contains only allowed fields. The stored original is untouched; only the copy handed to that user is trimmed.

Why security is decided before matching

Suppose the field filter were applied only on the final output. A clever user could then type a search like “salary greater than 100000” and learn, from which documents came back, who earns a lot, even though the salary column was never shown. By hiding the field from the query engine itself, Elasticsearch treats that search as a query on a non-existent field, which matches nothing useful.

Follow one request from the keyboard to the screen.

Let us walk through what happens when an HR analyst named Meera searches an employee index. Her role allows the name, department and job title, but not the salary or the home address.

sequenceDiagram
    participant U as Analyst
    participant K as Kibana or App
    participant E as Elasticsearch Security
    participant S as Shards
    U->>K: Search engineering staff
    K->>E: Request with credentials
    E->>E: Authenticate and load roles
    E->>E: Check index privilege and field rules
    E->>S: Search with field filter attached
    S-->>E: Matches with trimmed source
    E-->>K: Combined response
    K-->>U: Name, department, title only
        

What happens when the rules change?

Roles are stored inside the cluster and cached by the security layer. When an administrator edits a role, Elasticsearch clears the cached copy so that new requests pick up the change. You do not need to reindex data or restart anything, because field rules are only a lens applied at read time. This makes it cheap to fix a mistake quickly.

A tour of every place a hidden field might try to appear.

A good security control has no back doors. Here is how FLS treats the many ways a client can read data from Elasticsearch.

The mapping is filtered too

A mapping is Elasticsearch’s description of an index: which fields exist and what type each one has. If the mapping still listed a field called salary, the user would at least learn that salary data exists. With FLS, the mapping shown to the user leaves such fields out, so even the existence of the field is not revealed.

What FLS does not change

Some things stay the same for everyone. The total number of documents an index holds is not altered by hiding a field, because FLS hides columns, not rows. If you want some documents to disappear for some users, you need Document-Level Security. Also, system metadata such as the document identifier, index name and routing value remains visible.

Three cutting tools, three different shapes of cut.

Elasticsearch gives you three levels of data restriction. Beginners often mix them up, so let us separate them clearly.

Using them together

The real power appears when you combine them. Imagine a shared index of support tickets from many customer companies. Index-level security lets the support team read the ticket index. Document-level security limits each agent to tickets from their assigned customers. Field-level security hides the internal cost and margin notes from everyone except managers. One index, three lenses, no duplication.

Real people wear many hats, and Elasticsearch has to combine their permissions.

In a real company, one person often belongs to several groups. A data analyst may also be a member of the finance reviewers group. Each group maps to a role, so the person ends up holding several roles at once. Elasticsearch must then decide what the person can see when two roles say different things about the same index.

The additive rule

Permissions in Elasticsearch are additive. There is no “deny” rule that beats an “allow” rule. If any one role grants access to a field, the person can see that field. In other words, the field permissions from the different roles are combined into a union.

graph LR
    R1["Role A grants name and city"] --> U["Combined view for the user"]
    R2["Role B grants city and balance"] --> U
    U --> V["User sees name, city and balance"]
        

The trap of the wide role

Here is the part that surprises many teams. If one of the user’s roles has no field restriction at all on an index, that role is effectively granting every field. Because permissions add up, the restricted role can no longer protect anything. A single forgotten broad role can undo careful work in ten other roles.

Mixing document and field rules across roles

The same additive thinking applies when roles mix row rules and column rules. In general, the user gets the documents any role allows and the fields any role allows, and you should not assume that a field granted by one role stays tied to only the documents that same role allowed. When a user holds several roles with different row and column rules on the same index, the combined outcome can be wider than any single role intended.

The same technique protects very different kinds of data across industries.

A repeatable method that works for any dataset.

Good FLS is more about thinking than typing. The steps below turn a messy “who should see what” conversation into a clean set of roles.

Know what FLS protects, and just as important, what it does not.

FLS is about reading, not writing

Field-Level Security is a read-side control. It shapes what a user sees when reading. It is meant to be used with read-oriented privileges, and combining it with powerful write privileges on the same index is discouraged. Some write style operations, most notably the update-by-document operation, are not allowed when field or document security is active on the index, because a partial view of a document cannot safely be merged back into the full document.

Copying data can escape the filter

Anyone who can read data can, in principle, copy what they see to a new place. A user allowed to see a name and a phone number can export those two fields into a spreadsheet. FLS controls the view, but it does not stop authorized users from sharing what they legitimately saw. Policies, training and export controls must cover that human side.

Powerful roles bypass everything

Superuser accounts and roles with broad administrative privileges are not limited in the way normal read roles are. Anyone who can edit roles can also give themselves more access. Guard these accounts with strong authentication, keep the list very short, and record what they do.

The data on disk is not encrypted by FLS

FLS decides what a query can return. It does not encrypt shard files, snapshots or backups. Someone with access to the machine, a disk image or a snapshot repository could read the raw data. Protect these with disk encryption, network controls and strict access to the storage layer.

No built-in masking

FLS either shows a field or hides it. It does not show a partially masked value such as the last four digits of a card. If you need masking, prepare a separate masked field when the data is indexed, for instance with an ingest pipeline, and then grant the masked field to broad audiences while keeping the full field restricted.

Other features to double check

Cross-cluster search, reindexing, data views in Kibana and features that copy or transform data each have their own rules about how field and document security apply. Before relying on FLS in a new workflow, read the documentation for that feature in your exact version, and test it with a restricted user. Behaviour can differ between versions, so retest after upgrades.

A security feature should be observable and should not slow the business down.

Performance in plain words

Because FLS puts a filter around the reader, every request from a restricted user does a little extra work. For typical role definitions this cost is small compared with the cost of the search itself. The cost grows when role definitions are complicated, with very many overlapping wildcard patterns, or when a user holds many roles that all have to be merged. Simple, clean role definitions are both easier to understand and cheaper to run.

Auditing who accessed what

Elasticsearch can write audit logs that record security events such as successful logins, failed logins, access granted and access denied. These logs tell you which user touched which index and when. In general they record the request and its outcome rather than listing which individual fields were filtered out, so pair them with a good role review process.

What to monitor

Watch for repeated access-denied events, which may signal a misconfigured application or a person probing the system. Watch for changes to role definitions, because role edits are the moment a careful design can be quietly weakened. Send audit logs to a separate protected place so that an administrator cannot easily erase their own footprints.

Habits that age well, and habits that cause incidents.

Patterns worth copying

Anti-patterns to avoid

FLS versus other approaches

An honest look at what you gain and what you pay.

A short checklist you can print and pin next to your desk.

Best practices

Common mistakes

Quick answers to the doubts beginners raise most often.

It is part of Elastic’s paid subscription features, not the free basic tier. Check the current subscription comparison for the exact tier your version and deployment type requires.

No. The stored documents are unchanged. FLS only changes what a particular user is allowed to read at query time.

No. A hidden field is treated as if it does not exist for that user, so filters, sorts and aggregations on it do not reveal anything.

FLS hides columns, meaning specific fields. DLS hides rows, meaning whole documents, based on a query stored in the role. They are often used together.

Neither wins. Permissions are additive, so the user gets the combined set of fields from all roles. If one role has no field restriction, the user can see every field.

No. Field rules are applied when data is read, so an edited role takes effect for new requests without touching the stored data.

Not by itself. A field is either visible or hidden. For partial masking, create a masked field when the data is indexed and grant that field to the broader audience.

No. FLS works when data is queried through Elasticsearch. Protect raw files and snapshots with encryption and strict storage permissions.

Yes. Kibana talks to Elasticsearch as the signed-in user, so dashboards and Discover show only the fields that person may read. A visualization that depends on a hidden field will show empty or partial results for them.

Create a test user with the same roles, or use the run-as privilege to send requests on that person’s behalf, and inspect the results, the mapping and any dashboards.

Field-Level Security lets one Elasticsearch index serve many audiences without duplicating data. Rules are written as grant and except lists inside roles, enforced deep in each shard, and applied to results, queries, sorting, aggregations and mappings alike. Used with document-level rules and good role design, it turns “everyone sees everything” into “everyone sees what their job needs”. Its strength depends on careful design: allow-lists, small purpose-driven roles, honest testing as restricted users, and regular review.