Obtains a Security Token Service (STS) token to assume a Resource Access Management (RAM) role.

Prerequisites

The AliyunSTSAssumeRoleAccess policy is attached to the requester. You can use this policy to grant the requester the management permissions on STS. The requester can be a RAM user or RAM role.

If you do not attach the AliyunSTSAssumeRoleAccess policy to the requester, the following error message is returned:

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

You can refer to the following information to troubleshoot the error:

Best practices

An STS token is valid for a period of time after it is issued, and the number of STS tokens that can be issued within an interval is also limited. Therefore, we recommend that you configure a proper validity period for an STS token and repeatedly use the token within this period. This prevents frequent issuing of STS tokens from adversely affecting your services if a large number of requests are sent. For more information about the limit, see Is the number of STS API requests limited? You can configure the DurationSeconds parameter to specify a validity period for an STS token.

When you upload or download Object Storage Service (OSS) objects on mobile devices, a large number of STS API requests are sent. In this case, repeated use of an STS token may not meet your business requirements. To avoid the limit on STS API requests from affecting access to OSS, you can add a signature to the URL of an OSS object. For more information, see Add signatures to URLs and Obtain signature information from the server and upload data to OSS.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes AssumeRole

The operation that you want to perform. Set the value to AssumeRole.

DurationSeconds Long No 3600

The validity period of the STS token. Unit: seconds.

Minimum value: 900. Maximum value: the value of the MaxSessionDuration parameter. Default value: 3600.

You can call the CreateRole or UpdateRole operation to configure the MaxSessionDuration parameter. For more information, see CreateRole or UpdateRole.

Policy String No null

The policy that specifies the permissions of the returned STS token. You can use this parameter to grant the STS token fewer permissions than the permissions granted to the RAM role.

  • If you specify this parameter, the permissions of the returned STS token are the permissions that are included in the value of this parameter and owned by the RAM role.
  • If you do not specify this parameter, the returned STS token has all the permissions of the RAM role.

The value must be 1 to 1,024 characters in length.

RoleArn String Yes acs:ram::123456789012****:role/adminrole

The Alibaba Cloud Resource Name (ARN) of the RAM role.

The trusted entity of the RAM role is an Alibaba Cloud account. For more information, see Create a RAM role for a trusted Alibaba Cloud account or CreateRole.

Format: acs:ram::<account_id>:role/<role_name>.

You can view the ARN in the RAM console or by calling operations.

RoleSessionName String Yes alice

The custom name of the role session.

You can specify the value of this parameter based on your business requirements. In most cases, you can set this parameter to the identity of the user who calls the operation. For example, specify a username. In ActionTrail logs, you can distinguish the users who assume the same RAM role to perform operations based on the value of the RoleSessionName parameter. This way, you can perform user-specific auditing.

The value must be 2 to 64 characters in length and can contain letters, digits, periods (.), at signs (@), hyphens (-), and underscores (_).

Response parameters

Parameter Type Example Description
RequestId String 6894B13B-6D71-4EF5-88FA-F32781734A7F

The ID of the request.

AssumedRoleUser Object

The temporary identity that you use to assume the RAM role.

AssumedRoleId String 34458433936495****:alice

The ID of the temporary identity that you use to assume the RAM role.

Arn String acs:ram::123456789012****:role/adminrole/alice

The ARN of the temporary identity that you use to assume the RAM role.

Credentials Object

The access credentials.

SecurityToken String ********

The STS token.

Expiration String 2015-04-09T11:52:19Z

The time when the STS token expires. The time is displayed in UTC.

AccessKeySecret String wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****

The AccessKey secret.

AccessKeyId String STS.L4aBSCSJVMuKg5U1****

The AccessKey ID.

Examples

Sample requests

https://sts.aliyuncs.com/?Action=AssumeRole
&DurationSeconds=3600
&RoleArn=acs:ram::123456789012****:role/adminrole
&RoleSessionName=alice
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/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>

JSON format

HTTP/1.1 200 OK
Content-Type:application/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"
}

Error codes

For a list of error codes, visit the API Error Center.