首页 >访问控制 >API参考 >API参考(STS) >API目录 >角色扮演 >AssumeRole - 获取扮演角色的临时身份凭证

AssumeRole - 获取扮演角色的临时身份凭证

调用AssumeRole获取一个扮演RAM角色的临时身份凭证(STS Token)。

前提条件

请确保已为调用者(RAM用户或RAM角色)授予STS的管理权限(AliyunSTSAssumeRoleAccess)。

否则,会报如下错误:

You are not authorized to do this action. You should be authorized by RAM.

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

最佳实践

STS Token自颁发后将在一段时间内有效,建议您设置合理的Token有效期,并在有效期内重复使用,以避免业务请求速率上升后,STS Token颁发的速率限制影响到业务。具体速率限制,请参见STS服务调用次数是否有上限。您可以通过请求参数DurationSeconds设置Token有效期。

在移动端上传或下载OSS文件等场景下,其访问量较大,即使重复使用STS Token也可能无法满足限流要求。为避免STS的限流成为OSS访问量的瓶颈,您可以尝试OSS的在URL中包含签名的方案。更多信息,请参见在URL中包含签名服务端签名后直传

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

当前API暂无授权信息透出。

请求参数

名称类型必填描述示例值
DurationSecondsinteger

Token有效期。单位:秒。

Token有效期最小值为900秒,最大值为要扮演角色的MaxSessionDuration时间。默认值为3600秒。

您可以通过CreateRole或UpdateRole设置角色最大会话时间MaxSessionDuration。更多信息,请参见CreateRoleUpdateRole

3600
Policystring

为STS Token额外添加的一个权限策略,进一步限制STS Token的权限。具体如下:

  • 如果指定该权限策略,则STS Token最终的权限策略取RAM角色权限策略与该权限策略的交集。
  • 如果不指定该权限策略,则STS Token最终的权限策略取RAM角色的权限策略。

长度为1~1024个字符。

{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
RoleArnstring

要扮演的RAM角色ARN。

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

格式:acs:ram::<account_id>:role/<role_name>

您可以通过RAM控制台或API查看角色ARN。具体如下:

acs:ram::123456789012****:role/adminrole
RoleSessionNamestring

角色会话名称。

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

长度为2~64个字符,可包含英文字母、数字、半角句号(.)、at(@)、短划线(-)和下划线(_)。

alice

返回参数

名称类型描述示例值
object

返回参数。

RequestIdstring

请求ID。

6894B13B-6D71-4EF5-88FA-F32781734A7F
AssumedRoleUserobject

角色扮演时的临时身份。

AssumedRoleIdstring

临时身份的ID。

34458433936495****:alice
Arnstring

临时身份的ARN。

acs:ram::123456789012****:role/adminrole/alice
Credentialsobject

访问凭证。

SecurityTokenstring

安全令牌。

********
Expirationstring

Token到期失效时间(UTC时间)。

2015-04-09T11:52:19Z
AccessKeySecretstring

访问密钥。

wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****
AccessKeyIdstring

访问密钥ID。

STS.L4aBSCSJVMuKg5U1****

示例

请求示例

https://sts.aliyuncs.com/?Action=AssumeRole
&DurationSeconds=3600
&RoleArn=acs:ram::123456789012****:role/adminrole
&RoleSessionName=alice
&公共请求参数

正常返回示例

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"
}

XML格式

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

错误码

HttpCode错误码错误信息
400InvalidParameter.DurationSecondsThe Min/Max value of DurationSeconds is 15min/1hr.
400InvalidParameter.ExternalIdThe parameter ExternalId is wrongly formed.
400InvalidParameter.RoleArnThe parameter RoleArn is wrongly formed.
400InvalidParameter.RoleSessionNameThe parameter RoleSessionName is wrongly formed.
400InvalidParameter.SerialNumberThe parameter SerialNumber is wrongly formed.
400InvalidParameter.TokenCodeThe parameter TokenCode is wrongly formed.
400InvalidParameter.PolicyGrammarThe parameter Policy has not passed grammar check.
400InvalidParameter.PolicySizeThe size of Policy must be smaller than 1024 bytes.
400InvalidParameter.ContentTypeThe ContentType request header must be either "application/json" or "application/x-www-form-urlencoded".
403NoPermissionYou are not authorized to do this action. You should be authorized by RAM.
403AuthenticationFail.ApiUsernameThe specified api username is not legal.
403AuthenticationFail.ApiPasswordThe specified api password is not legal.
403NoPermissionNo permission perform sts:AssumeRole on this Role. Maybe you are not authorized to perform sts:AssumeRole or the specified role does not trust you
403NoPermissionRoles may not be assumed by root accounts.
404EntityNotExist.RoleThe specified Role not exists .
500InternalErrorSTS Server Internal Error happened, please send the RequestId to us.

访问错误中心查看更多错误码。

阿里云首页 访问控制 相关技术圈