elasticsearch-security-troubleshooting

A structured triage workflow for diagnosing and resolving common Elasticsearch security failures. It routes a reported symptom — an HTTP 401, an HTTP 403, a TLS handshake error, a rejected or expired API key, a role mapping that grants nothing, a broken Kibana login, or a full license-expiry lockout — to the matching diagnostic section, each of which follows a consistent Gather, Diagnose, Resolve pattern. Investigations begin with a small toolkit of read-only API calls: _security/_authenticate to confirm identity, realm, and effective roles; _xpack to verify security is enabled; _security/user/_has_privileges to test whether the caller holds specific index or cluster privileges without needing manage_security; and _license to check license type and status. Authentication troubleshooting reads the WWW-Authenticate header and the authentication_exception reason to distinguish wrong credentials, disabled users, expired tokens, and realm-chain ordering problems, noting that Elasticsearch tries realms in configured order and stops at the first match. Authorization troubleshooting compares requested privileges against the user's granted roles to find missing index or cluster privileges. Prerequisites are the cluster URL, any working credentials, and the monitor privilege for read-only diagnostics or manage_security to apply fixes. The workflow accounts for deployment differences across self-managed, Elastic Cloud Hosted, and Serverless, where diagnostic API availability varies. For deeper topics it defers to companion skills: elasticsearch-authn for authentication methods and API key management, elasticsearch-authz for roles, users, and role mappings, and elasticsearch-license for license management. Use it when a user reports a security error and needs a reliable path from symptom to root cause to remediation, particularly when locked out entirely, in which case it recommends starting from the TLS or license-recovery sections.