elasticsearch-security-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Elasticsearch Security Troubleshooting

Elasticsearch 安全故障排查

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.

诊断并解决常见的Elasticsearch安全问题。本技能提供了一套结构化的分流排查流程，涵盖认证失败、授权错误、TLS问题、API密钥问题、角色映射不匹配、Kibana登录失败以及许可证过期锁定等场景。

关于认证方法和API密钥管理，请参考elasticsearch-authn技能。关于角色、用户和角色映射，请参考elasticsearch-authz技能。关于许可证管理，请参考elasticsearch-license技能。

关于诊断API端点，请查看references/api-reference.md。

部署说明： 诊断API的可用性在自托管、ECH和Serverless部署之间存在差异。详情请见部署兼容性。

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

诊断HTTP 401认证失败问题
诊断HTTP 403权限拒绝错误
排查TLS/SSL握手或证书错误
调查过期或无效的API密钥
调试未授予预期角色的角色映射
修复Kibana登录失败、重定向循环或CORS错误
从许可证过期锁定状态恢复
确定用户无法访问特定索引的原因

Prerequisites

前提条件

Item	Description
Elasticsearch URL	Cluster endpoint (e.g. `https://localhost:9200` or a Cloud deployment URL)
Authentication	Any valid credentials — even minimal — to reach the cluster
Cluster privileges	`monitor` for read-only diagnostics; `manage_security` for fixes

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

项	描述
Elasticsearch URL	集群端点（例如 `https://localhost:9200` 或云部署URL）
Authentication	任何有效的凭据——即使是最低权限的，只要能连接到集群即可
Cluster privileges	`monitor` 权限用于只读诊断； `manage_security` 权限用于执行修复操作

如果用户缺少任何必要信息，请提示其提供。如果用户完全无法认证，请从TLS和证书错误或许可证过期恢复开始排查。

Diagnostic Workflow

诊断流程

Route the symptom to the correct section:

Symptom	Section
HTTP 401, `authentication_exception`	Authentication Failures
HTTP 403, `security_exception` , access denied	Authorization Failures
SSL/TLS handshake error, certificate rejected	TLS and Certificate Errors
API key rejected, expired, or ineffective	API Key Issues
Role mapping not granting expected roles	Role Mapping Issues
Kibana login broken, redirect loop, CORS error	Kibana Authentication Issues
All users locked out, paid features disabled	License Expiry Recovery

Each section follows a Gather - Diagnose - Resolve pattern.

根据症状定位到对应的章节：

症状	对应章节
HTTP 401, `authentication_exception`	认证失败（401）
HTTP 403, `security_exception` , 访问被拒绝	授权失败（403）
SSL/TLS握手错误、证书被拒绝	TLS和证书错误
API密钥被拒绝、过期或无效	API密钥问题
角色映射未授予预期角色	角色映射问题
Kibana登录失败、重定向循环、CORS错误	Kibana认证问题
所有用户被锁定、付费功能禁用	许可证过期恢复

每个章节都遵循收集信息 - 诊断问题 - 解决问题的模式。

Diagnostic Toolkit

诊断工具集

Use these APIs at the start of any security investigation:

bash

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

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

bash

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

Confirms whether security is enabled (

features.security.enabled

). If security is disabled, all security APIs return errors.

bash

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

bash

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

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

在任何安全问题排查开始时，都可以使用以下API：

bash

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

确认身份、域和角色。如果请求返回401，则问题出在认证环节。

bash

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

确认安全功能是否已启用（

features.security.enabled

）。如果安全功能已禁用，所有安全API都会返回错误。

bash

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

测试已认证用户是否拥有特定权限，无需

manage_security

权限。

bash

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

检查许可证类型和状态。过期的付费许可证会禁用付费域和功能。

Authentication Failures (401)

认证失败（401）

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

401响应意味着Elasticsearch无法验证调用者的身份。

Gather

收集信息

bash

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.

bash

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

-v

标志会显示请求头和响应体。重点关注：

```
WWW-Authenticate
```
请求头——指示集群接受的认证方案。
响应体中的
```
authentication_exception
```
——
```
reason
```
字段描述了失败原因。

Diagnose

诊断

Symptom	Likely cause
`unable to authenticate user`	Wrong username or password
`unable to authenticate with provided credentials`	Credentials do not match any realm in the chain
`user is not enabled`	The native user account is disabled
`token is expired`	API key or bearer token has expired
No `WWW-Authenticate` header	Security may be disabled; check `GET /_xpack`

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.

