elasticsearch-authz by elastic/agent-skills
npx skills add https://github.com/elastic/agent-skills --skill elasticsearch-authz管理 Elasticsearch 基于角色的访问控制:原生用户、角色、角色分配以及外部领域的角色映射。
关于身份验证方法和 API 密钥管理,请参阅 elasticsearch-authn 技能。
详细的 API 端点信息,请参见 references/api-reference.md。
部署说明: 功能在自托管、ECH 和 Serverless 之间的可用性不同。详情请参阅部署兼容性。
| 项目 | 描述 |
|---|---|
| Elasticsearch URL | 集群端点(例如 https://localhost:9200 或 Cloud 部署 URL) |
| Kibana URL |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 仅在设置 Kibana 功能/空间权限时需要 |
| 身份验证 | 有效的凭据(请参阅 elasticsearch-authn 技能) |
| 集群权限 | 用户和角色管理操作需要 manage_security 权限 |
提示用户输入任何缺失的值。
当用户用自然语言描述访问权限时(例如“创建一个对 logs-* 具有只读访问权限的用户”),在执行之前将请求分解为离散的任务。遵循以下工作流程:
从提示中提取:
| 组件 | 需要回答的问题 |
|---|---|
| 谁 | 新的原生用户、现有用户还是外部领域用户(LDAP、SAML 等) |
| 什么 | 哪些索引、数据流或 Kibana 功能 |
| 访问级别 | 读取、写入、管理或特定的权限集 |
| 范围 | 所有文档/字段,还是按区域、部门、敏感性限制? |
| Kibana? | 请求是否提及任何 Kibana 功能(仪表板、Discover 等) |
| 部署? | 自托管、ECH 还是 Serverless?Serverless 具有不同的用户模型。 |
在创建新角色之前,检查现有角色是否已授予所需的访问权限:
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
如果存在匹配的角色,则跳过角色创建并重用该角色。
根据请求派生角色名称和显示名称。对于纯索引/集群角色,使用 Elasticsearch API。如果涉及 Kibana 功能,则使用 Kibana API(请参阅选择正确的 API)。
| 场景 | 操作 |
|---|---|
| 新的原生用户 | 使用该角色和强生成的密码创建用户。(仅限自托管 / ECH。) |
| 现有的原生用户 | 获取当前角色,追加新角色,使用完整数组更新用户。(仅限自托管 / ECH。) |
| 外部领域用户 | 创建角色映射,将用户的领域属性与角色匹配。(仅限自托管 / ECH。) |
| Serverless 用户 | 使用 cloud-access-management 技能。分配预定义角色或先创建自定义角色,然后通过 Cloud API 分配。 |
提示: “创建一个用户 analyst,使其对 logs-* 和 metrics-* 具有只读访问权限,并能在 Kibana 中查看仪表板。”
analyst,索引 logs-*/metrics-*,仪表板,读取访问权限。GET /_security/role — 无匹配项。logs-metrics-dashboard-viewer。POST /_security/user/analyst,附带 roles: ["logs-metrics-dashboard-viewer"]。如果请求不明确,请与用户确认每个步骤。
原生用户管理适用于自托管和 ECH 部署。在 Serverless 上,用户在组织级别进行管理 — 请跳过此部分。
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
}'
使用 PUT /_security/user/${USERNAME} 并附带要更改的字段。省略 password 以保留现有密码。
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>
当角色仅需要 cluster 和 indices 权限时,使用 Elasticsearch API (PUT /_security/role/{name})。这是默认选择 — 不需要 Kibana 端点。
当角色包含任何 Kibana 功能或空间权限时,使用 Kibana 角色 API (PUT /api/security/role/{name})。Elasticsearch API 无法设置 Kibana 功能授权、空间范围或基本权限,因此如果用户提及 Kibana 功能,如 Discover、Dashboards、Maps、Visualize、Canvas 或任何其他 Kibana 应用程序,则需要使用 Kibana API。
如果 Kibana 端点不可用或对 Kibana 的 API 密钥身份验证失败,则回退到 Elasticsearch API 来处理 cluster 和 indices 部分,并警告用户无法设置 Kibana 权限。在放弃之前,提示输入 Kibana URL 或替代凭据。
当角色只有索引和集群权限时的默认选择:
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"]
}
]
}'
当角色包含 Kibana 功能或空间权限时需要:
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": ["*"]
}
]
}'
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>
角色可以在索引内限制文档和字段级别的访问,超越索引级权限。
限制角色可以查看的字段。使用 grant 进行白名单或 except 进行黑名单:
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 在搜索、获取和聚合结果上强制执行。
通过附加查询过滤器来限制角色可以查看的文档:
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 的文档。
DLS 查询支持 Mustache 模板,可在查询时注入用户元数据,从而在 RBAC 之上实现基于属性的访问控制(ABAC)。将用户特定属性存储在用户的 metadata 字段中,然后在角色查询模板中使用 {{_user.metadata.<key>}} 引用它们。
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 的文档。同一个角色适用于所有部门 — 无需每个部门一个角色。
对于多值属性(例如所需程序列表),使用带有 minimum_should_match_field 的 terms_set 来确保用户拥有文档上列出的所有必需属性。这使得能够使用单个角色实现复杂的 ABAC 策略 — 结合安全级别、程序列表和认证日期。有关完整的 terms_set ABAC 示例,包括组合多条件策略和用户元数据设置,请参见 references/api-reference.md。
单个索引权限条目可以同时包含 query(DLS)和 field_security(FLS)。请参阅人力资源部门示例,了解实际结合使用的案例。
仅限自托管和 ECH。在 Serverless 上,使用 cloud-access-management 技能 — 请参阅 Serverless 用户访问。
使用新的 roles 数组更新用户:
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
<auth_flags> \
-H "Content-Type: application/json" \
-d '{
"roles": ["role-a", "role-b"]
}'
roles 数组会被完全替换 — 包含用户应拥有的所有角色。在更新之前,请先获取用户以查看当前角色。
角色映射在 Serverless 上不可用(ES 和 Kibana API 均被禁用)。请改用 cloud-access-management 技能 — 请参阅 Serverless 用户访问。
角色映射根据属性规则将外部领域用户(LDAP、AD、SAML、PKI)分配给角色。仅限自托管和 ECH。
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" }
}
}'
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" } }
]
}
}'
使用 role_templates 代替 roles,从用户属性派生角色名称。必须启用脚本功能。
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。
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 上,没有原生用户或角色映射。用户通过 Cloud 级别的角色分配获得项目访问权限。
admin、developer、viewer)涵盖了常见的访问模式。如果某个角色合适,直接通过 Cloud API 分配 — 无需创建自定义角色。对于完整的工作流程(邀请用户、分配角色、管理 Cloud API 密钥和验证访问),请使用 cloud-access-management 技能。本技能仅处理角色定义;cloud-access-management 处理用户分配。
请求: “创建一个用户 joe,使其对 logs-* 具有只读访问权限。”
PUT /_security/role/logs-reader 创建角色,附带 "description": "Logs Reader" 和 indices: [{ names: ["logs-*"], privileges: ["read", "view_index_metadata"] }]。POST /_security/user/joe 创建用户,附带 "roles": ["logs-reader"] 和一个强生成的密码。请求: “让用户读取 logs-* 并在 Kibana 中查看仪表板。”
使用 Kibana API (PUT <KIBANA_URL>/api/security/role/logs-dashboard-viewer),附带 elasticsearch.indices 用于数据访问,kibana[].feature 用于在所有空间上对仪表板和 Discover 的读取访问权限。完整的请求结构请参阅创建或更新角色(Kibana API)。
请求: “除了她当前的角色外,给予 Alice 对 apm-* 的访问权限。”
GET /_security/user/alice — 响应显示 "roles": ["viewer"]。apm-reader 角色,附带 indices: [{ names: ["apm-*"], privileges: ["read", "view_index_metadata"] }]。PUT /_security/user/alice,附带 "roles": ["viewer", "apm-reader"](包含所有角色)。请求: “给予 alice@example.com 对 colors 索引的读写访问权限,并让她能够使用仪表板和 Discover。”
PUT <KIBANA_URL>/api/security/role/colors-rw-kibana,附带 elasticsearch.indices 用于对 colors 的 read、write、view_index_metadata 权限,以及 kibana[].feature 用于 dashboard、discover 权限。colors-rw-kibana。请求: “每位经理应只能看到其所在部门的人力资源记录,并且 PII 字段应被隐藏。”
POST /_security/user/manager_a,附带 "metadata": {"department": "engineering"}。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 字段已被移除。
elastic 超级用户用于日常操作。创建专用的最小权限角色,并将 elastic 保留用于初始设置和紧急恢复。read 和 view_index_metadata。除非明确需要,否则将 cluster 留空。query) 和 FLS (field_security) 来限制索引内的访问。切勿使用内部操作名称(例如 indices:data/read/search)。始终使用官方文档记录的命名权限。优先使用细粒度权限(manage_ingest_pipelines、monitor)而非宽泛权限(manage、all)。完整的权限参考表请参见 references/api-reference.md。
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"。X9k#mP2vL!qR7wZn)。切勿使用占位符值,如 changeme 或 password123。roles 数组在更新时会被完全替换。在修改之前,请始终获取当前角色。viewer),使用静态 roles。role_templates。all、any、field 和 except 规则来表达复杂条件,而无需重复映射。enabled: false 测试新映射,验证后再启用。有关自托管、ECH 和 Serverless 部署差异的功能矩阵和详细说明,请参见 references/deployment-compatibility.md。
每周安装次数
168
仓库
GitHub Stars
136
首次出现
11 天前
安全审计
安装于
cursor152
github-copilot144
opencode143
gemini-cli143
codex143
amp142
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.
| Item | Description |
|---|---|
| Elasticsearch URL | Cluster endpoint (e.g. https://localhost:9200 or a Cloud deployment URL) |
| Kibana URL | Required only when setting Kibana feature/space privileges |
| Authentication | Valid 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.
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:
Extract from the prompt:
| Component | Question to answer |
|---|---|
| Who | New native user, existing user, or external realm user (LDAP, SAML, etc.) |
| What | Which indices, data streams, or Kibana features |
| Access level | Read, write, manage, or a specific set of privileges |
| Scope | All 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. |
Before creating a new role, check if an existing role already grants the required access:
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
If a matching role exists, skip role creation and reuse it.
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).
| Scenario | Action |
|---|---|
| New native user | Create the user with the role and a strong generated password. (Self-managed / ECH only.) |
| Existing native user | Fetch current roles, append the new role, update the user with the full array. (Self-managed / ECH only.) |
| External realm user | Create a role mapping that matches the user's realm attributes to the role. (Self-managed / ECH only.) |
| Serverless user | Use the cloud-access-management skill. Assign a predefined role or create a custom role first, then assign it via the Cloud API. |
Prompt: "Create a user analyst with read-only access to logs-* and metrics-* and view dashboards in Kibana."
analyst, indices logs-*/metrics-*, dashboards, read access.GET /_security/role — no match.logs-metrics-dashboard-viewer.POST /_security/user/analyst with roles: ["logs-metrics-dashboard-viewer"].Confirm each step with the user if the request is ambiguous.
Native user management applies to self-managed and ECH deployments. On Serverless, users are managed at the organization level — skip this section.
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
}'
Use PUT /_security/user/${USERNAME} with the fields to change. Omit password to keep the existing one.
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>
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.
Default choice when the role has only index and cluster privileges:
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"]
}
]
}'
Required when the role includes Kibana feature or space privileges:
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": ["*"]
}
]
}'
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>
Roles can restrict access at the document and field level within an index, going beyond index-level privileges.
Restrict which fields a role can see. Use grant to whitelist or except to blacklist fields:
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.
Restrict which documents a role can see by attaching a query filter:
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.
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>}}.
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.
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.
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:
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.
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.
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" }
}
}'
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" } }
]
}
}'
Use role_templates instead of roles to derive role names from user attributes. Scripting must be enabled.
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.
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>
On Serverless, there are no native users or role mappings. Users receive project access through Cloud-level role assignments.
admin, developer, viewer) cover common access patterns. If one fits, assign it directly via the Cloud API — no custom role creation needed.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.
Request: "Create a user joe with read-only access to logs-*."
PUT /_security/role/logs-reader with "description": "Logs Reader" and indices: [{ names: ["logs-*"], privileges: ["read", "view_index_metadata"] }].POST /_security/user/joe with "roles": ["logs-reader"] and a strong generated password.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.
Request: "Give Alice access to apm-* in addition to her current roles."
GET /_security/user/alice — response shows "roles": ["viewer"].apm-reader role with indices: [{ names: ["apm-*"], privileges: ["read", "view_index_metadata"] }].PUT /_security/user/alice with "roles": ["viewer", "apm-reader"] (include all roles).Request: "Give alice@example.com read-write access to the colors index and let her use dashboards and Discover."
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.colors-rw-kibana.Request: "Each manager should only see HR records from their own department, and PII fields should be hidden."
POST /_security/user/manager_a with "metadata": {"department": "engineering"}.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.
elastic superuser for day-to-day operations. Create dedicated minimum-privilege roles and reserve elastic for initial setup and emergency recovery.read and view_index_metadata for read-only data access. Leave cluster empty unless explicitly required.query) and FLS (field_security) to restrict access within an index.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.
logs-reader, apm-data-viewer, metrics-writer.custom-role or new-role.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".X9k#mP2vL!qR7wZn). Never use placeholder values like changeme or password123.roles array on a user is replaced entirely on update. Always fetch current roles before modifying.roles for simple, fixed assignments (e.g. all SAML users get viewer).role_templates with Mustache only when roles must be derived dynamically from user attributes.all, any, field, and except rules to express complex conditions without duplicating mappings.enabled: false first, then enable once verified.See references/deployment-compatibility.md for a feature matrix and detailed notes on self-managed, ECH, and Serverless deployment differences.
Weekly Installs
168
Repository
GitHub Stars
136
First Seen
11 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
cursor152
github-copilot144
opencode143
gemini-cli143
codex143
amp142