elasticsearch-authn

Elasticsearch 身份验证

使用已配置的任何受支持身份验证域向 Elasticsearch 集群进行身份验证。本技能涵盖所有内置域、凭据验证以及 API 密钥的完整生命周期。

有关角色、用户、角色分配和角色映射，请参阅 elasticsearch-authz 技能。

有关详细的 API 端点，请参阅 references/api-reference.md。

部署说明： 并非所有部署类型都支持所有域。有关自托管、ECH 和 Serverless 的详细信息，请参阅 部署兼容性。

关键原则

• 绝不要在聊天中索要凭据。 不要让用户将密码、API 密钥、令牌或任何机密粘贴到对话中。机密不得出现在对话历史记录中。
• 始终使用环境变量。 本技能中的所有代码示例都使用环境变量（例如 ELASTICSEARCH_PASSWORD、ELASTICSEARCH_API_KEY）。缺少必需变量时，请指导用户在项目根目录的 .env 文件中设置它，绝不要直接索要变量值。
• 优先使用 .env，而非终端导出变量。 Agent 可能会在沙盒 shell 会话中运行命令，而该会话不会继承用户终端的环境。工作目录中的 .env 文件在所有执行环境中都可靠。只有在用户明确偏好时，才将 export 作为备用方案。

待完成任务

• 使用用户名和密码向集群进行身份验证（native 域）
• 使用 API 密钥（持有者令牌）进行连接
• 验证当前身份验证用户（_authenticate）
• 为部署选择合适的身份验证域
• 创建具有指定权限范围的 API 密钥，用于自动化或服务访问
• 轮换或使现有 API 密钥失效
• 为 Elastic Stack 组件设置服务账号令牌
• 在完成 PKI/TLS 设置后，使用 PKI / 双向 TLS 证书进行身份验证
• 使用已配置的外部身份提供商（SAML、OIDC、LDAP、AD、Kerberos）进行身份验证
• 代表其他用户授予 API 密钥

先决条件

项目	说明
Elasticsearch URL	集群端点（例如 https://localhost:9200 或 Cloud 部署 URL）
凭据	视域而定 — 请参阅以下方法
已配置的域	身份验证域及其身份后端必须已配置（域链、IdP、LDAP/AD、Kerberos、PKI/TLS）

如果缺少任何必需值，请指导用户将其添加到项目根目录的 .env 文件中。在单独 shell 会话中运行的 Agent 可能无法访问终端导出的变量，因此 .env 文件是可靠的默认方案。绝不要让用户在聊天中粘贴凭据——机密不得出现在对话历史记录中。

身份验证域

Elasticsearch 按已配置的顺序评估各个域（即域链）。第一个能够验证请求的域将处理该请求。内部域由 Elasticsearch 管理；外部域则委托给企业身份系统。

内部域

Native（用户名和密码）

用户存储在专用的 Elasticsearch 索引中。最简单的交互式使用方式。通过 Kibana 或用户管理 API 管理（请参阅 elasticsearch-authz 技能）。

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

File

用户定义在每个集群节点上的纯文本文件中（使用 elasticsearch-users CLI）。无论许可证状态如何，此域始终处于启用状态，因此付费域被禁用时可作为灾难恢复的备用方案。仅适用于自托管部署。

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

外部域

LDAP

使用用户名和密码通过外部 LDAP 目录进行身份验证。仅适用于自管理部署——ECH 和 Serverless 不提供此功能。通常与角色映射结合使用，将 LDAP 组转换为 Elasticsearch 角色。

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

该请求与原生身份验证完全相同——Elasticsearch 会通过领域链将其路由到 LDAP 领域。

Active Directory

通过 Active Directory 域进行身份验证。仅适用于自管理部署——ECH 和 Serverless 不提供此功能。与 LDAP 类似，但使用 AD 专属默认值（用户主体名称、sAMAccountName）。通常与角色映射结合使用，将 AD 组转换为角色。

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

PKI（TLS 客户端证书）