症状	可能原因
`unable to authenticate user`	用户名或密码错误
`unable to authenticate with provided credentials`	凭据与认证链中的任何域都不匹配
`user is not enabled`	本地用户账户已被禁用
`token is expired`	API密钥或Bearer令牌已过期
无 `WWW-Authenticate` 请求头	安全功能可能已禁用；请检查 `GET /_xpack`

如果用户通过外部域（LDAP、AD、SAML、OIDC）认证，域链的顺序很重要。Elasticsearch会按照配置的顺序尝试域，找到第一个匹配的域后就会停止。如果优先级较高的域在预期域之前拒绝了凭据，认证就会失败。

Resolve

解决方法

Cause	Action
Wrong credentials	Verify username/password or API key value. See elasticsearch-authn.
Disabled user	`PUT /_security/user/{name}/_enable` . See elasticsearch-authz.
Expired API key	Create a new API key. See API Key Issues.
Realm chain order	Check `elasticsearch.yml` realm order (self-managed only).
Security disabled	Enable `xpack.security.enabled: true` in `elasticsearch.yml` and restart.
Paid realm after expiry	License expired — see License Expiry Recovery.

原因	操作
凭据错误	验证用户名/密码或API密钥的值。请参考elasticsearch-authn。
用户被禁用	执行 `PUT /_security/user/{name}/_enable` 。请参考elasticsearch-authz。
API密钥过期	创建新的API密钥。请查看API密钥问题。
域链顺序问题	检查 `elasticsearch.yml` 中的域顺序（仅适用于自托管部署）。
安全功能已禁用	在 `elasticsearch.yml` 中设置 `xpack.security.enabled: true` 并重启集群。
付费域在许可证过期后不可用	许可证已过期——请查看许可证过期恢复。

Authorization Failures (403)

授权失败（403）

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

403响应意味着用户已通过认证，但缺少所需的权限。

Gather

收集信息

Test the specific privileges the operation requires:

bash

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:

bash

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

Inspect the

roles

array and

authentication_realm

to confirm the user is who you expect.

测试操作所需的特定权限：

bash

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

响应包含一个

has_all_requested

布尔值和按资源细分的权限检查结果。

同时检查用户的有效角色：

bash

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

查看

roles

数组和

authentication_realm

，确认用户身份符合预期。

Diagnose

诊断

Symptom	Likely cause
`has_all_requested: false` for an index	Role is missing the required index privilege
`has_all_requested: false` for a cluster	Role is missing the required cluster privilege
User has fewer roles than expected	Roles array was replaced (not merged) on last update
API key returns 403 on previously allowed	API key privileges are a snapshot — role changes after
operation	creation do not propagate to existing keys

症状	可能原因
针对索引的 `has_all_requested: false`	角色缺少所需的索引权限
针对集群的 `has_all_requested: false`	角色缺少所需的集群权限
用户拥有的角色少于预期	上次更新时角色数组被替换（而非合并）
API密钥在之前允许的操作上返回403	API密钥的权限是快照式的——创建密钥后角色的变更不会同步到现有密钥

Resolve

解决方法

Cause	Action
Missing index privilege	Add the privilege to the role or create a new role. See elasticsearch-authz.
Missing cluster privilege	Add the cluster privilege. See elasticsearch-authz.
Roles replaced on update	Fetch current roles first, then update with the full array. See elasticsearch-authz.
Stale API key privileges	Create a new API key with updated `role_descriptors` . See elasticsearch-authn.

原因	操作
缺少索引权限	为角色添加所需权限或创建新角色。请参考elasticsearch-authz。
缺少集群权限	为角色添加集群权限。请参考elasticsearch-authz。
更新时角色被替换	先获取当前角色，然后使用完整数组进行更新。请参考elasticsearch-authz。
API密钥权限过时	使用更新后的 `role_descriptors` 创建新的API密钥。请参考elasticsearch-authn。

TLS and Certificate Errors

TLS和证书错误

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

TLS错误会阻止客户端建立连接。

Gather

收集信息

bash

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):

bash

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

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

bash

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

重点关注：

SSL certificate problem: unable to get local issuer certificate

——CA证书不被信任。

SSL certificate problem: certificate has expired

——证书已过有效期。

SSL: no alternative certificate subject name matches target host name

——主机名不匹配。

如需更深入的检查（仅适用于自托管部署）：

