RAM用户调用AssumeRole接口获取一个扮演RAM角色的临时身份凭证（STS Token）。该接口中RAM用户扮演的是可信实体为阿里云账号类型的RAM角色。

使用限制

  • 本接口仅限具有STS角色扮演权限的RAM用户使用。没有权限时会报错，报错信息如下：
    You are not authorized to do this action. You should be authorized by RAM.

    问题原因和解决方法如下：

  • 本接口调用次数限制：每分钟最多调用6000次，且一个阿里云账号及该账号下的RAM用户、RAM角色共用这6000次。
    当请求量超过6000次时，超出部分会报错，报错信息如下：
    Request was denied due to user flow control.

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 AssumeRole 要执行的操作。取值：AssumeRole
RoleArn String 是 acs:ram::123456789012****:role/adminrole 要扮演的RAM角色ARN。

该角色是可信实体为阿里云账号类型的RAM角色。更多信息，请参见创建可信实体为阿里云账号的RAM角色或CreateRole。

格式：acs:ram::$accountID:role/$roleName 。

说明 您可以通过RAM控制台或API查看角色ARN。具体如下：
RoleSessionName String 是 alice

角色会话名称。

该参数为用户自定义参数。通常设置为调用该API的用户身份，例如：用户名。在操作审计日志中，即使是同一个RAM角色执行的操作，也可以根据不同的RoleSessionName来区分实际操作者，以实现用户级别的访问审计。

长度为2~64个字符，可包含英文字母、数字、半角句号（.）、at（@）、短划线（-）和下划线（_）。
Policy String 否 {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
为STS Token额外添加的一个权限策略，进一步限制STS Token的权限。具体如下：
  • 如果指定该权限策略，则STS Token最终的权限策略取RAM角色权限策略与该权限策略的交集。
  • 如果不指定该权限策略，则STS Token最终的权限策略取RAM角色的权限策略。

长度为1~1024个字符。
DurationSeconds Long 否 3600

过期时间。单位：秒。

过期时间最小值为900秒，最大值为要扮演角色的MaxSessionDuration时间。默认值为3600秒。

说明 您可以通过CreateRole或UpdateRole接口设置角色最大会话时间MaxSessionDuration。详情请参见CreateRole或UpdateRole。

返回数据

名称 类型 示例值 描述
RequestId String 6894B13B-6D71-4EF5-88FA-F32781734A7F 请求ID。
Credentials 访问凭证。
└AccessKeyId String STS.L4aBSCSJVMuKg5U1**** 访问密钥ID。
└AccessKeySecret String wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK**** 访问密钥。
└SecurityToken String ******** 安全令牌。
└Expiration String 2015-04-09T11:52:19Z 失效时间。
AssumedRoleUser 角色扮演时的临时身份。
└Arn String acs:ram::123456789012****:role/adminrole/alice 临时身份的ARN。
└AssumedRoleId String 34458433936495****:alice 临时身份的ID。

示例

请求示例

https://sts.aliyuncs.com/?Action=AssumeRole
&RoleArn=acs:ram::123456789012****:role/adminrole
&RoleSessionName=alice
&DurationSeconds=3600
&<公共请求参数>
说明 关于公共请求参数的详情，请参见公共参数。

正常返回示例

XML格式 

<AssumeRoleResponse>
    <RequestId>6894B13B-6D71-4EF5-88FA-F32781734A7F</RequestId>
    <AssumedRoleUser>
        <Arn>acs:ram::123456789012****:role/adminrole/alice</arn>
        <AssumedRoleId>34458433936495****:alice</AssumedRoleId>
    </AssumedRoleUser>
    <Credentials>
        <AccessKeyId>STS.L4aBSCSJVMuKg5U1****</AccessKeyId>
        <AccessKeySecret>wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****</AccessKeySecret>
        <SecurityToken>********</SecurityToken>
        <Expiration>2015-04-09T11:52:19Z</Expiration>
    </Credentials>
</AssumeRoleResponse>

JSON格式 

{
    "Credentials": {
        "AccessKeyId": "STS.L4aBSCSJVMuKg5U1****",
        "AccessKeySecret": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****",
        "Expiration": "2015-04-09T11:52:19Z",
        "SecurityToken": "********"
    },
    "AssumedRoleUser": {
        "Arn": "acs:ram::123456789012****:role/adminrole/alice",
        "AssumedRoleId":"34458433936495****:alice"
        },
    "RequestId": "6894B13B-6D71-4EF5-88FA-F32781734A7F"
}

错误码

HttpCode 错误码 错误信息 描述
400 InvalidParameter The parameter RoleArn is wrongly formed. 角色ARN格式错误。
400 InvalidParameter.RoleArn The parameter RoleArn is wrongly formed. 角色ARN格式错误。
400 InvalidParameter.RoleSessionName The parameter RoleSessionName is wrongly formed. RoleSessionName格式错误，支持输入2~64个字符，请输入至少2个字符，允许输入英文字母、数字、半角句号（.）、at（@）、短划线（-）和下划线（_）。
400 InvalidParameter.DurationSeconds The Min/Max value of DurationSeconds is 15min/1hr. DurationSeconds参数设置错误，过期时间最小值为900秒，最大值为MaxSessionDuration设置的时间。
400 InvalidParameter.PolicyGrammar The parameter Policy has not passed grammar check. 权限策略语法错误。
400 InvalidParameter.PolicySize The size of Policy must be smaller than 1024 bytes. 权限策略长度超限，最大不超过1024字符。
403 NoPermission You are not authorized to do this action. You should be authorized by RAM. STS Token没有权限。解决方法请参见为什么使用STS时会报错。
404 EntityNotExist.Role The specified Role not exists. 指定的RAM角色不存在。
500 InternalError STS Server Internal Error happened. 服务器内部错误。

后续步骤

获得扮演RAM角色的STS Token后，RAM用户便可以使用STS Token，开始以RAM角色身份访问阿里云资源。