使用 TLS 握手期间提交的 X.509 客户端证书进行身份验证。需要 PKI 领域，并在 HTTP 层启用 TLS。在 ECH 上，PKI 支持有限——请检查部署设置。Serverless 不提供此功能。最适合用于 相互 TLS 环境中的服务间通信。

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

SAML

启用 SAML 2.0 Web 浏览器单点登录（SSO），主要用于 Kibana 身份验证。在自管理部署中，通过 elasticsearch.yml 配置。在 ECH 上，通过 Cloud 部署设置界面配置。在 Serverless 上，SAML 在 组织级别处理，无法按项目配置。标准 REST 客户端无法使用此方式——基于浏览器的重定向流程由 Kibana 处理。除了 SAML，还要配置另一个领域（例如 native 或 API keys），以便通过程序访问 API。

OIDC（OpenID Connect）

启用 OpenID Connect 单点登录（SSO），主要用于 Kibana 身份验证。在自管理部署中，通过 elasticsearch.yml 配置。在 ECH 上，通过 Cloud 部署设置界面配置。Serverless 不提供此功能。与 SAML 一样，它依赖浏览器 重定向，不适合直接由 REST 客户端使用。若要在使用 OIDC 的同时通过程序访问，请使用 API keys 或 native 用户。

自定义应用可以通过 POST /_security/oidc/authenticate 将 OIDC 令牌换成 Elasticsearch 访问令牌， 但这需要实现完整的 OIDC 重定向流程。

JWT（JSON Web Token）

接受外部身份提供商签发的 JWT 作为持有者令牌。在自管理部署中，通过 elasticsearch.yml 配置。在 ECH 上，通过 Cloud 部署设置界面配置。Serverless 不提供此功能。支持 两种令牌类型：

• id_token（默认）——用于代表用户执行操作流程的 OpenID Connect ID 令牌。
• access_token——用于应用身份流程的 OAuth2 客户端凭据。

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

每个 JWT 领域仅处理一种令牌类型。如果两种类型都需要，请分别为 id_token 和 access_token 配置独立的领域。

Kerberos

通过 SPNEGO 机制使用 Kerberos 票据进行身份验证。仅适用于自管理部署——ECH 和 Serverless 不提供此功能。 需要正常运行的 KDC 基础设施、正确的 DNS 配置和时间同步。

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

--negotiate 标志会启用 SPNEGO。curl 要求提供 -u :，但会忽略用户名——实际使用的是 kinit 中的主体。需要支持 GSS-API/SPNEGO 的 curl 7.49+。

API keys

这不是领域，而是一种独立的身份验证机制。将 Base64 编码的 API key 放入 Authorization 请求头中。 这是程序化和自动化访问的首选方式。

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

创建密钥时返回的 ELASTICSEARCH_API_KEY 是 encoded 值（id:api_key 的 Base64 编码）。

验证身份验证

继续操作前，请始终验证凭据：

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

检查 username、roles 和 authentication_realm.type，以确认身份和身份验证方式：

authentication_realm.type	Realm
native	Native
file	File
ldap	LDAP
active_directory	Active Directory
pki	PKI
saml	SAML
oidc	OpenID Connect
jwt	JWT
kerberos	Kerberos

对于 API 密钥，authentication_type 为 "api_key"（而不是 realm 类型）。

管理 API 密钥

创建 API 密钥

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"]
          }
        ]
      }
    }
  }'

响应包含 id、api_key 和 encoded。请安全保存 encoded，之后无法再次获取。

省略 role_descriptors，即可继承已通过身份验证的用户当前权限的快照。

限制： API 密钥无法创建具有权限的其他 API 密钥。派生密钥创建后不具备任何 有效访问权限。请改用用户凭据调用 POST /_security/api_key/grant。

获取并使 API 密钥失效

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}"'"}'

示例

创建范围受限的 API 密钥

请求：“创建一个只能读取 metrics-* 的 API 密钥。”