bash

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

该命令会显示完整的证书链、过期日期和主题备用名称。

Diagnose

诊断

Error message	Likely cause
`unable to get local issuer certificate`	Missing or wrong CA certificate
`certificate has expired`	Server or CA certificate past expiry
`no alternative certificate subject name matches`	Certificate SAN does not include the hostname
`self-signed certificate`	Self-signed cert not in the trust store
`SSLHandshakeException` (Java client)	Truststore missing the CA or wrong password

错误信息	可能原因
`unable to get local issuer certificate`	缺少或使用了错误的CA证书
`certificate has expired`	服务器或CA证书已过期
`no alternative certificate subject name matches`	证书的SAN不包含目标主机名
`self-signed certificate`	自签名证书不在信任存储中
`SSLHandshakeException` (Java客户端)	信任存储中缺少CA证书或密码错误

Resolve

解决方法

Cause	Action
Wrong CA cert	Pass the correct CA with `--cacert` or add it to the system trust store.
Expired certificate	Regenerate certificates with `elasticsearch-certutil` (self-managed).
Hostname mismatch	Regenerate the certificate with the correct SAN entries.
Self-signed cert	Distribute the CA cert to all clients or use a publicly trusted CA.
Quick workaround	Use `curl -k` / `--insecure` to skip verification. Not for production.

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.

原因	操作
CA证书错误	使用 `--cacert` 参数指定正确的CA证书，或将其添加到系统信任存储中。
证书过期	使用 `elasticsearch-certutil` 重新生成证书（仅适用于自托管部署）。
主机名不匹配	重新生成包含正确SAN条目的证书。
自签名证书	将CA证书分发给所有客户端，或使用公共可信CA。
临时解决方法	使用 `curl -k` / `--insecure` 跳过证书验证。请勿在生产环境中使用。

在ECH部署中，TLS由Elastic管理——证书错误通常表示客户端使用了错误的云端点URL。在Serverless部署中，TLS完全由Elastic管理，对用户透明。

API Key Issues

API密钥问题

Gather

收集信息

Retrieve the key's metadata:

bash

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

Check

expiration

invalidated

, and

role_descriptors

in the response.

获取密钥的元数据：

bash

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

检查响应中的

expiration

、

invalidated

和

role_descriptors

字段。

Diagnose

诊断

Symptom	Likely cause
401 when using the key	Key expired or invalidated
403 on operations that should be allowed	Key was created with insufficient `role_descriptors`
Derived key has no access	API key created another API key — derived keys have no privilege
Key works for some indices but not others	`role_descriptors` scope is too narrow

症状	可能原因
使用密钥时返回401	密钥已过期或被吊销
本应允许的操作返回403	创建密钥时 `role_descriptors` 权限不足
派生密钥无访问权限	API密钥创建了另一个API密钥——派生密钥没有任何权限
密钥对部分索引有效但对其他索引无效	`role_descriptors` 的作用域太窄

Resolve

解决方法

Cause	Action
Expired key	Create a new key with appropriate `expiration` . See elasticsearch-authn.
Invalidated key	Create a new key. Invalidated keys cannot be reinstated.
Wrong scope	Create a new key with correct `role_descriptors` . See elasticsearch-authn.
Derived key problem	Use `POST /_security/api_key/grant` with user credentials instead. See elasticsearch-authn.

原因	操作
密钥过期	创建带有合适 `expiration` 的新密钥。请参考elasticsearch-authn。
密钥被吊销	创建新密钥。被吊销的密钥无法恢复。
作用域错误	使用正确的 `role_descriptors` 创建新密钥。请参考elasticsearch-authn。
派生密钥问题	使用用户凭据执行 `POST /_security/api_key/grant` 来创建密钥。请参考elasticsearch-authn。

Role Mapping Issues

角色映射问题

Role mappings grant roles to users from external realms. When they fail silently, users authenticate but get no roles.

角色映射用于为来自外部域的用户授予角色。当映射静默失败时，用户可以通过认证，但无法获得任何角色。

Gather

收集信息

bash

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

Note the

username

authentication_realm.name

, and

roles

array.

bash

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

List all mappings and inspect their

rules

and

enabled

fields.

bash

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

记录

username

、

authentication_realm.name

和

roles

数组。

bash

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

列出所有映射并检查它们的

rules

和

enabled

字段。

Diagnose

诊断

