全部产品
Search
文档中心

访问控制:扮演RAM角色

更新时间:Feb 06, 2026

本文介绍如何通过控制台、CLI和API的方式扮演RAM角色,以临时获取该角色的权限来访问阿里云资源。

什么是RAM角色扮演

与RAM用户不同,您不能直接用RAM角色登录控制台。您需要先用RAM用户或SSO登录控制台后,再切换到目标RAM角色,这个过程称为RAM角色扮演

角色扮演成功后,原身份所拥有的权限将暂时失去,转而获得被扮演的RAM角色所拥有的权限。被扮演的RAM角色可以与登录的RAM用户属于同一阿里云账号,也可以属于不同账号(跨账号角色扮演)。

工作原理

下面以RAM用户Alice尝试扮演RAM角色prod-role,并以角色身份访问OSS对象存储为例,解释角色扮演工作原理:

image
  1. 请求扮演RAM角色:RAM用户Alice向阿里云STS服务请求扮演RAM角色prod-role的临时安全凭证(STS Token)。RAM会验证Alice的身份(例如AccessKey),是否具有扮演该角色的权限(sts:AssumeRole),以及prod-role的信任策略是否允许Alice扮演(Principal是否匹配Alice)。

  2. 获取临时安全凭证:验证通过后,Alice获得由阿里云STS服务返回的STS Token。

  3. 以角色身份访问云资源:Alice使用获取到的STS Token,以prod-role角色身份访问OSS对象存储等云资源。此时Alice的原有权限暂时失效,转而拥有prod-role角色的权限。最终资源访问权限由角色prod-role的权限策略(oss:*)决定。

角色扮演的方式

你可以通过以下四种方式扮演RAM角色:

  • RAM用户在登录阿里云控制台后,使用切换身份功能切换到目标角色。

  • 管理员或开发者使用阿里云CLI、SDK或OpenAPI调用 AssumeRole接口(或其他角色扮演相关接口,如AssumeRoleWithSAML),获取临时安全凭证(STS Token)。

  • 用户使用角色SSO的方式(基于SAML2.0协议),经由用户的企业身份提供商(IdP)登录控制台。在这种场景下,用户在完成控制台登录时已经成功扮演了RAM角色。

  • 将角色绑定或关联到特定阿里云资源(如ECS实例,函数计算FC或ACK/ACS Pod),然后使用阿里云平台的内置功能来完成角色扮演。具体内容,请参见:阿里云上的应用访问阿里云资源

对于后两种场景,本文不作具体描述。关于如何使用,请参见上述相关参考文档。

角色会话的有效时间

角色会话是指实体身份(如RAM用户或其他可信实体)在成功扮演角色后,所建立的有时限的访问会话。角色会话的有效时间控制着您以该角色身份执行操作的可用时长。会话到期后,您需要重新通过扮演角色来获取新的会话。

控制台

决定因素

默认值

取值范围

说明

角色最大会话时间

1小时

1~12小时

可针对每个角色单独设置。

登录会话的过期时间

6小时

1~24小时

全局设置,影响所有RAM用户和RAM角色。

会话有效时间取上述两个因素中的较小值 。例如:登录会话的过期时间设置为8小时,角色A的最大会话时间设置为1小时,则切换身份为角色A后,会话有效时间为1小时。会话过期后需要重新切换身份进行角色扮演。

OpenAPI

决定因素

默认值

取值范围

说明

角色最大会话时间

1小时

1~12小时

可针对每个角色单独设置。

DurationSeconds 参数

3600秒(1小时)

900秒(15分钟)~角色最大会话时间

调用 AssumeRole* 相关接口时传入。

SAML响应/OIDC Token有效时间

由IdP决定(通常为1小时)

由IdP决定

仅角色SSO场景,通过 AssumeRoleWithSAML/AssumeRoleWithOIDC 接口获取 STS Token 时使用。

会话有效时间取上述相关因素中的较小值 。会话过期后需要重新调用AssumeRole*接口进行角色扮演。

如需了解如何设置角色最大会话时间登录会话的过期时间,请参见设置RAM角色最大会话时间管理RAM用户安全设置

扮演RAM角色的操作方式

您可以根据实际场景选择合适的方式扮演RAM角色:

  • 控制台切换身份:在控制台临时切换到RAM角色执行操作。

  • API调用:程序或服务获取临时安全凭证(STS Token)访问阿里云资源。

  • CLI命令:通过命令行工具以RAM角色身份执行操作。

切换身份为RAM角色(控制台)

使用RAM用户或通过角色SSO登录控制台后,可以通过切换身份的方式扮演RAM角色。

