Use Elasticsearch API keys and least-privilege roles

The fix

# A role scoped to one index pattern and specific actions
curl -sk -u elastic -X PUT https://localhost:9200/_security/role/app_search -H 'Content-Type: application/json' -d '{
  "indices": [{
    "names": ["app-*"],
    "privileges": ["read", "view_index_metadata"]
  }]
}'

# An API key that grants only that role
curl -sk -u elastic -X POST https://localhost:9200/_security/api_key -H 'Content-Type: application/json' -d '{
  "name": "app-search-key",
  "role_descriptors": { "app_search": { "indices": [{ "names": ["app-*"], "privileges": ["read"] }] } }
}'

Why it matters

Every credential is a blast radius. An application authenticating as elastic can read every index, delete every index, change cluster settings and create users — so a SQL-injection equivalent, a leaked config file, or a compromised app container hands all of that to an attacker.

Scope it down and the same leak is bounded: a key limited to read on app-* reads some documents and can do nothing else. No deletes, no other indices, no cluster administration.

Elasticsearch’s RBAC makes this cheap, and there’s no reason an application should ever hold more than the specific privileges it uses.

The three levers

A role descriptor narrows on three axes, and using all three is the point:

Axis	Example	Effect
Indices	"names": ["app-*"]	Cannot touch other indices, including system ones
Privileges	["read", "view_index_metadata"]	No write, no delete_index, no manage
Documents / fields	query and field_security	Row- and column-level limits within an index

The index scope is the one people skip. "names": ["*"] in a role is elastic-lite — it can read everything even if the privileges are narrow. Document-level security (a query in the role) and field-level security (a field_security block) go further, letting one key see only certain documents or certain fields — useful when a reporting tool needs orders but not the PII columns in them.

API keys beat user passwords for applications

For non-human callers, prefer an API key over a username and password:

• Keys are independently revocable. Kill one application’s key without touching any other credential or restarting anything.
• Keys can be scoped tighter than the user that created them — the role_descriptors in the key intersect with the creator’s privileges, so a key is never more powerful than intended even if created by a broad account.
• Keys can expire. Set "expiration": "90d" and the credential rotates itself out.
• A leaked key is one key. A leaked user password may be reused across services; a key is minted per consumer.

The one caveat: an API key is a bearer token. Anyone holding it is that key, so it still needs to be stored like a secret and sent only over TLS — which, on a secured cluster, it is.

Verify it worked

List roles and what they actually grant:

curl -sk -u elastic https://localhost:9200/_security/role?filter_path='*.indices' | python3 -m json.tool | head -40

Find roles scoped to everything — the ones that aren’t really scoped:

curl -sk -u elastic https://localhost:9200/_security/role | \
  python3 -c 'import sys,json; [print(r) for r,d in json.load(sys.stdin).items() for i in d.get("indices",[]) if "*" in i.get("names",[]) and "all" in i.get("privileges",[])]'

List API keys and their scopes:

curl -sk -u elastic https://localhost:9200/_security/api_key?filter_path='api_keys.name,api_keys.expiration,api_keys.invalidated'

Then prove a key’s limits — use the key and try something it shouldn’t be able to do:

curl -sk -H "Authorization: ApiKey $KEY" -X DELETE https://localhost:9200/some-other-index \
  -o /dev/null -w '%{http_code}\n'

Expect 403. If it’s 200, the key is wider than intended.

Check what a key can do, resolved:

curl -sk -H "Authorization: ApiKey $KEY" https://localhost:9200/_security/user/_has_privileges \
  -H 'Content-Type: application/json' -d '{"index":[{"names":["*"],"privileges":["all"]}]}'

"has_all_requested": false is what you want.

Before you apply this

Narrowing a role breaks the application at its next operation — a 403 in the middle of a request, not a clean startup failure — and only on the code path that used the privilege you removed.

Find out what the credential actually does before you cut it. If audit logging is available it records the actions; without it, check the application’s own logs and its query patterns. The common misses are the once-a-day jobs: an index-template update, a snapshot trigger, a reindex — each needs a manage or create_index privilege that day-to-day reads don’t.

Migrating from a shared user to a per-app key is the safe path, and it’s staged, not flipped:

1. Create the scoped role and mint a key for one application.
2. Deploy that application with the key. Confirm it works.
3. Repeat per application.
4. Once nothing uses the shared account, disable it.

Don’t set overly short expirations without rotation automation. A key with "expiration": "7d" and no process to mint a new one is a self-inflicted outage next week — the same trap as short-lived TLS certificates. Match the expiry to a rotation process you actually run, or leave it unset and revoke manually.

Keys are stored in the .security index. Filesystem or superuser access to the cluster can read and mint keys, so this control assumes the superuser is protected and the node’s filesystem is not casually accessible.

Related

• Built-in users and passwords — stop using elastic for apps.
• Enable TLS — API keys are bearer tokens; they need encryption.