Back to Details

elasticsearch-authz

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Elasticsearch Authorization

Elasticsearch 授权管理

Manage Elasticsearch role-based access control: native users, roles, role assignment, and role mappings for external realms.
For authentication methods and API key management, see the elasticsearch-authn skill.
For detailed API endpoints, see references/api-reference.md.
Deployment note: Feature availability differs between self-managed, ECH, and Serverless. See Deployment Compatibility for details.
管理Elasticsearch基于角色的访问控制（RBAC）：原生用户、角色、角色分配，以及针对外部领域的角色映射。
关于认证方法和API密钥管理，请查看 elasticsearch-authn 技能文档。
如需详细API端点信息，请参阅 references/api-reference.md。
部署说明：功能可用性在自托管、ECH和Serverless部署之间存在差异。详情请查看 部署兼容性。

Jobs to Be Done

可执行任务

  • Create a native user with a specific set of privileges
  • Define a custom role with least-privilege index and cluster access
  • Assign one or more roles to an existing user
  • Create a role with Kibana feature or space privileges
  • Configure a role mapping for external realm users (SAML, LDAP, PKI)
  • Derive role assignments dynamically from user attributes (Mustache templates)
  • Restrict document visibility per user or department (document-level security)
  • Hide sensitive fields like PII from certain roles (field-level security)
  • Implement attribute-based access control (ABAC) using templated role queries
  • Translate a natural-language access request into user, role, and role mapping tasks
  • 创建具备特定权限集的原生用户
  • 定义遵循最小权限原则的自定义角色，包含索引和集群访问权限
  • 为现有用户分配一个或多个角色
  • 创建包含Kibana功能或空间权限的角色
  • 为外部领域用户（SAML、LDAP、PKI）配置角色映射
  • 通过Mustache模板从用户属性动态推导角色分配
  • 按用户或部门限制文档可见性（文档级安全）
  • 对特定角色隐藏PII等敏感字段（字段级安全）
  • 使用模板化角色查询实现基于属性的访问控制（ABAC）
  • 将自然语言描述的访问需求转化为用户、角色和角色映射任务

Prerequisites

前置条件

ItemDescription
Elasticsearch URLCluster endpoint (e.g. 
https://localhost:9200
or a Cloud deployment URL)
Kibana URLRequired only when setting Kibana feature/space privileges
AuthenticationValid credentials (see the elasticsearch-authn skill)
Cluster privileges
manage_security
is required for user and role management operations
Prompt the user for any missing values.
项描述
Elasticsearch URL集群端点（例如 
https://localhost:9200
或云部署URL）
Kibana URL仅在设置Kibana功能/空间权限时需要
Authentication有效凭据（请查看elasticsearch-authn技能文档）
Cluster privileges用户和角色管理操作需要 
manage_security
权限
若有缺失项，请提示用户补充。

Decomposing Access Requests

拆解访问请求

