cloud-access-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Access Management

Elastic Cloud访问管理

Manage identity and access for an Elastic Cloud organization and its Serverless projects: invite users, assign predefined or custom roles, and manage Cloud API keys.

Prerequisite: This skill assumes the cloud-setup skill has already run —
EC_API_KEY
is set in the environment and the organization context is established. If
EC_API_KEY
is missing, instruct the agent to invoke cloud-setup first. Do NOT prompt the user for an API key directly.

For project creation, see the cloud-create-project skill. For day-2 project operations (list, update, delete), see cloud-manage-project. For Elasticsearch-level role management (native users, role mappings, DLS/FLS), see the elasticsearch-authz skill.

For detailed API endpoints and request schemas, see references/api-reference.md.

管理Elastic Cloud组织及其Serverless项目的身份与访问权限：邀请用户、分配预定义或自定义角色，以及管理Cloud API密钥。

前提条件：本技能假设已运行cloud-setup技能——环境中已设置
EC_API_KEY
，且已建立组织上下文。如果缺少
EC_API_KEY
，请指示Agent先调用cloud-setup。请勿直接向用户索要API密钥。

项目创建相关内容，请查看cloud-create-project技能。日常项目操作（列出、更新、删除），请查看cloud-manage-project技能。Elasticsearch层面的角色管理（本地用户、角色映射、DLS/FLS），请查看elasticsearch-authz技能。

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

Jobs to Be Done

需完成的任务

Invite a user to the organization and assign them a Serverless project role
List organization members and their current role assignments
Update a user's roles (org-level or project-level)
Remove a user from the organization
Create an additional Cloud API key with scoped roles and expiration
List and revoke Cloud API keys
Create a custom role inside a Serverless project with ES cluster, index, and Kibana privileges
Assign or remove a custom role for a user on a Serverless project using the Cloud API's
```
application_roles
```
Translate a natural-language access request into invite, role, and API key tasks

邀请用户加入组织并为其分配Serverless项目角色
列出组织成员及其当前角色分配情况
更新用户的角色（组织级或项目级）
将用户从组织中移除
创建具有限定角色和过期时间的附加Cloud API密钥
列出并撤销Cloud API密钥
在Serverless项目中创建包含ES集群、索引和Kibana权限的自定义角色
通过Cloud API的
```
application_roles
```
为用户分配或移除Serverless项目的自定义角色
将自然语言的访问请求转换为邀请、角色分配和API密钥相关任务

Prerequisites

前提条件

Item	Description
EC_API_KEY	Cloud API key (set by cloud-setup). Required for all operations.
Organization ID	Auto-discovered using `GET /organizations` . Do not ask the user for it.
Project endpoint	Elasticsearch endpoint of a Serverless project. Required only for custom role operations.
ES credentials	API key or credentials with `manage_security` privilege on the project. Required only for custom roles.
Org owner role	Only Organization owners can create and manage Cloud API keys. Required for API key operations.

Run

python3 skills/cloud/access-management/scripts/cloud_access.py list-members

to verify that

EC_API_KEY

is valid and auto-discover the org ID before proceeding with any operation.

项	描述
EC_API_KEY	Cloud API密钥（由cloud-setup设置）。所有操作都需要此密钥。
组织ID	通过 `GET /organizations` 自动发现。请勿向用户索要。
项目端点	Serverless项目的Elasticsearch端点。仅自定义角色操作需要。
ES凭证	具有项目 `manage_security` 权限的API密钥或凭证。仅自定义角色操作需要。
组织所有者角色	只有组织所有者才能创建和管理Cloud API密钥。API密钥操作需要此角色。

运行

python3 skills/cloud/access-management/scripts/cloud_access.py list-members

来验证

EC_API_KEY

是否有效，并在执行任何操作前自动发现组织ID。

Decomposing Access Requests

分解访问请求

When the user describes access in natural language (for example, "add Alice to my search project as a developer"), break the request into discrete tasks before executing.

当用户用自然语言描述访问需求时（例如："将Alice添加到我的搜索项目中，赋予开发者权限"），在执行前将请求分解为独立任务。

