Elasticsearch Security Troubleshooting

Elasticsearch Security Troubleshooting

Diagnose and resolve common Elasticsearch security issues. This skill provides a structured triage workflow for authentication failures, authorization errors, TLS problems, API key issues, role mapping mismatches, Kibana login failures, and license-expiry lockouts.

For authentication methods and API key management, see the elasticsearch-authn skill. For roles, users, and role mappings, see the elasticsearch-authz skill. For license management, see the elasticsearch-license skill.

For diagnostic API endpoints, see references/api-reference.md.

Deployment note: Diagnostic API availability differs between self-managed, ECH, and Serverless. See Deployment Compatibility for details.

Jobs to Be Done

• Diagnose HTTP 401 authentication failures
• Diagnose HTTP 403 permission denied errors
• Troubleshoot TLS/SSL handshake or certificate errors
• Investigate expired or invalid API keys
• Debug role mappings that do not grant expected roles
• Fix Kibana login failures, redirect loops, or CORS errors
• Recover from a license-expiry lockout
• Determine why a user lacks access to a specific index

Prerequisites

Prompt the user for any missing values. If the user cannot authenticate at all, start with TLS and Certificate Errors or License Expiry Recovery.

Diagnostic Workflow

Route the symptom to the correct section:

Each section follows a Gather - Diagnose - Resolve pattern.

Diagnostic Toolkit

Use these APIs at the start of any security investigation:

curl <auth_flags> "${ELASTICSEARCH_URL}/_security/_authenticate"

Confirms identity, realm, and roles. If this fails with 401, the problem is authentication.

curl <auth_flags> "${ELASTICSEARCH_URL}/_xpack"

Confirms whether security is enabled (features.security.enabled). If security is disabled, all security APIs return errors.

curl -X POST "${ELASTICSEARCH_URL}/_security/user/_has_privileges" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "index": [
      { "names": ["'"${INDEX_PATTERN}"'"], "privileges": ["read"] }
    ]
  }'

Tests whether the authenticated user holds specific privileges without requiring manage_security.

curl <auth_flags> "${ELASTICSEARCH_URL}/_license"

Check license type and status. An expired paid license disables paid realms and features.

Authentication Failures (401)

A 401 response means Elasticsearch could not verify the caller's identity.

Gather

curl -v <auth_flags> "${ELASTICSEARCH_URL}/_security/_authenticate" 2>&1

The -v flag shows headers and the response body. Look for:

• WWW-Authenticate header — indicates which auth schemes the cluster accepts.
• authentication_exception in the response body — the reason field describes what failed.

Diagnose

If the user authenticates via an external realm (LDAP, AD, SAML, OIDC), the realm chain order matters. Elasticsearch tries realms in configured order and stops at the first match. If a higher-priority realm rejects the credentials before the intended realm is reached, authentication fails.

Resolve

Authorization Failures (403)

A 403 response means the user is authenticated but lacks the required privileges.

Gather

Test the specific privileges the operation requires:

curl -X POST "${ELASTICSEARCH_URL}/_security/user/_has_privileges" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "index": [
      { "names": ["logs-*"], "privileges": ["read", "view_index_metadata"] }
    ],
    "cluster": ["monitor"]
  }'

The response contains a has_all_requested boolean and per-resource breakdowns.

Also check the user's effective roles:

curl <auth_flags> "${ELASTICSEARCH_URL}/_security/_authenticate"

Inspect the roles array and authentication_realm to confirm the user is who you expect.

Diagnose

Resolve

TLS and Certificate Errors

TLS errors prevent the client from establishing a connection at all.

Gather

curl -v --cacert "${CA_CERT}" "https://${ELASTICSEARCH_HOST}:9200/" 2>&1 | head -30

Look for:

• SSL certificate problem: unable to get local issuer certificate — CA not trusted.
• SSL certificate problem: certificate has expired — certificate past its validity date.
• SSL: no alternative certificate subject name matches target host name — hostname mismatch.

For deeper inspection (self-managed only):

openssl s_client -connect "${ELASTICSEARCH_HOST}:9200" -showcerts </dev/null 2>&1

This displays the full certificate chain, expiry dates, and subject alternative names.

Diagnose

Resolve

On ECH, TLS is managed by Elastic — certificate errors usually indicate the client is not using the correct Cloud endpoint URL. On Serverless, TLS is fully managed and transparent.

API Key Issues

Gather

Retrieve the key's metadata:

curl "${ELASTICSEARCH_URL}/_security/api_key?name=${KEY_NAME}" <auth_flags>

Check expiration, invalidated, and role_descriptors in the response.

Diagnose