When the user describes access in natural language (e.g. "create a user that has read-only access to 
logs-*
"), break the request into discrete tasks before executing. Follow this workflow:
当用户用自然语言描述访问需求时（例如“创建一个对
logs-*
具备只读访问权限的用户”），请先将请求拆解为独立任务再执行。遵循以下流程：

Step 1 — Identify the components

步骤1 — 识别核心组件

Extract from the prompt:
ComponentQuestion to answer
WhoNew native user, existing user, or external realm user (LDAP, SAML, etc.)
WhatWhich indices, data streams, or Kibana features
Access levelRead, write, manage, or a specific set of privileges
ScopeAll documents/fields, or restricted by region, department, sensitivity?
Kibana?Does the request mention any Kibana feature (dashboards, Discover, etc.)
Deployment?Self-managed, ECH, or Serverless? Serverless has a different user model.
从请求中提取以下信息：
组件需明确的问题
Who新原生用户、现有用户，还是外部领域用户（LDAP、SAML等）
What涉及哪些索引、数据流或Kibana功能
Access level只读、写入、管理，还是特定权限集
Scope所有文档/字段，还是按区域、部门、敏感度限制？
Kibana?请求中是否提及Kibana功能（如仪表盘、Discover等）
Deployment?自托管、ECH还是Serverless？Serverless采用不同的用户模型。

Step 2 — Check for existing roles

步骤2 — 检查现有角色

Before creating a new role, check if an existing role already grants the required access:
bash
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
If a matching role exists, skip role creation and reuse it.
创建新角色前，请检查是否已有角色满足所需权限：
bash
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
若存在匹配角色，请跳过角色创建直接复用。

Step 3 — Create the role (if needed)

步骤3 — 创建角色（如需要）

Derive a role name and display name from the request. Use the Elasticsearch API for pure index/cluster roles. Use the Kibana API if Kibana features are involved (see Choosing the right API).
从请求中推导角色名称和显示名称。纯索引/集群角色使用Elasticsearch API。若涉及Kibana功能，请使用Kibana API（请查看选择合适的API）。

Step 4 — Create or update the user

步骤4 — 创建或更新用户

ScenarioAction
New native userCreate the user with the role and a strong generated password. (Self-managed / ECH only.)
Existing native userFetch current roles, append the new role, update the user with the full array. (Self-managed / ECH only.)
External realm userCreate a role mapping that matches the user's realm attributes to the role. (Self-managed / ECH only.)
Serverless userUse the cloud-access-management skill. Assign a predefined role or create a custom role first, then assign it via the Cloud API.
场景操作
新原生用户创建用户并分配角色，同时生成强密码。（仅适用于自托管/ECH部署。）
现有原生用户获取当前角色列表，追加新角色后，用完整角色数组更新用户。（仅适用于自托管/ECH部署。）
外部领域用户创建角色映射，将用户的领域属性与角色关联。（仅适用于自托管/ECH部署。）
Serverless用户使用 cloud-access-management 技能。先分配预定义角色或创建自定义角色，再通过Cloud API为用户分配。

Example decomposition

拆解示例

Prompt: "Create a user 
analyst
with read-only access to 
logs-*
and 
metrics-*
and view dashboards in Kibana."
  1. Identify: new user 
    analyst
    , indices 
    logs-*
    /
    metrics-*
    , dashboards, read access.
  2. Check roles: 
    GET /_security/role
    — no match.
  3. Create role via Kibana API (dashboards involved): 
    logs-metrics-dashboard-viewer
    .
  4. Create user: 
    POST /_security/user/analyst
    with 
    roles: ["logs-metrics-dashboard-viewer"]
    .
Confirm each step with the user if the request is ambiguous.
请求：“创建用户
analyst
，使其对
logs-*
和
metrics-*
具备只读访问权限，并可查看Kibana中的仪表盘。”
  1. 识别：新用户
    analyst
    ，索引
    logs-*
    /
    metrics-*
    ，仪表盘，只读权限。
  2. 检查角色：执行
    GET /_security/role
    — 无匹配角色。
  3. 通过Kibana API创建角色：
    logs-metrics-dashboard-viewer
    。
  4. 创建用户：执行
    POST /_security/user/analyst
    ，设置
    roles: ["logs-metrics-dashboard-viewer"]
    。
若请求存在歧义，请与用户确认每一步操作。

Manage Native Users

管理原生用户

Native user management applies to self-managed and ECH deployments. On Serverless, users are managed at the organization level — skip this section.
原生用户管理仅适用于自托管和ECH部署。在Serverless部署中，用户在组织级别管理 — 请跳过本节。

Create a user

创建用户

bash
curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "password": "'"${PASSWORD}"'",
    "roles": ["'"${ROLE_NAME}"'"],
    "full_name": "'"${FULL_NAME}"'",
    "email": "'"${EMAIL}"'",
    "enabled": true
  }'
bash
curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "password": "'"${PASSWORD}"'",
    "roles": ["'"${ROLE_NAME}"'"],
    "full_name": "'"${FULL_NAME}"'",
    "email": "'"${EMAIL}"'",
    "enabled": true
  }'

