elasticsearch-authn

name	elasticsearch-authn
description	Authenticate to Elasticsearch using native, file-based, LDAP/AD, SAML, OIDC, Kerberos, JWT, or certificate realms. Use when connecting with credentials, choosing a realm, or managing API keys.
metadata	{"author":"elastic","version":"0.1.0","source":"elastic/agent-skills//skills/elasticsearch/elasticsearch-authn"}

Elasticsearch Authentication

Authenticate to an Elasticsearch cluster using any supported authentication realm that is already configured. Covers all built-in realms, credential verification, and the full API key lifecycle.

For roles, users, role assignment, and role mappings, see the elasticsearch-authz skill.

Critical principles

• Never ask for credentials in chat. Secrets must not appear in conversation history.
• Always use environment variables. Instruct the user to set them in a .env file in the project root.

Authentication Realms

Elasticsearch evaluates realms in a configured order (the realm chain). The first realm that can authenticate the request wins.

Internal realms

Native (username and password)

curl -u "${ELASTICSEARCH_USERNAME}:${ELASTICSEARCH_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

File

Users defined in flat files on each cluster node. Always active regardless of license state. Self-managed only.

curl -u "${FILE_USER}:${FILE_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

External realms

LDAP / Active Directory

Self-managed only. Combined with role mappings to translate LDAP/AD groups to Elasticsearch roles.

curl -u "${LDAP_USER}:${LDAP_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"

PKI (TLS client certificates)

Requires PKI realm and TLS on HTTP layer.

curl --cert "${CLIENT_CERT}" --key "${CLIENT_KEY}" --cacert "${CA_CERT}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"

SAML / OIDC

Primarily for Kibana SSO. Browser-based redirect flow, not for REST clients. Configure another realm alongside for programmatic API access.

JWT

Accepts JWTs as bearer tokens.

curl -H "Authorization: Bearer ${JWT_TOKEN}" "${ELASTICSEARCH_URL}/_security/_authenticate"

Kerberos

Self-managed only. Requires KDC infrastructure, DNS, and time synchronization.

kinit "${KERBEROS_PRINCIPAL}"
curl --negotiate -u : "${ELASTICSEARCH_URL}/_security/_authenticate"

API keys

Preferred for programmatic and automated access.

curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" "${ELASTICSEARCH_URL}/_security/_authenticate"

Manage API Keys

Create an API key

curl -X POST "${ELASTICSEARCH_URL}/_security/api_key" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"${KEY_NAME}"'",
    "expiration": "30d",
    "role_descriptors": {
      "'"${ROLE_NAME}"'": {
        "cluster": [],
        "indices": [
          {
            "names": ["'"${INDEX_PATTERN}"'"],
            "privileges": ["read"]
          }
        ]
      }
    }
  }'

The response contains id, api_key, and encoded. Store encoded securely — it cannot be retrieved again.

Limitation: An API key cannot create another API key with privileges. Use POST /_security/api_key/grant with user credentials instead.

Get and invalidate API keys

curl "${ELASTICSEARCH_URL}/_security/api_key?name=${KEY_NAME}" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/api_key" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{"name": "'"${KEY_NAME}"'"}'

Deployment Compatibility

Realm	Self-managed	ECH	Serverless
Native	Yes	Yes	Not available
File	Yes	Not available	Not available
LDAP / AD	Yes	Not available	Not available
PKI	Yes	Limited	Not available
SAML	Yes	Yes (deployment config)	Organization-level
OIDC	Yes	Yes (deployment config)	Not available
JWT	Yes	Yes (deployment config)	Not available
Kerberos	Yes	Not available	Not available
API keys	Yes	Yes	Yes

Guidelines

• Prefer API keys for automated workflows — they support fine-grained scoping and independent expiration.
• Never use the elastic superuser for day-to-day operations.
• Always set expiration on API keys. Avoid indefinite keys in production.
• Never receive, echo, or log passwords, API keys, or any credentials in chat.