Symptom	Likely cause
User has empty `roles` array	No mapping matches the user's attributes
User gets wrong roles	A different mapping matched first or the rule is too broad
Mapping exists but does not apply	`enabled` is `false`
Mustache template produces wrong role name	Template syntax error or unexpected attribute value

Compare the user's

authentication_realm.name

and

groups

(from

_authenticate

) against each mapping's

rules

to find the mismatch.

症状	可能原因
用户的 `roles` 数组为空	没有映射匹配用户的属性
用户获得错误的角色	其他映射先匹配成功，或规则范围太广
映射存在但不生效	`enabled` 设置为 `false`
Mustache模板生成错误的角色名称	模板语法错误或属性值不符合预期

将用户的

authentication_realm.name

和

groups

（来自

_authenticate

响应）与每个映射的

rules

进行比较，找出不匹配的地方。

Resolve

解决方法

Cause	Action
No matching rule	Update the mapping rules to match the user's realm and attributes.
Mapping disabled	Set `"enabled": true` on the mapping.
Template error	Test the Mustache template with known attribute values. See elasticsearch-authz.
Rule too broad	Add `all` / `except` conditions to narrow the match. See elasticsearch-authz.

原因	操作
无匹配规则	更新映射规则以匹配用户的域和属性。
映射被禁用	将映射的 `"enabled": true` 设置为 `true` 。
模板错误	使用已知的属性值测试Mustache模板。请参考elasticsearch-authz。
规则范围太广	添加 `all` / `except` 条件来缩小匹配范围。请参考elasticsearch-authz。

Kibana Authentication Issues

Kibana认证问题

Missing

kbn-xsrf

header

缺少

kbn-xsrf

请求头

All mutating Kibana API requests require the

kbn-xsrf

header:

bash

curl -X PUT "${KIBANA_URL}/api/security/role/my-role" \
  <auth_flags> \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Without it, Kibana returns

400 Bad Request

with

"Request must contain a kbn-xsrf header"

所有修改类的Kibana API请求都需要

kbn-xsrf

请求头：

bash

curl -X PUT "${KIBANA_URL}/api/security/role/my-role" \
  <auth_flags> \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

如果缺少该请求头，Kibana会返回

400 Bad Request

，并提示

"Request must contain a kbn-xsrf header"

。

SAML/OIDC redirect loop

SAML/OIDC重定向循环

Common causes:

Incorrect

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

idp.metadata.path

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.

Verify the SAML realm configuration:

bash

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

If this returns a valid user via a non-SAML realm, the SAML realm itself is not being reached. Check realm chain order.

常见原因：

elasticsearch.yml

中的

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

或

idp.metadata.path

配置错误。

IdP与Elasticsearch节点之间的时钟不同步（SAML断言有有效期窗口）。
Kibana的
```
server.publicBaseUrl
```
与SAML ACS URL不匹配。

验证SAML域配置：

bash

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

如果请求通过非SAML域返回有效用户，则说明SAML域本身未被访问到。请检查域链顺序。

Kibana cannot reach Elasticsearch

Kibana无法连接到Elasticsearch

Kibana logs

Unable to retrieve version information from Elasticsearch nodes

. Verify the

elasticsearch.hosts

setting in

kibana.yml

points to a reachable endpoint and the credentials (

elasticsearch.username

elasticsearch.password

elasticsearch.serviceAccountToken

) are valid.

Kibana日志中显示

Unable to retrieve version information from Elasticsearch nodes

。请验证

kibana.yml

中的

elasticsearch.hosts

设置指向可访问的端点，且凭据（

elasticsearch.username

elasticsearch.password

或

elasticsearch.serviceAccountToken

）有效。

License Expiry Recovery

许可证过期恢复

When a paid license expires, the cluster enters a security-closed state: paid realms (SAML, LDAP, AD, PKI) stop working and users authenticating through them are locked out. Native and file realms remain functional.

当付费许可证过期时，集群会进入安全关闭状态：付费域（SAML、LDAP、AD、PKI）停止工作，通过这些域认证的用户会被锁定。本地域和文件域仍然可用。

Quick triage

快速排查

bash

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

license.status

"expired"

, proceed with recovery.

bash

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

如果

license.status

为

"expired"

，则按照恢复步骤操作。

Recovery steps

恢复步骤

Follow the detailed recovery workflow in the elasticsearch-license skill. The critical first step depends on deployment type:

Deployment	First step
Self-managed	Log in with a file-based user ( `elasticsearch-users` CLI) or native user.
ECH	Contact Elastic support or renew via the Cloud console.
Serverless	Not applicable — licensing is fully managed by Elastic.

请遵循elasticsearch-license技能中的详细恢复流程。关键的第一步取决于部署类型：

部署类型	第一步
自托管	使用文件用户（ `elasticsearch-users` CLI）或本地用户登录。
ECH	联系Elastic支持或通过云控制台续订许可证。
Serverless	不适用——许可证完全由Elastic管理。

Examples

示例

User gets 403 when querying logs

用户查询日志时返回403

Symptom: "I get a 403 when searching

logs-*

Verify identity:

bash

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

Response shows

"roles": ["viewer"]

Test privileges:

bash

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

Response:

"has_all_requested": false

— the

viewer

role does not include

read

logs-*

Fix: create a
```
logs-reader
```
role and assign it to Joe. See elasticsearch-authz.

症状： "我搜索

logs-*

时收到403错误。"

验证身份：

bash

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

响应显示

"roles": ["viewer"]

。

测试权限：

bash

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

角色不包含对

logs-*

的

read

权限。

解决方法：创建
```
logs-reader
```
角色并将其分配给Joe。请参考elasticsearch-authz。

API key stopped working

API密钥突然失效

Symptom: "My API key returns 401 since yesterday."

Check the key:

bash

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

Response shows

"expiration": 1709251200000

— the key expired.

Fix: create a new API key with a suitable
```
expiration
```
. See elasticsearch-authn.

症状： "我的API密钥从昨天开始返回401错误。"

检查密钥：

bash

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

响应显示

"expiration": 1709251200000

——密钥已过期。

解决方法：创建带有合适
```
expiration
```
的新API密钥。请参考elasticsearch-authn。

SAML login redirects to error

SAML登录重定向到错误页面

Symptom: "Clicking the SSO button in Kibana redirects to an error page."

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

bash

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

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

bash

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

Check for clock skew — SAML assertions are time-sensitive. Ensure NTP is configured on all nodes.
Verify
```
server.publicBaseUrl
```
in
```
kibana.yml
```
matches the SAML ACS URL configured in the IdP.

症状： "点击Kibana中的SSO按钮后重定向到错误页面。"

通过非SAML方法认证，检查SAML域是否可访问：

bash

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

验证IdP元数据URL是否可从Elasticsearch节点访问（自托管部署）：

bash

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

检查时钟同步——SAML断言对时间敏感。确保所有节点都配置了NTP。
验证
```
kibana.yml
```
中的
```
server.publicBaseUrl
```
与IdP中配置的SAML ACS URL是否匹配。

Users locked out after license expired

许可证过期后所有用户被锁定

Symptom: "Nobody can log in to Kibana. We use SAML."

Check license:

bash

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

Response shows

"status": "expired"

"type": "platinum"

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.

症状： "没有人能登录到Kibana。我们使用SAML认证。"

检查许可证：

bash

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

响应显示

"status": "expired"

"type": "platinum"

。

由于付费许可证过期，SAML域已被禁用。请遵循elasticsearch-license中的恢复步骤：使用文件用户或本地用户登录，然后上传续订的许可证或降级到基础许可证。

Guidelines

指导原则

Always start with

_authenticate

始终从

_authenticate

开始

Run

GET /_security/_authenticate

as the first diagnostic step. It reveals the user's identity, realm, roles, and authentication type in a single call. Most issues become apparent from this response alone.

将

GET /_security/_authenticate

作为第一个诊断步骤。它可以在一次调用中揭示用户的身份、域、角色和认证类型。大多数问题从这个响应中就能显现出来。

Check the license early

尽早检查许可证

Before investigating realm or privilege issues, verify the license is active with

GET /_license

. An expired paid license disables realms and features, producing symptoms that mimic misconfiguration.

在排查域或权限问题之前，先使用

GET /_license

验证许可证是否有效。过期的付费许可证会禁用域和功能，产生的症状与配置错误类似。

Use

_has_privileges

before manual inspection

先使用

_has_privileges

再手动检查

Instead of reading role definitions and mentally computing effective access, use

POST /_security/user/_has_privileges

to test specific privileges directly. This is faster and accounts for role composition, DLS, and FLS.

不要通过阅读角色定义来手动计算有效权限，而是使用

POST /_security/user/_has_privileges

直接测试特定权限。这种方法更快，而且能考虑到角色组合、DLS和FLS的影响。