Update a user

更新用户

Use 
PUT /_security/user/${USERNAME}
with the fields to change. Omit 
password
to keep the existing one.
使用
PUT /_security/user/${USERNAME}
接口，传入需要修改的字段。若无需修改密码，请省略
password
字段。

Other user operations

其他用户操作

bash
curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_password" \
  <auth_flags> -H "Content-Type: application/json" \
  -d '{"password": "'"${NEW_PASSWORD}"'"}'
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_disable" <auth_flags>
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_enable" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>
bash
curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_password" \
  <auth_flags> -H "Content-Type: application/json" \
  -d '{"password": "'"${NEW_PASSWORD}"'"}'
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_disable" <auth_flags>
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_enable" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>

Manage Roles

管理角色

Choosing the right API

选择合适的API

Use the Elasticsearch API (
PUT /_security/role/{name}
) when the role only needs 
cluster
and 
indices
privileges. This is the default — no Kibana endpoint is required.
Use the Kibana role API (
PUT /api/security/role/{name}
) when the role includes any Kibana feature or space privileges. The Elasticsearch API cannot set Kibana feature grants, space scoping, or base privileges, so if the user mentions Kibana features like Discover, Dashboards, Maps, Visualize, Canvas, or any other Kibana application, the Kibana API is required.
If the Kibana endpoint is not available or API key authentication to Kibana fails, fall back to the Elasticsearch API for the 
cluster
and 
indices
portion and warn the user that Kibana privileges could not be set. Prompt for a Kibana URL or alternative credentials before giving up.
当角色仅需
cluster
和
indices
权限时，使用 Elasticsearch API (
PUT /_security/role/{name}
)。这是默认方式 — 无需Kibana端点。
当角色包含Kibana功能或空间权限时，使用 Kibana角色API (
PUT /api/security/role/{name}
)。Elasticsearch API无法设置Kibana功能权限、空间范围或基础权限，因此若用户提及Discover、Dashboards、Maps等Kibana应用，必须使用Kibana API。
若Kibana端点不可用或API密钥认证失败，可回退使用Elasticsearch API配置
cluster
和
indices
权限，并提醒用户无法设置Kibana权限。在放弃前，请提示用户提供Kibana URL或替代凭据。

Create or update a role (Elasticsearch API)

创建或更新角色（Elasticsearch API）

Default choice when the role has only index and cluster privileges:
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "cluster": [],
    "indices": [
      {
        "names": ["'"${INDEX_PATTERN}"'"],
        "privileges": ["read", "view_index_metadata"]
      }
    ]
  }'
当角色仅包含索引和集群权限时的默认选择：
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "cluster": [],
    "indices": [
      {
        "names": ["'"${INDEX_PATTERN}"'"],
        "privileges": ["read", "view_index_metadata"]
      }
    ]
  }'

Create or update a role (Kibana API)

创建或更新角色（Kibana API）