Step 1 — Identify the components

步骤1 — 识别组成部分

Component	Question to answer
Who	New org member (invite) or existing member (role update)?
What	Which Serverless project(s) or org-level access?
Access level	Predefined role (Admin/Developer/Viewer/Editor) or custom role?
API key?	Does the request also need a Cloud API key for programmatic access?

组成部分	需要回答的问题
对象	是新组织成员（需要邀请）还是现有成员（需要更新角色）？
范围	针对哪些Serverless项目或组织级访问？
访问级别	预定义角色（管理员/开发者/查看者/编辑者）还是自定义角色？
是否需要API密钥？	请求是否还需要用于程序化访问的Cloud API密钥？

Step 2 — Check if a predefined role fits

步骤2 — 检查预定义角色是否适用

Consult the predefined roles table below. Prefer predefined roles — only create a custom role when predefined roles do not provide the required granularity.

参考下方的预定义角色表。优先使用预定义角色——只有当预定义角色无法满足所需粒度时，才创建自定义角色。

Step 3 — Check existing state

步骤3 — 检查现有状态

Before creating or inviting, check what already exists:

bash

python3 skills/cloud/access-management/scripts/cloud_access.py list-members
python3 skills/cloud/access-management/scripts/cloud_access.py list-api-keys

If the user is already a member, skip the invitation and update their roles instead.

For API key requests, only Organization owners can create and manage Cloud API keys. If the authenticated user does not have the

organization-admin

role, API key operations will fail with a 403 error. Review the existing keys returned by

list-api-keys

. If an active key already exists for the same purpose or task with the required roles and sufficient remaining lifetime, reuse it instead of creating a new one. Two keys with identical permissions are fine when they serve different purposes (for example, separate CI pipelines), but creating a second key for the same task is unnecessary and increases the management burden.

在创建或邀请前，先检查已存在的资源：

bash

python3 skills/cloud/access-management/scripts/cloud_access.py list-members
python3 skills/cloud/access-management/scripts/cloud_access.py list-api-keys

如果用户已是成员，跳过邀请步骤，直接更新其角色。

对于API密钥请求，只有组织所有者才能创建和管理Cloud API密钥。如果已认证用户没有

organization-admin

角色，API密钥操作会返回403错误。查看

list-api-keys

返回的现有密钥。如果已有一个用于相同用途或任务的有效密钥，且具备所需角色和足够的剩余有效期，请复用该密钥，无需创建新密钥。当用于不同用途时（例如：独立的CI流水线），可以存在两个权限相同的密钥，但为同一任务创建第二个密钥是不必要的，会增加管理负担。

Step 4 — Run

步骤4 — 执行

Run the appropriate command(s) from

skills/cloud/access-management/scripts/cloud_access.py

. Confirm destructive actions (remove member, revoke key) with the user before executing.

运行

skills/cloud/access-management/scripts/cloud_access.py

中的相应命令。在执行破坏性操作（移除成员、撤销密钥）前，请与用户确认。

Step 5 — Verify

步骤5 — 验证

After execution, list members or keys again to confirm the change took effect.

执行完成后，再次列出成员或密钥，确认更改已生效。

Predefined Roles

预定义角色

Organization-level roles

组织级角色

Role	Cloud API `role_id`	Description
Organization owner	`organization-admin`	Full admin over org, deployments, projects
Billing admin	`billing-admin`	Manage billing details only

角色	Cloud API `role_id`	描述
组织所有者	`organization-admin`	对组织、部署、项目拥有完全管理权限
账单管理员	`billing-admin`	仅管理账单详情

Serverless project-level roles

Serverless项目级角色

Role	Cloud API `role_id`	Available on	Description
Admin	`admin`	Search, Obs, Security	Full project management, superuser on sign-in
Developer	`developer`	Search only	Create indices, API keys, connectors, visualizations
Viewer	`viewer`	Search, Obs, Security	Read-only access to project data and features
Editor	`editor`	Obs, Security	Configure project features, read-only data indices
Tier 1 analyst	`t1_analyst`	Security only	Alert triage, general read, create dashboards
Tier 2 analyst	`t2_analyst`	Security only	Alert triage, begin investigations, create cases
Tier 3 analyst	`t3_analyst`	Security only	Deep investigation, rules, lists, response actions
SOC manager	`soc_manager`	Security only	Alerts, cases, endpoint policy, response actions
Rule author	`rule_author`	Security only	Detection engineering, rule creation