角色扮演所需权限

  • RAM用户登录

    为RAM用户分配系统策略 AliyunSTSAssumeRoleAccess或包含权限操作sts:AssumeRole的自定义策略。具体授权操作,请参见为RAM用户授权

    说明

    该系统策略(AliyunSTSAssumeRoleAccess)允许RAM用户扮演所有RAM角色。

  • 角色SSO登录

    通过角色SSO登录时,您已经以RAM角色身份登录。如需切换身份到其他角色,必须确保当前角色具有扮演目标角色的权限。为当前角色分配系统策略 AliyunSTSAssumeRoleAccess或包含权限操作sts:AssumeRole的自定义策略。例如:假设角色SSO登录后的身份是角色A,如果用户需要切换身份为角色B,那么就需要确保角色A具备身份权限策略,以允许扮演角色B。

操作步骤

  1. 使用RAM用户或角色SSO登录RAM控制台

  2. 将鼠标悬停在右上角头像的位置,单击切换身份

    Snipaste_2025-12-12_10-24-09

    切换身份

  3. 角色切换页面,输入要扮演的RAM角色信息。

    • 企业别名/默认域名/主账号UID:RAM角色所属的企业别名(账号别名)、默认域名或归属的阿里云账号(主账号)ID,三者任选其一。如需跨账号切换,填写目标账号的阿里云账号ID。

    • 角色名:要扮演的RAM角色名称。向管理员咨询,或在RAM控制台身份管理 > 角色页面查看。

  4. 单击提交

    身份切换成功后,您将以RAM角色身份操作控制台。控制台右上角头像位置将显示当前身份和登录身份(原身份)。

    角色切换成功

    登录身份和当前身份的显示格式如下表所示:

    登录场景

    登录身份

    当前身份

    RAM用户登录

    <RAM用户名>

    <RoleName>/<RAM用户名>

    角色SSO登录(首次)

    不显示

    <RoleName>/<RoleSessionName>

    角色SSO登录后切换身份

    <SSO角色名>/<RoleSessionName>

    <切换后角色名>/<RoleSessionName>

    字段说明

    • RoleName:当前扮演的角色名称。

    • RoleSessionName:会话名称。RAM用户登录时为RAM用户名;角色SSO登录时由IdP提供,切换身份后保持不变。

    示例

    用户Tom(UPN:tom@example.local)通过角色SSO以角色 test-saml-role1 登录控制台,然后切换身份为角色 alice-testrole。假设RoleSessionName为用户的UPN。则登录身份与当前身份分别为:

    • 登录身份:test-saml-role1/tom@example.local

    • 当前身份:alice-testrole/tom@example.local

  5. (可选)切换回原身份。将鼠标悬停在控制台右上角头像位置,单击返回登录身份。切换后,RAM角色的权限将失效,原身份的权限将恢复。

说明

如管理员针对目标角色设置了特殊条件规则(sts:ExternalIdsts:SourceIdentity),或目标角色仅信任某些特定实体身份(如特定RAM用户)时,身份切换可能失败。

如遇到身份切换失败问题,您需要检查原身份被授予的权限策略,以及目标角色的信任策略。

通过API扮演RAM角色

您可以通过调用STS服务的API来扮演RAM角色,并获取所扮演角色的临时安全凭证(STS Token)。当程序或服务随后通过获取的STS Token访问阿里云资源时,将可执行所扮演角色权限范围内的操作。

角色扮演API

API

说明

AssumeRole

获取扮演RAM角色的临时安全凭证,适用于使用AccessKey或STS Token等凭证进行角色扮演的场景。

AssumeRoleWithSAML

通过SAML断言获取临时安全凭证,适用于SAML 角色SSO场景。

AssumeRoleWithOIDC

通过OIDC Token获取临时安全凭证,适用于OIDC 角色SSO场景。

在调用上述API时,您需要通过 RoleArn 参数明确指定希望扮演的RAM角色(Arn格式为 acs:ram::<主账号ID>:role/<角色名称>)。

此外,您还可以通过传递 Policy 参数(会话策略),在本次角色会话中对所扮演角色的权限做进一步限制。

调用API所需权限

通过不同API进行角色扮演,所需要的权限不同:

  • 如果使用 AssumeRole 接口,调用者必须被授予 sts:AssumeRole 操作权限(如附加 AliyunSTSAssumeRoleAccess 系统策略)。

  • 如果使用 AssumeRoleWithSAML 或 AssumeRoleWithOIDC 接口,只需在目标RAM角色的信任策略中正确配置受信任的SAML或OIDC身份提供商,无需为外部身份单独分配RAM身份权限策略。

您可以使用阿里云SDK调用AssumeRole相关接口扮演RAM角色,关于具体示例代码,请参见相关SDK文档,如:使用AK及RamRoleArn获取STS Token(Python SDK)

说明

如管理员针对目标角色设置了特殊条件规则(sts:ExternalIdsts:SourceIdentity),或目标角色仅信任某些特定实体身份(如特定RAM用户)时,通过API的角色扮演可能失败。

如遇到API调用返回权限不足相关问题,您需要检查原身份被授予的权限策略,以及目标角色的信任策略。