Required when the role includes Kibana feature or space privileges:
bash
curl -X PUT "${KIBANA_URL}/api/security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "elasticsearch": {
      "cluster": [],
      "indices": [
        {
          "names": ["'"${INDEX_PATTERN}"'"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    },
    "kibana": [
      {
        "base": [],
        "feature": {
          "discover": ["read"],
          "dashboard": ["read"]
        },
        "spaces": ["*"]
      }
    ]
  }'
当角色包含Kibana功能或空间权限时必须使用：
bash
curl -X PUT "${KIBANA_URL}/api/security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "elasticsearch": {
      "cluster": [],
      "indices": [
        {
          "names": ["'"${INDEX_PATTERN}"'"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    },
    "kibana": [
      {
        "base": [],
        "feature": {
          "discover": ["read"],
          "dashboard": ["read"]
        },
        "spaces": ["*"]
      }
    ]
  }'

Get, list, and delete roles

获取、列出和删除角色

bash
curl "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" <auth_flags>
bash
curl "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" <auth_flags>

Document-Level and Field-Level Security

文档级与字段级安全

Roles can restrict access at the document and field level within an index, going beyond index-level privileges.
角色可在索引内进一步限制文档和字段的访问权限，超越索引级权限的管控范围。

Field-level security (FLS)

字段级安全（FLS）

Restrict which fields a role can see. Use 
grant
to whitelist or 
except
to blacklist fields:
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/pii-redacted-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "PII Redacted Reader",
    "indices": [
      {
        "names": ["customers-*"],
        "privileges": ["read"],
        "field_security": {
          "grant": ["*"],
          "except": ["ssn", "credit_card", "date_of_birth"]
        }
      }
    ]
  }'
Users with this role see all fields except the PII fields. FLS is enforced on search, get, and aggregation results.
限制角色可查看的字段。使用
grant
白名单字段，或
except
黑名单字段：
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/pii-redacted-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "PII Redacted Reader",
    "indices": [
      {
        "names": ["customers-*"],
        "privileges": ["read"],
        "field_security": {
          "grant": ["*"],
          "except": ["ssn", "credit_card", "date_of_birth"]
        }
      }
    ]
  }'
拥有该角色的用户可查看除PII字段外的所有字段。FLS会在搜索、获取和聚合结果时生效。

Document-level security (DLS)

文档级安全（DLS）

Restrict which documents a role can see by attaching a query filter:
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/emea-logs-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "EMEA Logs Reader",
    "indices": [
      {
        "names": ["logs-*"],
        "privileges": ["read"],
        "query": "{\"term\": {\"region\": \"emea\"}}"
      }
    ]
  }'
The 
query
field is a JSON string containing a Query DSL filter. Users with this role only see documents where 
region
equals 
emea
.
通过附加查询过滤器限制角色可查看的文档：
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/emea-logs-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "EMEA Logs Reader",
    "indices": [
      {
        "names": ["logs-*"],
        "privileges": ["read"],
        "query": "{\"term\": {\"region\": \"emea\"}}"
      }
    ]
  }'
query
字段是包含Query DSL过滤器的JSON字符串。拥有该角色的用户仅能查看
region
等于
emea
的文档。

Templated DLS queries (ABAC)

模板化DLS查询（ABAC）

DLS queries support Mustache templates that inject user metadata at query time, enabling attribute-based access control (ABAC) on top of RBAC. Store user-specific attributes in the user's 
metadata
field, then reference them in the role query template with 
{{_user.metadata.<key>}}
.
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/department-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Department Reader",
    "indices": [
      {
        "names": ["records-*"],
        "privileges": ["read"],
        "query": "{\"template\": {\"source\": \"{\\\"term\\\": {\\\"department\\\": \\\"{{_user.metadata.department}}\\\"}}\"}}"
      }
    ]
  }'
A user with 
"metadata": {"department": "engineering"}
only sees documents where 
department
equals 
engineering
. The same role works for all departments — no per-department role needed.
For multi-valued attributes (e.g. a list of required programs), use 
terms_set
with 
minimum_should_match_field
to ensure the user holds all required attributes listed on the document. This enables complex ABAC policies — combining security levels, program lists, and certification dates — using a single role. See references/api-reference.md for full 
terms_set
ABAC examples including combined multi-condition policies and user metadata setup.
DLS查询支持Mustache模板，可在查询时注入用户元数据，实现基于RBAC之上的基于属性的访问控制（ABAC）。将用户特定属性存储在用户的
metadata
字段中，然后在角色查询模板中通过
{{_user.metadata.<key>}}
引用。
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/department-reader" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Department Reader",
    "indices": [
      {
        "names": ["records-*"],
        "privileges": ["read"],
        "query": "{\"template\": {\"source\": \"{\\\"term\\\": {\\\"department\\\": \\\"{{_user.metadata.department}}\\\"}}\"}}"
      }
    ]
  }'