Project-level roles are assigned during invitation (

POST /organizations/{org_id}/invitations

) or using the role assignment update (

POST /users/{user_id}/role_assignments

). See references/api-reference.md for the

role_assignments

JSON schema including the

project

scope.

角色	Cloud API `role_id`	适用项目类型	描述
管理员	`admin`	搜索、可观测性、安全	完全项目管理权限，登录后为超级用户
开发者	`developer`	仅搜索	创建索引、API密钥、连接器、可视化
查看者	`viewer`	搜索、可观测性、安全	对项目数据和功能的只读访问权限
编辑者	`editor`	可观测性、安全	配置项目功能，对数据索引拥有只读权限
一级分析师	`t1_analyst`	仅安全	警报分类、常规读取、创建仪表盘
二级分析师	`t2_analyst`	仅安全	警报分类、初步调查、创建案例
三级分析师	`t3_analyst`	仅安全	深度调查、规则、列表、响应操作
SOC经理	`soc_manager`	仅安全	警报、案例、终端策略、响应行动
规则作者	`rule_author`	仅安全	检测工程、规则创建

项目级角色在邀请时（

POST /organizations/{org_id}/invitations

）或通过角色分配更新（

POST /users/{user_id}/role_assignments

）进行分配。有关包含

project

范围的

role_assignments

JSON schema，请参阅references/api-reference.md。

Custom Roles (Serverless)

自定义角色（Serverless）

When predefined roles lack the required granularity, create a custom role inside the Serverless project using the Elasticsearch security API and assign it to users through the Cloud API's

application_roles

field.

Security: do not assign a predefined Cloud role separately when using a custom role. Custom roles implicitly grant Viewer-level Cloud access for the project scope. If you also assign
viewer
(or any other predefined role) as a separate Cloud role assignment for the same project, the user receives the union of both roles when they SSO into the project — the Viewer stack role is broader than most custom roles and will override the restrictions you intended.

当预定义角色无法满足所需粒度时，可使用Elasticsearch安全API在Serverless项目中创建自定义角色，并通过Cloud API的

application_roles

字段为用户分配。

安全提示：使用自定义角色时，请勿单独分配预定义Cloud角色。 自定义角色会隐式授予项目范围的查看者级Cloud访问权限。如果您还为同一项目单独分配
viewer
（或其他任何预定义角色）作为Cloud角色，当用户SSO登录项目时，将获得两个角色的权限合集——查看者栈角色比大多数自定义角色的范围更广，会覆盖您原本想要设置的限制。

How custom role assignment works

自定义角色分配的工作原理

Predefined roles (
```
viewer
```
,
```
developer
```
,
```
admin
```
, etc.) are assigned via Cloud APIs (
```
invite-user
```
,
```
assign-role
```
). When the user SSOs into the project, they receive the stack role mapped to their Cloud role (for example, Cloud
```
viewer
```
maps to the
```
viewer
```
stack role).
Custom roles are created in the project via the Elasticsearch security API (
```
create-custom-role
```
) and assigned via the Cloud API's
```
application_roles
```
field (
```
assign-custom-role
```
). When
```
application_roles
```
is set, the user gets only the specified custom role on SSO — not the default stack role for their Cloud role.
The
```
assign-custom-role
```
command sets
```
role_id
```
to the project-type Viewer role (
```
elasticsearch-viewer
```
,
```
observability-viewer
```
, or
```
security-viewer
```
) and sets
```
application_roles
```
to the custom role name. This ensures the user can see and access the project in the Cloud console but receives only the custom role's restricted permissions inside the project.
Cloud API keys (
```
create-api-key
```
) currently carry Cloud roles only. Support for assigning custom roles to Cloud API keys is planned and will be documented here once available in production.

