Elasticsearch / Advanced: resilient and recoverable retrieval / Lesson 15

TLS, API keys and access boundaries

Define a narrow search principal and distinguish transport trust, authentication and authorization.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Scope credentials to explicit runtime actions and destinations.
Explain role intersections and the limits of filters and source shaping.

Trust, identity and permission are different checks

TLS verifies and protects the communication channel when correctly configured. Authentication identifies the principal, and authorization decides which actions and data that principal can access. A certificate trust error is not fixed by broadening index privileges; a forbidden action is not fixed by disabling certificate verification. Record the intended endpoint name, trusted certificate chain and runtime identity separately. Elastic deployment types provide different setup workflows, so inspect the actual environment rather than assuming every package has identical automatic configuration. The course never supplies credentials or connects to an endpoint.

Separate search, ingestion and administration

A public catalog search service usually needs read access to a controlled logical target, not permission to create indices, manage pipelines or delete snapshots. Ingestion needs a different set of actions, and deployment administration is another identity. The role descriptor fragment below grants read on a fictional museum-search alias only. Alias and concrete-index privilege semantics must be reviewed for the actual access path. This fragment is a policy proposal, not a created role. Keep denied-action tests alongside allowed calls so the team verifies that a successful search did not accidentally grant a broad maintenance surface.

json Illustrative technical example; logical results are reasoned, not engine-tested.

{"cluster":[],"indices":[{"names":["museum-search"],"privileges":["read"],"allow_restricted_indices":false}]}

A role-descriptor fragment for review. It is not sent to the role API and contains no secret.

An API key is a managed secret with bounded authority

An API key creation request can include role descriptors and an expiration. Effective authority is constrained by the documented intersection with the creator’s privileges, not just the desired role text. Omitting descriptors can snapshot a broader creator privilege set, so choose scope deliberately. Default keys can be nonexpiring unless an expiration is specified; a one-day example is a scenario value, not a universal rotation policy. The body below describes a synthetic read key without creating it. Never embed returned credentials in browser code, course files, logs or public support evidence.

json Illustrative technical example; logical results are reasoned, not engine-tested.

{"name":"museum-search-lab","expiration":"1d","role_descriptors":{"catalog_reader":{"cluster":[],"indices":[{"names":["museum-search"],"privileges":["read"]}]}}}

Illustrative API-key request body only. No key is generated, stored or shown; the creator must have approved key-management authority.

A UI filter is not a security boundary

An application filter for department=public can be omitted if an untrusted caller controls arbitrary DSL. Likewise _source filtering changes response shape and is not field-level security. Enforce mandatory policy in a trusted application layer and supported security controls. Document-level and field-level security have feature and subscription boundaries that must be checked for the exact offering. A filtered alias also has documented limitations and should not be treated as a universal authorization mechanism. Review every accessible endpoint, including direct document retrieval, aggregations and alternate index names, against the intended data boundary.

Credential lifecycle includes evidence and recovery

Define storage ownership, rotation, revocation, incident response and application reload behavior. A revoked credential can leave clients retrying indefinitely unless failures are classified and surfaced. Preserve redacted key identifiers where useful, not secret values. Test one allowed search and denied write, administrative and cross-target actions in a separately authorized synthetic lab. Check current source-code licensing, distribution terms and subscription features independently: an AGPL option for eligible source portions does not mean every binary feature or managed service is Apache-licensed or free. This lesson creates no account, key, role or TLS configuration and claims no security test against a cluster.

Common errors and fixes

security_exception

Why it happens: Authentication failed or the authenticated principal lacks the required action privilege.
How to fix it: Preserve HTTP status and detailed cause, then inspect identity and intended scope.
Prevent it next time: Verify runtime permissions with narrow allowed and denied cases.

Certificate verification is disabled to make a request work

Why it happens: Transport trust failure was bypassed instead of repaired.
How to fix it: Repair the approved endpoint name and trust chain.
Prevent it next time: Keep trusted certificates and endpoint identity in deployment configuration.

A search key can perform unintended maintenance

Why it happens: The credential inherited or received overly broad authority.
How to fix it: Review descriptors, creator intersection and actual denied-action evidence.
Prevent it next time: Separate runtime search from ingestion and administration identities.

Check your understanding

1. Does _source:["title"] prevent a principal from reading other fields through another request?

Show worked solution

No. It shapes that response. Enforce the actual field and document access policy through supported authorized controls and a trusted interface. Test alternate retrieval paths and verify the subscription boundary before relying on specialized security features.

2. Why can an API-key request with no descriptors be broader than expected?