若用户的元数据为
"metadata": {"department": "engineering"}
，则该用户仅能查看
department
等于
engineering
的文档。同一个角色可适用于所有部门 — 无需为每个部门单独创建角色。
对于多值属性（例如所需程序列表），可使用
terms_set
配合
minimum_should_match_field
，确保用户具备文档中列出的所有必要属性。这可实现复杂的ABAC策略 — 结合安全级别、程序列表和认证日期 — 只需单个角色即可完成。完整的
terms_set
ABAC示例（包括多条件组合策略和用户元数据设置）请参阅 references/api-reference.md。

Combining DLS and FLS

组合DLS与FLS

A single index privilege entry can include both 
query
(DLS) and 
field_security
(FLS). See the HR department example for a practical combined use case.
单个索引权限条目可同时包含
query
（DLS）和
field_security
（FLS）。实际组合使用案例请查看 HR部门示例。

Assign Roles to Users

为用户分配角色

Self-managed and ECH only. On Serverless, use the cloud-access-management skill — see Serverless User Access.
Update the user with the new 
roles
array:
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["role-a", "role-b"]
  }'
The 
roles
array is replaced entirely — include all roles the user should have. Fetch the user first to see current roles before updating.
仅适用于自托管和ECH部署。在Serverless部署中，请使用 cloud-access-management 技能 — 查看 Serverless用户访问。
通过新的
roles
数组更新用户：
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["role-a", "role-b"]
  }'
roles
数组会被完全替换 — 请包含用户应拥有的所有角色。更新前请先获取用户当前角色列表。

Manage Role Mappings

管理角色映射

Role mappings are not available on Serverless (both ES and Kibana APIs are disabled). Use the cloud-access-management skill instead — see Serverless User Access.
Role mappings assign external-realm users (LDAP, AD, SAML, PKI) to roles based on attribute rules. Self-managed and ECH only.
Serverless部署不支持角色映射（ES和Kibana API均已禁用）。请改用 cloud-access-management 技能 — 查看 Serverless用户访问。
角色映射可基于属性规则，将外部领域用户（LDAP、AD、SAML、PKI）与角色关联。仅适用于自托管和ECH部署。

Static role mapping

静态角色映射

bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["viewer"],
    "enabled": true,
    "rules": {
      "field": { "realm.name": "saml1" }
    }
  }'
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["viewer"],
    "enabled": true,
    "rules": {
      "field": { "realm.name": "saml1" }
    }
  }'

LDAP group-based mapping

基于LDAP组的映射

bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/ldap-admins" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["superuser"],
    "enabled": true,
    "rules": {
      "all": [
        { "field": { "realm.name": "ldap1" } },
        { "field": { "groups": "cn=admins,ou=groups,dc=example,dc=com" } }
      ]
    }
  }'
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/ldap-admins" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["superuser"],
    "enabled": true,
    "rules": {
      "all": [
        { "field": { "realm.name": "ldap1" } },
        { "field": { "groups": "cn=admins,ou=groups,dc=example,dc=com" } }
      ]
    }
  }'

Dynamic role assignment with Mustache templates

基于Mustache模板的动态角色分配

Use 
role_templates
instead of 
roles
to derive role names from user attributes. Scripting must be enabled.
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/ldap-group-roles" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "role_templates": [
      {
        "template": { "source": "{{#tojson}}groups{{/tojson}}" },
        "format": "json"
      }
    ],
    "enabled": true,
    "rules": {
      "field": { "realm.name": "ldap1" }
    }
  }'
See references/api-reference.md for more Mustache patterns including realm-username derived roles and tiered group access.
当需要从用户属性动态推导角色时，使用
role_templates
替代
roles
。需启用脚本功能。
bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role_mapping/ldap-group-roles" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "role_templates": [
      {
        "template": { "source": "{{#tojson}}groups{{/tojson}}" },
        "format": "json"
      }
    ],
    "enabled": true,
    "rules": {
      "field": { "realm.name": "ldap1" }
    }
  }'
更多Mustache模板模式（包括基于领域用户名推导角色和分层组访问）请参阅 references/api-reference.md。

Get, list, and delete role mappings