预定义角色（
```
viewer
```
、
```
developer
```
、
```
admin
```
等）通过Cloud API（
```
invite-user
```
、
```
assign-role
```
）分配。当用户SSO登录项目时，他们会获得与Cloud角色对应的栈角色（例如：Cloud
```
viewer
```
映射到
```
viewer
```
栈角色）。
自定义角色通过Elasticsearch安全API在项目中创建（
```
create-custom-role
```
），并通过Cloud API的
```
application_roles
```
字段分配（
```
assign-custom-role
```
）。当设置
```
application_roles
```
后，用户SSO登录时仅会获得指定的自定义角色——而非其Cloud角色对应的默认栈角色。
```
assign-custom-role
```
命令会将
```
role_id
```
设置为项目类型的查看者角色（
```
elasticsearch-viewer
```
、
```
observability-viewer
```
或
```
security-viewer
```
），并将
```
application_roles
```
设置为自定义角色名称。这确保用户可以在Cloud控制台中查看和访问项目，但在项目内部仅拥有自定义角色的受限权限。
当前Cloud API密钥（
```
create-api-key
```
）仅携带Cloud角色。为Cloud API密钥分配自定义角色的支持正在规划中，一旦在生产环境可用，将在此处更新文档。

Canonical custom-role onboarding flow

标准自定义角色入职流程

Create the custom role in the project (
```
create-custom-role
```
).
Invite the user to the organization if they are not already a member (
```
invite-user
```
). Do not include project role assignments in the invitation — the custom role assignment in the next step handles project access.

