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

• 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

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

-v

• WWW-Authenticate

  header — indicates which auth schemes the cluster accepts.

• authentication_exception

  in the response body — the

  reason

  field describes what failed.

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

• 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.

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

• Incorrect

  xpack.security.authc.realms.saml.*.sp.acs

  or

  idp.metadata.path

  in

  elasticsearch.yml

  .
• Clock skew between the IdP and Elasticsearch nodes (SAML assertions have a validity window).
• Kibana

  server.publicBaseUrl

  does not match the SAML ACS URL.

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

logs-*

1. Verify identity:

curl -u "joe:${PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

"roles": ["viewer"]

1. Test privileges:

curl -X POST "${ELASTICSEARCH_URL}/_security/user/_has_privileges" \
  -u "joe:${PASSWORD}" \
  -H "Content-Type: application/json" \
  -d '{"index": [{"names": ["logs-*"], "privileges": ["read"]}]}'

"has_all_requested": false

viewer

read

logs-*

1. Fix: create a

   logs-reader

   role and assign it to Joe. See elasticsearch-authz.

1. Check the key:

curl -u "admin:${PASSWORD}" "${ELASTICSEARCH_URL}/_security/api_key?name=my-key"

"expiration": 1709251200000

1. Fix: create a new API key with a suitable

   expiration

   . See elasticsearch-authn.

1. Check if the SAML realm is reachable by authenticating with a non-SAML method:

curl -u "elastic:${PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

1. Verify the IdP metadata URL is accessible from the Elasticsearch nodes (self-managed):

curl -s "${IDP_METADATA_URL}" | head -5

1. Check for clock skew — SAML assertions are time-sensitive. Ensure NTP is configured on all nodes.
2. Verify

   server.publicBaseUrl

   in

   kibana.yml

   matches the SAML ACS URL configured in the IdP.

1. Check license:

curl -u "admin:${PASSWORD}" "${ELASTICSEARCH_URL}/_license"

"status": "expired"

"type": "platinum"

1. The SAML realm is disabled because the paid license expired. Follow the recovery steps in elasticsearch-license: log in with a file-based or native user, then upload a renewed license or revert to basic.

_security/_authenticate

_security/user/_has_privileges

_xpack

_license

_security/api_key

_security/role_mapping

elasticsearch-users

openssl s_client

• No node-level access, so the

  elasticsearch-users

  CLI and direct log/certificate inspection are not available.
• TLS is managed by Elastic — certificate errors typically indicate an incorrect endpoint URL.
• Use the Cloud console for log inspection and deployment configuration.

• Licensing APIs are not exposed. License-related lockouts do not occur.
• Native users do not exist — authentication issues are handled at the organization level.
• TLS is fully managed and transparent.