获取、列出和删除角色映射

bash
curl "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/role_mapping" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" <auth_flags>
bash
curl "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/role_mapping" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/role_mapping/saml-default-access" <auth_flags>

Serverless User Access

Serverless用户访问

On Serverless, there are no native users or role mappings. Users receive project access through Cloud-level role assignments.
  • Predefined roles (e.g. 
    admin
    , 
    developer
    , 
    viewer
    ) cover common access patterns. If one fits, assign it directly via the Cloud API — no custom role creation needed.
  • Custom roles are required when the user needs fine-grained access (specific indices, Kibana features, DLS/FLS). Create the custom role using the Elasticsearch API or Kibana API (same as self-managed — see Manage Roles), then assign it to the user alongside a predefined base role via the Cloud API.
Use the cloud-access-management skill for the full workflow (inviting users, assigning roles, managing Cloud API keys, and verifying access). This skill handles only role definition; cloud-access-management handles user assignment.
在Serverless部署中，不存在原生用户或角色映射。用户通过Cloud级别的角色分配获取项目访问权限。
  • 预定义角色（例如
    admin
    、
    developer
    、
    viewer
    ）覆盖常见访问场景。若符合需求，可直接通过Cloud API分配 — 无需创建自定义角色。
  • 自定义角色适用于用户需要细粒度访问权限的场景（特定索引、Kibana功能、DLS/FLS）。先通过Elasticsearch API或Kibana API创建自定义角色（与自托管部署方式相同 — 查看 管理角色），再通过Cloud API为用户分配自定义角色和预定义基础角色。
完整工作流（邀请用户、分配角色、管理Cloud API密钥、验证访问权限）请使用 cloud-access-management 技能。本技能仅处理角色定义，用户分配由cloud-access-management技能负责。

Examples

示例

Create a read-only user for logs

创建日志只读用户

Request: "Create a user 
joe
with read-only access to 
logs-*
."
  1. Create the role via 
    PUT /_security/role/logs-reader
    with 
    "description": "Logs Reader"
    and 
    indices: [{ names: ["logs-*"], privileges: ["read", "view_index_metadata"] }]
    .
  2. Create the user via 
    POST /_security/user/joe
    with 
    "roles": ["logs-reader"]
    and a strong generated password.
请求：“创建用户
joe
，使其对
logs-*
具备只读访问权限。”
  1. 执行
    PUT /_security/role/logs-reader
    创建角色，设置
    "description": "Logs Reader"
    和
    indices: [{ names: ["logs-*"], privileges: ["read", "view_index_metadata"] }]
    。
  2. 执行
    POST /_security/user/joe
    创建用户，设置
    "roles": ["logs-reader"]
    并生成强密码。

Create a role with Kibana dashboard access

创建包含Kibana仪表盘访问权限的角色

Request: "Let users read 
logs-*
and view dashboards in Kibana."
Use the Kibana API (
PUT <KIBANA_URL>/api/security/role/logs-dashboard-viewer
) with 
elasticsearch.indices
for data access and 
kibana[].feature
for dashboard and Discover read access on all spaces. See Create or update a role (Kibana API) for the full request structure.
请求：“允许用户读取
logs-*
并查看Kibana中的仪表盘。”
使用Kibana API (
PUT <KIBANA_URL>/api/security/role/logs-dashboard-viewer
)，通过
elasticsearch.indices
配置数据访问权限，通过
kibana[].feature
配置所有空间下的仪表盘和Discover只读权限。完整请求结构请查看 创建或更新角色（Kibana API）。

Add a role to an existing user

为现有用户添加角色

Request: "Give Alice access to 
apm-*
in addition to her current roles."
  1. GET /_security/user/alice
    — response shows 
    "roles": ["viewer"]
    .
  2. Create 
    apm-reader
    role with 
    indices: [{ names: ["apm-*"], privileges: ["read", "view_index_metadata"] }]
    .
  3. PUT /_security/user/alice
    with 
    "roles": ["viewer", "apm-reader"]
    (include all roles).