Assign the custom role to the user (

assign-custom-role --user-id ... --project-id ... --custom-role-name ...

Verify with
```
list-members
```
and
```
list-roles
```
.

在项目中创建自定义角色（
```
create-custom-role
```
）。
如果用户不是组织成员，邀请其加入（
```
invite-user
```
）。请勿在邀请中包含项目角色分配——下一步的自定义角色分配会处理项目访问权限。

为用户分配自定义角色（

assign-custom-role --user-id ... --project-id ... --custom-role-name ...

）。

通过
```
list-members
```
和
```
list-roles
```
验证。

Create a custom role

创建自定义角色

bash

python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
  --role-name marketing-analyst \
  --body '{"cluster":[],"indices":[{"names":["marketing-*"],"privileges":["read","view_index_metadata"]}]}'

This calls

PUT /_security/role/{name}

on the project Elasticsearch endpoint.

bash

python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
  --role-name marketing-analyst \
  --body '{"cluster":[],"indices":[{"names":["marketing-*"],"privileges":["read","view_index_metadata"]}]}'

此命令会调用项目Elasticsearch端点的

PUT /_security/role/{name}

接口。

Naming constraints

命名约束

Role names must begin with a letter or digit and contain only letters, digits,

, and

. Run-as privileges are not available in Serverless.

角色名称必须以字母或数字开头，且只能包含字母、数字、

、

和

。Serverless环境不支持Run-as权限。

When to use custom roles versus predefined

何时使用自定义角色 vs 预定义角色

Scenario	Use
Standard admin/developer/viewer access	Predefined role
Read-only access to specific index pattern	Custom role
DLS or FLS restrictions	Custom role
Kibana feature-level access control	Custom role

For advanced DLS/FLS patterns (templated queries, ABAC), see the elasticsearch-authz skill.

场景	推荐使用
标准管理员/开发者/查看者访问	预定义角色
对特定索引模式的只读访问	自定义角色
DLS或FLS限制	自定义角色
Kibana功能级访问控制	自定义角色

有关高级DLS/FLS模式（模板化查询、ABAC），请查看elasticsearch-authz技能。

Examples

示例

Invite a user as a Viewer on a search project

邀请用户作为搜索项目的查看者

Prompt: "Add

alice@example.com

to my search project with read-only access."

bash

python3 skills/cloud/access-management/scripts/cloud_access.py invite-user \
  --emails alice@example.com \
  --roles '{"project":{"elasticsearch":[{"role_id":"viewer","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"]}]}}'

Replace

$ORG_ID

and

$PROJECT_ID

with the actual IDs. The Viewer role is assigned when the invitation is accepted. For custom role access, use

assign-custom-role

after the user has accepted the invitation — do not combine a predefined role assignment with a custom role for the same project.

提示： "将

alice@example.com

添加到我的搜索项目，赋予只读访问权限。"

bash

python3 skills/cloud/access-management/scripts/cloud_access.py invite-user \
  --emails alice@example.com \
  --roles '{"project":{"elasticsearch":[{"role_id":"viewer","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"]}]}}'

将

$ORG_ID

和

$PROJECT_ID

替换为实际ID。查看者角色会在用户接受邀请后分配。对于自定义角色访问，请在用户接受邀请后使用

assign-custom-role

——请勿将预定义角色分配与同一项目的自定义角色分配结合使用。

Create a CI/CD API key

创建CI/CD API密钥

Prompt: "Create an API key for our CI pipeline that expires in 30 days with editor access to all deployments."

bash

python3 skills/cloud/access-management/scripts/cloud_access.py create-api-key \
  --description "CI/CD pipeline" \
  --expiration "30d" \
  --roles '{"deployment":[{"role_id":"deployment-editor","all":true}]}'

The actual key value is written to a secure temp file (0600 permissions). The stdout JSON contains a

_secret_file

path instead of the raw secret. Tell the user to retrieve the key from that file — it is shown only once. When the CI pipeline no longer needs this key, revoke it using

delete-api-key

to avoid unused keys accumulating.

提示： "为我们的CI流水线创建一个30天后过期的API密钥，拥有所有部署的编辑者权限。"

bash

python3 skills/cloud/access-management/scripts/cloud_access.py create-api-key \
  --description "CI/CD pipeline" \
  --expiration "30d" \
  --roles '{"deployment":[{"role_id":"deployment-editor","all":true}]}'

实际密钥值会写入一个安全的临时文件（权限为0600）。标准输出的JSON中包含

_secret_file

路径，而非原始密钥。请告知用户从该文件中获取密钥——密钥仅会显示一次。当CI流水线不再需要此密钥时，请使用

delete-api-key

撤销，避免积累未使用的密钥。

Create a custom role for marketing data

为营销数据创建自定义角色

Prompt: "Create a role that gives read-only access to marketing-* indices on my search project."

bash

python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
  --role-name marketing-reader \
  --body '{"cluster":[],"indices":[{"names":["marketing-*"],"privileges":["read","view_index_metadata"]}]}'

Then assign the custom role to a user using the

assign-custom-role

command, which sets

application_roles

in the Cloud API role assignment.

提示： "创建一个角色，赋予我的搜索项目中

marketing-*

索引的只读访问权限。"

bash

python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
  --role-name marketing-reader \
  --body '{"cluster":[],"indices":[{"names":["marketing-*"],"privileges":["read","view_index_metadata"]}]}'

然后使用

assign-custom-role

命令为用户分配自定义角色，该命令会在Cloud API角色分配中设置

application_roles

。

Full custom-role flow for read-only dashboards

只读仪表盘的完整自定义角色流程

Prompt: "Add

bob@example.com

to my search project with read-only dashboard access."

bash

undefined

提示： "将

bob@example.com

添加到我的搜索项目，赋予只读仪表盘访问权限。"

bash

undefined

1) Create custom role in the project

1) 在项目中创建自定义角色

python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role
--role-name dashboard-reader
--body '{"cluster":[],"indices":[],"applications":[{"application":"kibana-.kibana","privileges":["feature_dashboard.read"],"resources":["*"]}]}'

2) Invite user to the organization (no project roles — custom role handles access)

2) 邀请用户加入组织（不包含项目角色——自定义角色处理访问权限）

python3 skills/cloud/access-management/scripts/cloud_access.py invite-user
--emails bob@example.com

3) After invitation is accepted, assign the custom role via application_roles

3) 用户接受邀请后，通过application_roles分配自定义角色

