elasticsearch-authn

What this skill does

# Elasticsearch Authentication

Authenticate to an Elasticsearch cluster using any supported authentication realm that is already configured. This skill
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.

For detailed API endpoints, see [references/api-reference.md](references/api-reference.md).

> **Deployment note:** Not all realms are available on every deployment type. See
> [Deployment Compatibility](#deployment-compatibility) for self-managed vs. ECH vs. Serverless details.

## Critical principles

- **Never ask for credentials in chat.** Do not ask the user to paste passwords, API keys, tokens, or any secret into
  the conversation. Secrets must not appear in conversation history.
- **Always use environment variables.** All code examples in this skill reference environment variables (e.g.
  `ELASTICSEARCH_PASSWORD`, `ELASTICSEARCH_API_KEY`). When a required variable is missing, instruct the user to set it
  in a `.env` file in the project root — never prompt for the value directly.
- **Prefer `.env` over terminal exports.** Agents may run commands in a sandboxed shell session that does not inherit
  the user's terminal environment. A `.env` file in the working directory is reliable across all execution contexts.
  Only suggest `export` as a fallback when the user explicitly prefers it.

## Jobs to Be Done

- Authenticate to a cluster using username and password (native realm)
- Connect using an API key (bearer token)
- Verify who is currently authenticated (`_authenticate`)
- Choose the right authentication realm for a deployment
- Create an API key with scoped privileges for automation or service access
- Rotate or invalidate an existing API key
- Set up service account tokens for Elastic stack components
- Authenticate with PKI / mutual TLS certificate-based authentication after PKI/TLS setup
- Authenticate with configured external identity providers (SAML, OIDC, LDAP, AD, Kerberos)
- Grant API keys on behalf of other users

## Prerequisites

| Item                  | Description                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Elasticsearch URL** | Cluster endpoint (e.g. `https://localhost:9200` or a Cloud deployment URL)                                                  |
| **Credentials**       | Depends on the realm — see the methods below                                                                                |
| **Realms configured** | Authentication realms and their identity backends must already be configured (realm chain, IdP, LDAP/AD, Kerberos, PKI/TLS) |

If any required value is missing, instruct the user to add it to a `.env` file in the project root. Terminal exports may
not be visible to agents running in a separate shell session — the `.env` file is the reliable default. **Never ask the
user to paste credentials into the chat** — secrets must not appear in conversation history.

## Authentication Realms

Elasticsearch evaluates realms in a configured order (the **realm chain**). The first realm that can authenticate the
request wins. Internal realms are managed by Elasticsearch; external realms delegate to enterprise identity systems.

### Internal realms

#### Native (username and password)

Users stored in a dedicated Elasticsearch index. Simplest method for interactive use. Managed via Kibana or the user
management APIs (see the elasticsearch-authz skill).

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

#### File

Users defined in flat files on each cluster node (`elasticsearch-users` CLI). Always active regardless of license state,
making it the fallback for disaster recovery when paid realms are disabled. Only available on self-managed deployments.

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

### External realms

#### LDAP

Authenticates against an external LDAP directory using username and password. Self-managed only — not available on ECH
or Serverless. Typically combined with role mappings to translate LDAP groups to Elasticsearch roles.

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

The request is identical to native — Elasticsearch routes it to the LDAP realm via the realm chain.

#### Active Directory

Authenticates against an Active Directory domain. Self-managed only — not available on ECH or Serverless. Similar to
LDAP but uses AD-specific defaults (user principal name, `sAMAccountName`). Typically combined with role mappings for AD
group-to-role translation.

```bash
curl -u "${AD_USER}:${AD_PASSWORD}" "${ELASTICSEARCH_URL}/_security/_authenticate"
```

#### PKI (TLS client certificates)

Authenticates using X.509 client certificates presented during the TLS handshake. Requires a PKI realm and TLS on the
HTTP layer. On ECH, PKI support is limited — check deployment settings. Not available on Serverless. Best for
service-to-service communication in mutual TLS environments.

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

#### SAML

Enables SAML 2.0 Web Browser SSO, primarily for Kibana authentication. On self-managed, configure in
`elasticsearch.yml`. On ECH, configure through the Cloud deployment settings UI. On Serverless, SAML is handled at the
organization level and not configurable per project. Not usable by standard REST clients — the browser-based redirect
flow is handled by Kibana. Configure another realm (e.g. native or API keys) alongside SAML for programmatic API access.

#### OIDC (OpenID Connect)

Enables OpenID Connect SSO, primarily for Kibana authentication. On self-managed, configure in `elasticsearch.yml`. On
ECH, configure through the Cloud deployment settings UI. Not available on Serverless. Like SAML, it relies on browser
redirects and is not suited for direct REST client use. For programmatic access alongside OIDC, use API keys or native
users.

Custom applications can exchange OIDC tokens for Elasticsearch access tokens via `POST /_security/oidc/authenticate`,
but this requires implementing the full OIDC redirect flow.

#### JWT (JSON Web Tokens)

Accepts JWTs issued by an external identity provider as bearer tokens. On self-managed, configure in
`elasticsearch.yml`. On ECH, configure through the Cloud deployment settings UI. Not available on Serverless. Supports
two token types:

- **`id_token`** (default) — OpenID Connect ID tokens for user-on-behalf-of flows.
- **`access_token`** — OAuth2 client credentials for application identity flows.

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

Each JWT realm handles one token type. Configure separate realms for `id_token` and `access_token` if both are needed.

#### Kerberos

Authenticates using Kerberos tickets via the SPNEGO mechanism. Self-managed only — not available on ECH or Serverless.
Requires a working KDC infrastructure, proper DNS, and time synchronization.

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

The `--negotiate` flag enables SPNEGO. The `-u :` is required by curl but the username is ignored — the principal from
`kinit` is used. Requires curl 7.49+ with GSS-API/SPNEGO support.

### API keys

Not a realm, but a distinct authentication mechanism. Pass a Base64-encoded API key in the `Authorization` header.
Preferred for programmatic and automated access.

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

`ELASTICSEARCH_A