请求：“除现有权限外，为Alice添加
apm-*
的访问权限。”
  1. 执行
    GET /_security/user/alice
    — 响应显示
    "roles": ["viewer"]
    。
  2. 创建
    apm-reader
    角色，设置
    indices: [{ names: ["apm-*"], privileges: ["read", "view_index_metadata"] }]
    。
  3. 执行
    PUT /_security/user/alice
    ，设置
    "roles": ["viewer", "apm-reader"]
    （包含所有角色）。

Grant a Serverless user read-write access with Kibana dashboards

为Serverless用户分配读写权限及Kibana仪表盘访问权限

Request: "Give 
alice@example.com
read-write access to the 
colors
index and let her use dashboards and Discover."
  1. Create a custom role via the Kibana API: 
    PUT <KIBANA_URL>/api/security/role/colors-rw-kibana
    with 
    elasticsearch.indices
    for 
    read
    , 
    write
    , 
    view_index_metadata
    on 
    colors
    and 
    kibana[].feature
    for 
    dashboard
    , 
    discover
    .
  2. Use the cloud-access-management skill to assign the user the custom role 
    colors-rw-kibana
    .
请求：“为
alice@example.com
分配
colors
索引的读写权限，并允许其使用仪表盘和Discover。”
  1. 通过Kibana API创建自定义角色：
    PUT <KIBANA_URL>/api/security/role/colors-rw-kibana
    ，设置
    elasticsearch.indices
    为
    colors
    索引的
    read
    、
    write
    、
    view_index_metadata
    权限，
    kibana[].feature
    为
    dashboard
    和
    discover
    权限。
  2. 使用 cloud-access-management 技能为用户分配自定义角色
    colors-rw-kibana
    。

Restrict HR data by department (DLS + FLS)

按部门限制HR数据访问（DLS + FLS）

Request: "Each manager should only see HR records from their own department, and PII fields should be hidden."
  1. Create a user with department metadata: 
    POST /_security/user/manager_a
    with 
    "metadata": {"department": "engineering"}
    .
  2. Create a role with DLS + FLS:
json
PUT /_security/role/hr-department-viewer
{
  "description": "HR Department Viewer",
  "indices": [
    {
      "names": ["hr-*"],
      "privileges": ["read"],
      "field_security": { "grant": ["*"], "except": ["ssn", "salary", "date_of_birth"] },
      "query": "{\"template\": {\"source\": \"{\\\"term\\\": {\\\"department\\\": \\\"{{_user.metadata.department}}\\\"}}\"}}"
    }
  ]
}
The same role works for every department — each user sees only their department's records with PII fields removed.
请求：“每位经理仅能查看本部门的HR记录，且PII字段需隐藏。”
  1. 创建包含部门元数据的用户：执行
    POST /_security/user/manager_a
    ，设置
    "metadata": {"department": "engineering"}
    。
  2. 创建包含DLS+FLS的角色：
json
PUT /_security/role/hr-department-viewer
{
  "description": "HR Department Viewer",
  "indices": [
    {
      "names": ["hr-*"],
      "privileges": ["read"],
      "field_security": { "grant": ["*"], "except": ["ssn", "salary", "date_of_birth"] },
      "query": "{\"template\": {\"source\": \"{\\\"term\\\": {\\\"department\\\": \\\"{{_user.metadata.department}}\\\"}}\"}}"
    }
  ]
}
同一个角色适用于所有部门 — 每位用户仅能查看本部门的记录，且PII字段已被隐藏。

Guidelines

指导原则

Least-privilege principles

最小权限原则

  • Never use the 
    elastic
    superuser for day-to-day operations. Create dedicated minimum-privilege roles and reserve 
    elastic
    for initial setup and emergency recovery.
  • Use 
    read
    and 
    view_index_metadata
    for read-only data access. Leave 
    cluster
    empty unless explicitly required.
  • Use DLS (
    query
    ) and FLS (
    field_security
    ) to restrict access within an index.
  • 日常操作切勿使用
    elastic
    超级用户。创建专用的最小权限角色，仅在初始设置和紧急恢复时使用
    elastic
    账号。
  • 只读数据访问请使用
    read
    和
    view_index_metadata
    权限。除非明确需要，否则
    cluster
    字段留空。
  • 使用DLS (
    query
    )和FLS (
    field_security
    )限制索引内的访问范围。