python3 skills/cloud/access-management/scripts/cloud_access.py assign-custom-role
--user-id "$USER_ID"
--project-id "$PROJECT_ID"
--project-type elasticsearch
--custom-role-name dashboard-reader


The user receives Viewer-level Cloud access (can see the project in the console) and **only** `dashboard-reader`
permissions when they SSO into the project. Do not also assign `viewer` as a separate Cloud role for this project —
doing so would grant the broader Viewer stack role and override the custom role's restrictions.

python3 skills/cloud/access-management/scripts/cloud_access.py assign-custom-role
--user-id "$USER_ID"
--project-id "$PROJECT_ID"
--project-type elasticsearch
--custom-role-name dashboard-reader


用户会获得查看者级Cloud访问权限（可在控制台中查看项目），并且在SSO登录项目时**仅**拥有`dashboard-reader`权限。请勿为此项目单独分配`viewer`作为Cloud角色——这样会授予更广泛的查看者栈角色，覆盖自定义角色的限制。

Update a user's project role

更新用户的项目角色

Prompt: "Promote Bob to admin on our observability project."

bash

python3 skills/cloud/access-management/scripts/cloud_access.py assign-role \
  --user-id "$USER_ID" \
  --roles '{"project":{"observability":[{"role_id":"admin","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"]}]}}'

Replace

$USER_ID

$ORG_ID

, and

$PROJECT_ID

with actual values. Use

list-members

to look up the user ID. To remove a role assignment, use

remove-role-assignment

with the same

--roles

schema.

提示： "将Bob提升为我们可观测性项目的管理员。"

bash

python3 skills/cloud/access-management/scripts/cloud_access.py assign-role \
  --user-id "$USER_ID" \
  --roles '{"project":{"observability":[{"role_id":"admin","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"]}]}}'

将

$USER_ID

、

$ORG_ID

和

$PROJECT_ID

替换为实际值。使用

list-members

查找用户ID。要移除角色分配，请使用

remove-role-assignment

并传入相同的

--roles

schema。

List all members and their roles

列出所有成员及其角色

Prompt: "Show me who has access to my organization."

bash

python3 skills/cloud/access-management/scripts/cloud_access.py list-members

The output includes each member's user ID, email, and assigned roles.

提示： "告诉我谁有权访问我的组织。"

bash

python3 skills/cloud/access-management/scripts/cloud_access.py list-members

输出包含每个成员的用户ID、邮箱和已分配的角色。

Guidelines

指南

If
```
EC_API_KEY
```
is not set, do not prompt the user — instruct the agent to invoke cloud-setup first.
Always confirm destructive actions (remove member, revoke key) with the user before executing.
Prefer predefined roles over custom roles when they satisfy the access requirement.
API keys created here are additional keys for CI/CD, scoped access, or team members. The initial key is managed by cloud-setup.
Secrets are never printed to stdout or stderr. The script replaces sensitive fields (
```
key
```
,
```
token
```
,
```
invitation_token
```
) with a
```
REDACTED
```
placeholder in stdout and writes the full unredacted response to a temporary file with 0600 (owner-read-only) permissions. The stdout JSON includes a
```
_secret_file
```
path pointing to that file. Never attempt to read, extract, or summarize the contents of the secret file. If the user asks for the key, tell them to open the file at the
```
_secret_file
```
path. After the user retrieves the secret, advise them to delete the file.
Cloud API keys inherit roles at creation and cannot be updated — revoke and recreate to change roles.
API key hygiene — minimize, scope, and expire:
- Before creating a key, always run
```
list-api-keys
```
  and check whether an existing key for the same purpose or task already has the required roles and sufficient remaining lifetime. Keys with identical permissions serving different purposes (for example, two separate CI pipelines) are legitimate — the goal is to avoid redundant keys for the same task.
- Always set an
```
--expiration
```
  that matches the intended task lifetime. Short-lived tasks (CI runs, one-time migrations) should use short-lived keys (for example,
```
1d
```
  ,
```
7d
```
  ).
- After a task is complete, prompt the user to revoke any keys that are no longer needed using
```
delete-api-key
```
  . This applies to both short-lived and long-running keys.
