Obtains a Security Token Service (STS) token to assume a RAM role. In this example, an Alibaba Cloud account is used as the trusted entity of the RAM role.

Limits

  • This operation is available only to a RAM user that is allowed to assume a RAM role by using an STS token. If the RAM user is not allowed to assume a RAM role by using an STS token, 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:

    • Cause of the error: The policy that is required to assume a RAM role is not attached to the RAM user. To resolve this issue, attach the AliyunSTSAssumeRoleAccess policy or a custom policy to the RAM user. For more information, see Grant permissions to a RAM user and Can I specify the RAM role that a RAM user can assume?.
    • Cause of the error: The RAM user that you use is not added to the trust policy of the RAM role. In other words, the RAM user does not have the permissions to assume the RAM role. To resolve this issue, add the RAM user to the Principal element in the trust policy of the RAM role. For more information, see Edit the trust policy of a RAM role.
  • STS allows each Alibaba Cloud account to send up to 6,000 AssumeRole requests per minute. API requests that are sent by using RAM users and RAM roles that belong to the Alibaba Cloud account are also counted.
    If an Alibaba Cloud account sends more than 6,000 AssumeRole requests within a minute, the following error message is returned for the excessive requests:
    Request was denied due to user flow control.

Request parameters

Parameter Type Required Example Description
Action String Yes AssumeRole The operation that you want to perform. Set the value to AssumeRole.
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::$accountID:role/$roleName.

Note You can view the ARN in the RAM console or by calling operations.
RoleSessionName String Yes alice

The custom name of the role session.

In most cases, this parameter is set to the identity of the user who calls the operation, for example, the 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 (_).

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.

DurationSeconds Long No 3600

The validity period. Unit: seconds.

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

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

Response parameters

Parameter Type Example Description
RequestId String 6894B13B-6D71-4EF5-88FA-F32781734A7F The ID of the request.
Credentials The access credentials.
AccessKeyId String STS.L4aBSCSJVMuKg5U1**** The AccessKey ID.
AccessKeySecret String wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK**** The AccessKey secret.
SecurityToken String ******** The STS token.
Expiration String 2015-04-09T11:52:19Z The time when the STS token expires.
AssumedRoleUser 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.
AssumedRoleId String 34458433936495****:alice The ID of the temporary identity that you use to assume the RAM role.

Examples

Sample requests

https://sts.aliyuncs.com/?Action=AssumeRole
&RoleArn=acs:ram::123456789012****:role/adminrole
&RoleSessionName=alice
&DurationSeconds=3600
&Common request parameters
Note For more information about common request parameters, see Common parameters.

Sample success responses

XML format

<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 format

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

HTTP status code Error code Error message Description
400 InvalidParameter The parameter RoleArn is wrongly formed. The error message returned because the ARN format of the RAM role is invalid.
400 InvalidParameter.RoleArn The parameter RoleArn is wrongly formed. The error message returned because the ARN format of the RAM role is invalid.
400 InvalidParameter.RoleSessionName The parameter RoleSessionName is wrongly formed. The error message returned because the format of the RoleSessionName parameter is invalid. The value must be 2 to 64 characters in length and can contain letters, digits, periods (.), at signs (@), hyphens (-), and underscores (_).
400 InvalidParameter.DurationSeconds The Min/Max value of DurationSeconds is 15min/1hr. The error message returned because the value of the DurationSeconds parameter is invalid. The minimum value is 900, and the maximum value is equal to the value of the MaxSessionDuration parameter.
400 InvalidParameter.PolicyGrammar The parameter Policy has not passed grammar check. The error message returned because the syntax of the policy is invalid.
400 InvalidParameter.PolicySize The size of Policy must be smaller than 1024 bytes. The error message returned because the length of the specified policy string exceeds the upper limit. The policy string can be up to 1,024 characters in length.
403 NoPermission You are not authorized to do this action. You should be authorized by RAM. The error message returned because the STS token does not have the required permissions. For more information about how to fix the error, see FAQ about RAM roles and STS tokens.
404 EntityNotExist.Role The specified Role not exists. The error message returned because the specified RAM role does not exist.
500 InternalError STS Server Internal Error happened. The error message returned because an internal error occurred in the server.

What to do next

After the STS token is obtained, the RAM user can use the STS token to assume the RAM role and access Alibaba Cloud resources.