使用CLI扮演RAM角色

假设您希望通过CLI扮演RAM角色admin-role,来完成相关管理任务。操作步骤如下:

  1. 为阿里云CLI配置身份凭证。这里使用RamRoleArn模式为例,也即通过RAM用户的AccessKey作为身份认证方式来完成角色扮演。

    aliyun configure --profile RamRoleArnProfile --mode RamRoleArn
  2. 按照提示输入AccessKey ID,AccessKey Secret,要扮演的角色Arn,角色会话名等信息。具体参数说明和用法请参考阿里云CLI凭证配置

    Configuring profile 'RamRoleArnProfile' in 'RamRoleArn' authenticate mode...
    Access Key Id []: <yourAccessKeyID>
    Access Key Secret []: <yourAccessKeySecret>
    Sts Region []: cn-shanghai
    Ram Role Arn []: acs:ram::012345678910****:role/admin-role
    Role Session Name []: user-name
    External ID []: abcd1234
    Expired Seconds [900]: 900
    Default Region Id []: cn-shanghai
    Default Output Format [json]: json (Only support json)
    Default Language [zh|en] en: en
    Saving profile[RamRoleArnProfile] ...Done.
  3. 完成认证后,执行具体命令。此时执行命令所使用的身份为所扮演的目标RAM角色,而非持有AccessKey的RAM用户。

    aliyun ram ListUsers --profile RamRoleArnProfile

详细操作步骤,请参见为程序或服务创建AccessKey并使用

跨账号角色扮演

跨账号角色扮演允许您以一个阿里云账号下的身份(RAM用户或RAM角色),扮演另一个阿里云账号下的RAM角色,从而访问该账号下的资源。

实现跨账号角色扮演需要满足以下条件:

  • 目标角色需要信任源账号或源账号下的RAM用户、RAM角色(在目标角色的信任策略中通过Principal关键字定义)。

  • 原身份具有 sts:AssumeRole 操作权限。

更多信息,请参见跨阿里云账号访问资源

角色链

角色链指的是 RAM 身份(或角色SSO)成功扮演一个角色后,继续以这个角色的身份扮演其他角色的过程。

要使得角色A可以继续扮演角色B,角色A必须被授予sts:AssumeRole操作权限,且角色B必须信任角色A。

下面使用CLI演示如何使用角色链:

  1. 按照上述使用CLI扮演RAM角色案例配置CLI并扮演角色admin-role(源角色)。

  2. 为角色admin-role添加系统策略AliyunSTSAssumeRoleAccess

  3. 创建目标RAM角色,例如名称为target-role。修改目标角色的信任策略,在Principal关键字中指定身份为admin-role

    {
      "Statement": [
        {
          "Action": "sts:AssumeRole",
          "Effect": "Allow",
          "Principal": {
            "RAM": [
              "acs:ram::<ACCOUNT_ID>:role/admin-role"
            ]
          }
        }
      ],
      "Version": "1"
    }
  4. 使用ChainableProfile模式来配置阿里云CLI。

    aliyun configure --profile ChainableProfile --mode ChainableRamRoleArn
  5. 按照提示输入源配置(Source Profile)名,希望继续扮演的角色Arn等信息。

    Configuring profile 'ChainableProfile' in 'ChainableRamRoleArn' authenticate mode...
    Source Profile []: RamRoleArnProfile
    Sts Region []: cn-shanghai
    Ram Role Arn []: acs:ram::012345678910****:role/target-role
    Role Session Name []: user-name
    External ID []: abcd1234
    Expired Seconds [900]: 900
    Default Region Id []: cn-shanghai
    Default Output Format [json]: json (Only support json)
    Default Language [zh|en] zh: en
    Saving profile[ChainableProfile] ...Done.
  6. 完成认证后,执行如下命令来查看当前调用者的身份信息。返回结果中将包含目标角色Arn。

    aliyun sts GetCallerIdentity

    您现在可以使用角色链中目标角色的身份执行CLI命令。

说明

在使用角色链的场景下,通过审计日志追溯初始角色调用者身份信息将变得困难。此时,建议用SourceIdentity实现角色扮演溯源与权限控制

常见问题

如何限制用户只能扮演某些特定RAM角色

系统权限策略AliyunSTSAssumeRoleAccess允许扮演所有RAM角色。如您需要限制扮演指定RAM角色,需要为原身份配置自定义权限策略并修改目标角色的信任策略。更多内容,请参见如何限制指定RAM用户扮演指定RAM角色

阿里云主账号是否可以扮演RAM角色

不可以。阿里云账号(主账号)无法通过控制台切换身份为RAM角色,也无法通过调用AssumeRole接口扮演RAM角色。

如果通过角色扮演获取的STS Token发生泄露该如何处理

如果您通过扮演角色获取的STS Token发生泄露,您可以回收所有已经颁发的STS Token。具体操作,请参见STS Token发生泄露时如何处理

相关文档