- Long-running keys (for example, monitoring pipelines) should still have a defined expiration and be rotated periodically rather than set to never expire.
Each organization supports up to 500 active API keys. Default expiration is 3 months.
Invitations expire after 72 hours by default. Resend if the user has not accepted.
For SAML SSO configuration, refer to Elastic Cloud SAML docs.
Custom role security — do not over-assign: Never assign a predefined Cloud role (for example,
```
viewer
```
) for a project when using
```
assign-custom-role
```
for the same project. The custom role assignment implicitly grants Viewer-level Cloud access. Adding a predefined role on top widens the user's in-project permissions beyond what the custom role intended.
If a custom role exists but the user cannot access the project, verify the role was assigned with
```
assign-custom-role
```
(which uses
```
application_roles
```
in the Cloud API). Creating a custom role alone does not grant project access — the Cloud API assignment is required.
For network-level security (traffic filters, private links), see the cloud-network-security skill.
For ES-level role management beyond Cloud roles (native users, DLS/FLS), see elasticsearch-authz.

如果未设置
```
EC_API_KEY
```
，请勿向用户索要——请指示Agent先调用cloud-setup。
在执行破坏性操作（移除成员、撤销密钥）前，务必与用户确认。
当预定义角色满足访问需求时，优先使用预定义角色而非自定义角色。
在此创建的API密钥是用于CI/CD、限定访问或团队成员的附加密钥。初始密钥由cloud-setup管理。
敏感信息绝不会打印到标准输出或标准错误流。脚本会在标准输出中用
```
REDACTED
```
占位符替换敏感字段（
```
key
```
、
```
token
```
、
```
invitation_token
```
），并将完整的未脱敏响应写入权限为0600（仅所有者可读）的临时文件。标准输出的JSON中包含指向该文件的
```
_secret_file
```
路径。切勿尝试读取、提取或总结敏感文件的内容。如果用户索要密钥，请告知他们打开
```
_secret_file
```
路径对应的文件。用户获取敏感信息后，建议他们删除该文件。
Cloud API密钥在创建时继承角色，无法更新——如需更改角色，请撤销并重新创建。
API密钥最佳实践——最小化、限定范围、设置过期时间：
- 创建密钥前，务必运行
```
list-api-keys
```
  ，检查是否已有用于相同用途或任务的有效密钥，且具备所需角色和足够的剩余有效期。当用于不同用途时（例如：两个独立的CI流水线），可以存在权限相同的密钥——目标是避免为同一任务创建冗余密钥。
- 始终设置与预期任务生命周期匹配的
```
--expiration
```
  。短期任务（CI运行、一次性迁移）应使用短期密钥（例如：
```
1d
```
  、
```
7d
```
  ）。
- 任务完成后，提示用户使用
```
delete-api-key
```
  撤销不再需要的密钥。这适用于短期和长期运行的密钥。
- 长期运行的密钥（例如：监控流水线）也应设置明确的过期时间，并定期轮换，而非设置为永不过期。
每个组织最多支持500个有效API密钥。默认过期时间为3个月。
邀请默认72小时后过期。如果用户未接受，请重新发送。
有关SAML SSO配置，请参阅Elastic Cloud SAML文档。
自定义角色安全提示——切勿过度分配： 使用
```
assign-custom-role
```
为项目分配角色时，请勿为同一项目分配预定义Cloud角色（例如：
```
viewer
```
）。自定义角色分配会隐式授予查看者级Cloud访问权限。额外分配预定义角色会扩大用户在项目内的权限，超出自定义角色原本的限制。
如果自定义角色已存在，但用户无法访问项目，请验证是否已通过
```
assign-custom-role
```
分配角色（该命令会在Cloud API中使用
```
application_roles
```
）。仅创建自定义角色不会授予项目访问权限——必须通过Cloud API分配。
有关网络级安全（流量过滤器、专用链接），请查看cloud-network-security技能。
有关Cloud角色之外的ES级角色管理（本地用户、DLS/FLS），请查看elasticsearch-authz技能。