火山云角色凭据用于将 AgentKit 中的用户或智能体身份映射到火山引擎云角色，并在访问 TOS、方舟等云资源时换取 STS 临时凭证。创建时可选择默认角色、规则匹配、调用方指定或混合模式，以满足统一授权、按身份属性授权和受控角色切换等场景。

本文介绍如何在 AgentKit 控制台中创建火山云角色凭据，并根据业务需求配置身份来源、云角色分配方式和所属项目。

推荐场景

Agent 访问火山引擎云资源

当 Agent 需要访问 TOS、方舟或其他支持火山云角色鉴权的资源时，可创建火山云角色凭据，通过角色换取 STS 临时凭证并完成身份认证。

使用临时凭证替代长期固定密钥

当业务不希望在代码或配置中保存长期 Access Key 时，可通过火山云角色凭据按需获取 STS 临时凭证，降低固定密钥泄露和长期暴露的风险。

前提条件

准备 IAM 角色与授权配置

准备 IAM 角色

请准备可用于访问云资源的 IAM 角色，并按照最小权限原则为其授予业务所需权限。

准备操作人员权限

除目标 IAM 角色本身需要具备相应权限外，执行角色创建、策略关联或信任策略更新的操作人员，也需要具备对应的 IAM 和 AgentKit 操作权限。有关操作人员所需权限及授权方法，请参见为 IAM 用户授权 AgentKit 权限。

创建用户池（可选）

若身份类型选择用户池，需先完成目标用户池及客户端的创建。后续配置火山云角色凭据时，需要从已创建的用户池中选择目标用户池，并关联对应客户端，用于识别和验证调用方身份。

创建智能体身份池（可选）

若身份类型选择智能体身份池，需先完成目标智能体身份池的创建。后续配置火山云角色凭据时，需要选择目标智能体身份池，作为工作负载身份的来源范围。

操作步骤

步骤一：选择火山云角色

火山云角色凭据通过 Agent 身份换取 STS 临时凭证，适用于访问 TOS、方舟等火山引擎云资源。

登录 AgentKit 控制台。

在左侧导航树，选择“身份与权限 > 凭据管理”。

进入凭据管理页面，单击“新建凭据”按钮。

在“选类型”页面选择“火山云角色”。

确认待选择信息无误后，单击“下一步”按钮。

步骤二：配置云角色基本信息和身份来源

参考下表，配置基本信息和身份来源参数。身份来源决定系统使用哪类主体信息进行角色匹配和 STS 临时凭证换取，请根据实际调用主体选择。

参数	说明
基本信息
名称	自定义凭据名称，用于在凭据列表和后续调用中识别该凭据。建议名称能够体现业务、用途和环境，例如 tos-reader-prod 或 ark-runtime-test ，避免使用含义不明确或重复的名称。
云厂商	确认“云厂商”为“火山引擎”。当前固定为火山引擎，表示该凭据用于换取火山引擎云角色对应的 STS 临时凭证，不支持手动修改。
身份来源
身份类型	指定用于换取云角色的主体身份来源。支持以下选项：用户池：使用用户池中的用户身份及其 Claim 参与角色分配，适用于按用户、部门、用户组或其他用户属性控制云资源访问权限的场景。智能体身份池：使用智能体或工作负载身份参与角色分配，适用于 Agent 以自身身份访问火山引擎云资源的场景。
用户池	选择提供用户身份信息的目标用户池。后续配置规则匹配时，可以使用该用户池身份令牌中的 Claim，将不同用户映射到对应的云角色。说明仅选择“身份类型”为用户池时必填。
客户端	选择目标用户池下用于验证和识别调用方的客户端。客户端选项与用户池联动，在选择用户池前该字段不可配置，页面提示为“请先选择用户池”。说明仅选择“身份类型”为用户池时必填。
智能体身份池	选择提供智能体或工作负载身份的目标身份池，页面提示为“请选择工作负载池”。后续请求将基于该身份池中的主体身份进行角色分配和临时凭证换取。说明选择“身份类型”为智能体身份池时必填。

步骤三：配置云角色权限

您可以结合业务的权限模型与角色分配方式，在默认角色、规则匹配、调用方指定、混合模式四种模式中按需选用其一。不同的配置模式，将决定系统在换取 STS 临时凭证的过程中，采用何种策略为当前请求判定对应的 IAM 角色。

默认角色：固定使用预设的 IAM 角色处理请求。

规则匹配：依据请求携带的属性，通过自定义规则自动匹配 IAM 角色。

调用方指定：由调用方在请求中主动声明本次需要使用的 IAM 角色。

混合模式：组合多种判定逻辑，按优先级选择 IAM 角色。

默认角色

规则匹配

调用方指定

混合模式

该方式配置简单，所有符合身份来源要求的请求统一使用同一角色。当不同用户或智能体访问云资源时需要使用相同权限，可选择默认角色，统一使用指定 IAM 角色换取临时凭证。

说明

建议为默认角色授予业务必需的最小权限，避免所有调用主体共享权限范围过大的角色。

在“配置方式”中选择“默认角色”。

在“默认角色”中，单击“点击配置”按钮，选择已有的 IAM 角色，或输入并回车创建新角色。

若使用已有 IAM 角色：请确认目标角色已关联访问业务资源所需的权限策略。若尚未授权，可在 IAM 控制台找到目标权限策略，单击“授权”按钮，将该策略授予目标角色，详情请参见权限策略概述中的授权操作说明。

选择角色后，控制台将自动检查其信任策略是否允许具备允许 ID 服务扮演角色的信任配置。

信任对象：ID 服务。

允许的操作：sts:AssumeRole，即允许 ID 服务扮演该角色并获取临时访问凭证。

若已包含所需信任配置，可直接继续操作。

若缺少所需信任配置，控制台将弹出确认更新角色信任策略对话框。确认后，平台会保留原有信任配置，并追加允许ID服务执行 sts:AssumeRole的信任条目，不会覆盖已有配置。

若在当前页面新建 IAM 角色：在配置云权限页面输入角色名称并按回车按键创建新角色，并勾选所需权限策略。确认后，平台将创建角色、关联策略并写入必要的信任配置。

说明

角色关联的权限策略决定其具备哪些基础资源权限；“动态权限策略”用于在这些权限内进一步限制本次访问，不能替代角色的基础资源授权。

（可选）您可按需配置动态权限策略，在调用时动态注入 IAM Policy，用于进一步限制角色的实际权限范围。支持通过${claim_name} 引用 OIDC Token 中的 Claim。

策略内容应使用符合要求的 IAM Policy JSON。

确认配置的云权限无误后，单击“确定”按钮。

步骤四：配置资源管理

在资源管理区域选择该凭据所属项目，系统默认选择default（默认项目）；也可按需切换项目或新建项目。

一个资源仅可归属于一个项目，如需更改凭据所属项目，可单击所属项目下拉列表并选择目标项目。

选定项目后，创建的凭据仅支持具有该项目权限的用户访问和使用。

如当前项目不符合业务需求，可单击“新建项目”按钮进行创建。创建完成后，返回当前页面并选择新建的项目。

步骤五：提交并确认结果

检查名称、身份来源、配置方式、角色和所属项目。

确认无误后，单击“创建”。

进入“完成”阶段后，确认凭据创建结果，并按需查看凭据详情。