文档中心

AgentKit

管理凭据

为火山云角色凭据更换角色

更换角色用于调整火山云角色凭据所使用的 IAM 角色。更换完成后，后续选择新角色换取的 STS 临时凭证将按新角色权限访问云资源。新签发凭证可访问的云资源和可执行的操作，由新角色权限、动态权限策略及云服务侧权限共同决定。

如果新角色未授予业务所需权限，可能导致 TOS、方舟或相关工具调用失败。操作前，请确认新角色已配置正确的信任关系和权限策略。了解更多

使用限制

是否支持直接更换角色，取决于凭据当前采用的角色配置方式：

配置方式	是否支持直接更换	说明
默认角色	支持	凭据使用固定角色，可通过更换角色直接替换。
规则匹配	不支持	角色由身份 Claim 和匹配规则决定，请通过编辑凭据调整匹配规则及对应角色。
调用方指定	不支持	角色由调用方在白名单范围内指定，请通过编辑凭据调整角色白名单。
混合模式	不支持	角色由调用方指定或规则匹配结果决定，请通过编辑凭据角色白名单、匹配规则或默认角色。

适用场景

前提条件

已完成目标 IAM 角色创建。

操作步骤

后续操作

角色更换完成后，请重新发起云资源调用，确认系统能够基于新角色申请 STS 临时凭证，并验证新角色的权限范围是否符合业务预期。

通过目标 Agent 发起一次需要访问云资源的调用，使系统基于新角色申请 STS 临时凭证。建议使用新的请求或会话进行验证，避免复用业务进程、运行实例或历史会话中缓存的旧凭证。如需通过智能体运行时验证，具体操作请参见创建运行时。

注意

验证新角色权限仅确认业务调用成功，无法证明新角色已正确限制非必要权限。

确认旧凭证的过期时间：查看申请临时凭证时返回的Expiration字段，记录旧凭证的最晚有效时间。字段说明和返回示例请参见 GetRoleCredentials - 获取角色凭据。

停止继续使用旧凭证：停止向新请求、定时任务和后台作业分发旧凭证，并清理业务进程、运行实例及会话中的凭证缓存。重新发起请求时，应确保系统使用新角色申请新的 STS 临时凭证。

调整旧角色权限：如需在旧凭证自然过期前收敛访问范围，请先核对旧 IAM 角色是否仍被其他业务、Agent、定时任务或云资源调用链路使用，再根据业务风险确定是否需要调整旧角色关联的权限策略，移除不再需要的操作或资源权限。具体操作请参见配置 IAM 策略的其他操作。

收紧云资源侧权限：如果目标云服务支持资源策略、访问控制列表、网络访问控制或其他服务侧限制，可同步撤销旧角色对目标资源的访问权限。具体配置方式请参见对应云服务的权限管理文档。

验证旧凭证已不可用：使用旧凭证对目标资源发起一次只读测试，确认请求已被拒绝；同时使用新凭证验证业务必需操作仍可正常执行。若通过 Agent 验证，可在智能体运行时中执行在线测试，具体操作请参见创建运行时。

最近更新时间：2026.10.23 16:53:59

这个页面对您有帮助吗？

有用

无用