POST /_security/api_key
{
  "name": "metrics-reader-key",
  "expiration": "90d",
  "role_descriptors": {
    "metrics-reader": {
      "indices": [
        {
          "names": ["metrics-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
  }
}

验证用户通过哪个 realm 完成身份验证

GET /_security/_authenticate

{
  "username": "joe",
  "authentication_realm": { "name": "ldap1", "type": "ldap" },
  "authentication_type": "realm"
}

使用 JWT bearer token 进行身份验证

curl -H "Authorization: Bearer ${JWT_TOKEN}" "https://my-cluster:9200/_security/_authenticate"

确认响应中的 authentication_realm.type 显示为 "jwt"。

指南

选择身份验证方式

方式	最适合的场景	权衡
Native 用户	交互式使用、简单配置	必须存储密码或提示用户输入
File 用户	灾难恢复、引导配置	必须在每个节点上配置
API 密钥	编程访问、CI/CD、范围受限的访问	创建后无法再次获取
LDAP / AD	企业目录集成	需要访问目录服务的网络
PKI 证书	服务间通信、双向 TLS 环境	需要 PKI 基础设施和 PKI realm
SAML	通过企业 IdP 实现 Kibana SSO	仅限浏览器；不适用于 REST 客户端
OIDC	通过 OpenID Connect 提供商实现 Kibana SSO	仅限浏览器；不适用于 REST 客户端
JWT	基于令牌的服务和用户身份验证	需要外部令牌签发方和 realm 配置
Kerberos	Windows/企业 Kerberos 环境	需要 KDC、DNS 和时间同步基础设施

自动化工作流优先使用 API 密钥，因为它支持精细的范围控制和独立的过期时间。对于 Kibana SSO，请使用 SAML 或 OIDC。对于企业目录集成，请使用 LDAP 或 AD，并配置角色映射（参见 elasticsearch-authz）。

避免使用超级用户凭据

切勿在日常操作、自动化或应用访问中使用内置的 elastic 超级用户或任何具有 superuser 角色的账户。请改为创建专用用户或 API 密钥，仅授予任务所需的权限。elastic 用户仅应保留用于初始集群设置和紧急恢复。

安全

• API 密钥不能创建具有权限的其他 API 密钥。以编程方式创建密钥时，请使用用户凭据或 POST /_security/api_key/grant。
• 始终为 API 密钥设置 expiration。生产环境中应避免使用永不过期的密钥。
• 通过 role_descriptors 限定 API 密钥的权限范围。绝不要为自动化系统创建未限定权限范围的密钥。
• 切勿在聊天中接收、复述或记录密码、API 密钥、令牌或任何凭据。应指导用户直接在终端、环境变量或文件中管理机密信息。
• 切勿将机密信息存储在代码、脚本或版本控制中。请从环境变量中加载。
• 执行管理操作前，使用 GET /_security/_authenticate 验证凭据。
• 为原生用户生成密码时，至少使用 16 个字符，并混合大小写字母、数字和符号。绝不要使用 changeme 或 password123 这类占位值。
• SAML 和 OIDC 仅用于基于浏览器的 SSO。除这些方式外，始终配置一个配套的领域（原生、文件或 API 密钥），以便通过 REST API 访问。

部署兼容性

并非所有部署类型都支持所有身份验证领域。自管理集群支持所有领域。Elastic Cloud Hosted (ECH) 由 Elastic 管理，无法访问节点。Serverless 是完全托管的 SaaS。

领域	自管理	ECH	Serverless
原生	是	是	不可用
文件	是	不可用	不可用
LDAP	是	不可用	不可用
Active Directory	是	不可用	不可用
PKI	是	有限	不可用
SAML	是	是（部署配置）	组织级别
OIDC	是	是（部署配置）	不可用
JWT	是	是（部署配置）	不可用
Kerberos	是	不可用	不可用
API 密钥	是	是	是

ECH 注意事项：

• 无法访问节点，因此文件领域和 elasticsearch-users CLI 不可用。
• 无法在 ECH 上配置 LDAP、Active Directory 和 Kerberos。
• 可通过 Cloud 部署设置界面配置 SAML、OIDC 和 JWT。
• elastic 超级用户可用，但日常使用仍应避免使用。

Serverless 注意事项：

• API 密钥是主要的身份验证方式。
• 不存在原生用户——用户在 Elastic Cloud 组织级别进行管理。
• SAML SSO 在组织级别配置，而非按项目配置。