Avoid superuser credentials

避免使用超级用户凭据

Never use the built-in

elastic

superuser for day-to-day troubleshooting. Create a dedicated admin user or API key with

manage_security

privileges. Reserve the

elastic

user for initial setup and emergency recovery only.

日常排查时绝不要使用内置的

elastic

超级用户。创建一个专用的管理员用户或带有

manage_security

权限的API密钥。仅在初始设置和紧急恢复时使用

elastic

用户。

Do not bypass TLS in production

生产环境中不要绕过TLS

Using

curl -k

--insecure

skips certificate verification and masks real TLS issues. Use it only for initial diagnosis, then fix the underlying certificate problem.

使用

curl -k

或

--insecure

会跳过证书验证，掩盖真实的TLS问题。仅在初始诊断时使用，然后修复底层的证书问题。

Deployment Compatibility

部署兼容性

Diagnostic tool and API availability differs across deployment types.

Tool / API	Self-managed	ECH	Serverless
`_security/_authenticate`	Yes	Yes	Yes
`_security/user/_has_privileges`	Yes	Yes	Yes
`_xpack`	Yes	Yes	Limited
`_license`	Yes	Yes (read)	Not available
`_security/api_key` (GET)	Yes	Yes	Yes
`_security/role_mapping`	Yes	Yes	Yes
`elasticsearch-users` CLI	Yes	Not available	Not available
`openssl s_client` on nodes	Yes	Not available	Not available
Elasticsearch logs	Yes	Via Cloud UI	Via Cloud UI

ECH notes:

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.

Serverless notes:

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.

诊断工具和API的可用性因部署类型而异。

工具/API	自托管	ECH	Serverless
`_security/_authenticate`	是	是	是
`_security/user/_has_privileges`	是	是	是
`_xpack`	是	是	受限
`_license`	是	是（只读）	不可用
`_security/api_key` (GET)	是	是	是
`_security/role_mapping`	是	是	是
`elasticsearch-users` CLI	是	不可用	不可用
节点上的 `openssl s_client`	是	不可用	不可用
Elasticsearch日志	是	通过云UI查看	通过云UI查看

ECH说明：

无节点级访问权限，因此无法使用
```
elasticsearch-users
```
CLI和直接查看日志/证书。
TLS由Elastic管理——证书错误通常表示使用了错误的端点URL。
使用云控制台查看日志和配置部署。

Serverless说明：

不暴露许可证API。不会发生与许可证相关的锁定。
不存在本地用户——认证问题在组织级别处理。
TLS完全由Elastic管理，对用户透明。

elasticsearch-security-troubleshooting

Original

Translation

Elasticsearch Security Troubleshooting

Elasticsearch 安全故障排查

Jobs to Be Done

需完成的任务

Prerequisites

前提条件

Diagnostic Workflow

诊断流程

Diagnostic Toolkit

诊断工具集

Authentication Failures (401)

认证失败（401）

Gather

收集信息

Diagnose

诊断

Resolve

解决方法

Authorization Failures (403)

授权失败（403）

Gather

收集信息

Diagnose

诊断

Resolve

解决方法

TLS and Certificate Errors

TLS和证书错误

Gather

收集信息

Diagnose

诊断

Resolve

解决方法

API Key Issues

API密钥问题

Gather

收集信息

Diagnose

诊断

Resolve

解决方法

Role Mapping Issues

角色映射问题

Gather

收集信息

Diagnose

诊断

Resolve

解决方法

Kibana Authentication Issues

Kibana认证问题

Missing kbn-xsrf header

缺少kbn-xsrf请求头

SAML/OIDC redirect loop

SAML/OIDC重定向循环

Kibana cannot reach Elasticsearch

Kibana无法连接到Elasticsearch

License Expiry Recovery

许可证过期恢复

Quick triage

快速排查

Recovery steps

恢复步骤

Examples

示例

User gets 403 when querying logs

用户查询日志时返回403

API key stopped working

API密钥突然失效

SAML login redirects to error

SAML登录重定向到错误页面

Users locked out after license expired

许可证过期后所有用户被锁定

Guidelines

指导原则

Always start with _authenticate

Missing
`kbn-xsrf`
header

缺少
`kbn-xsrf`
请求头

Always start with
`_authenticate`

始终从
`_authenticate`
开始

Use
`_has_privileges`
before manual inspection

先使用
`_has_privileges`
再手动检查