Named privileges only

仅使用命名权限

Never use internal action names (e.g. 
indices:data/read/search
). Always use officially documented named privileges. Prefer fine-grained privileges (
manage_ingest_pipelines
, 
monitor
) over broad ones (
manage
, 
all
). See references/api-reference.md for the full privilege reference tables.
切勿使用内部操作名称（例如
indices:data/read/search
）。始终使用官方文档中定义的命名权限。优先使用细粒度权限（
manage_ingest_pipelines
、
monitor
）而非宽泛权限（
manage
、
all
）。完整权限参考表请参阅 references/api-reference.md。

Role naming conventions

角色命名规范

  • Use short lowercase names with hyphens: 
    logs-reader
    , 
    apm-data-viewer
    , 
    metrics-writer
    .
  • Avoid generic names like 
    custom-role
    or 
    new-role
    .
  • Set 
    description
    to a short, human-readable display name — not a long sentence. It is shown in the Kibana UI as the role's label. Good: 
    "Logs Reader"
    , 
    "APM Data Viewer"
    . Bad: 
    "Read-only access to all logs-* indices for the operations team"
    .
  • 使用短小写名称，以连字符分隔：
    logs-reader
    、
    apm-data-viewer
    、
    metrics-writer
    。
  • 避免使用
    custom-role
    或
    new-role
    等通用名称。
  • description
    字段设置为简短的人类可读名称 — 不要使用长句。该名称会在Kibana UI中作为角色标签显示。推荐：
    "Logs Reader"
    、
    "APM Data Viewer"
    。不推荐： 
    "Read-only access to all logs-* indices for the operations team"
    。

User management

用户管理

  • Generate strong passwords by default: at least 16 characters mixing uppercase, lowercase, digits, and symbols (e.g. 
    X9k#mP2vL!qR7wZn
    ). Never use placeholder values like 
    changeme
    or 
    password123
    .
  • Prefer disabling users over deleting them to preserve audit trail.
  • The 
    roles
    array on a user is replaced entirely on update. Always fetch current roles before modifying.
  • 默认生成强密码：至少16个字符，混合大小写字母、数字和符号（例如
    X9k#mP2vL!qR7wZn
    ）。切勿使用
    changeme
    或
    password123
    等占位符密码。
  • 优先禁用用户而非删除，以保留审计轨迹。
  • 用户的
    roles
    数组在更新时会被完全替换。修改前请务必获取当前角色列表。

Role mapping best practices

角色映射最佳实践

  • Use static 
    roles
    for simple, fixed assignments (e.g. all SAML users get 
    viewer
    ).
  • Use 
    role_templates
    with Mustache only when roles must be derived dynamically from user attributes.
  • Combine 
    all
    , 
    any
    , 
    field
    , and 
    except
    rules to express complex conditions without duplicating mappings.
  • Test new mappings with 
    enabled: false
    first, then enable once verified.
  • 简单固定分配请使用静态
    roles
    （例如所有SAML用户分配
    viewer
    角色）。
  • 仅当需要从用户属性动态推导角色时，才使用带Mustache模板的
    role_templates
    。
  • 组合使用
    all
    、
    any
    、
    field
    和
    except
    规则表达复杂条件，避免重复创建映射。
  • 新映射请先设置
    enabled: false
    进行测试，验证通过后再启用。

Deployment Compatibility

部署兼容性

See references/deployment-compatibility.md for a feature matrix and detailed notes on self-managed, ECH, and Serverless deployment differences.
自托管、ECH和Serverless部署的差异详情及功能矩阵请查看 references/deployment-compatibility.md。