Obtains a temporary identity to assume a RAM role. This topic takes a RAM role whose trusted entity is an Alibaba Cloud account as an example.

Note

STS supports up to 100 AssumeRole API requests for each Alibaba Cloud account. API requests that are sent by using RAM users and RAM roles that belong to the Alibaba Cloud account are also counted. If the number of API requests reaches 100, the following error message is returned: 

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 this parameter to AssumeRole.
RoleArn String Yes acs:ram::123456789012****:role/adminrole The Alibaba Cloud Resource Name (ARN) of the RAM role. Format: acs:ram::$accountID:role/$roleName.
Note
  • $accountID: specifies the ID of the Alibaba Cloud account that owns the RAM role. To view the account ID, log on to the Alibaba Cloud console, move your pointer over your profile picture in the upper-right corner, and then click Security Settings.
  • $roleName: specifies the name of the RAM role. To view the RAM role name, perform the following steps: Log on to the RAM console. In the left-side navigation pane, click RAM Roles. In the RAM Role Name column on the page that appears, you can view the name of the RAM role.
RoleSessionName String Yes alice

The customized role session name. This parameter can be used to identify the RAM user who assumes the RAM role.

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

Policy String No {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}

The policy that specifies the permissions of the returned STS token.

You can use this parameter to grant the STS token fewer permissions than those granted to the RAM role. If you do not specify this parameter, the returned STS token has all permissions of the RAM role.

The value must be 1 to 1,024 characters in length.
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.

Note You can call the CreateRole or UpdateRole operation to set 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****:assumed-role/AdminRole/alice The ARN of the RAM role. Format: acs:ram::$accountID:role/$roleName.
Note
  • $accountID: indicates the ID of the Alibaba Cloud account that owns the RAM role. To view the account ID, log on to the Alibaba Cloud console, move your pointer over your profile picture in the upper-right corner, and then click Security Settings.
  • $roleName: indicates the name of the RAM role. To view the RAM role name, perform the following steps: Log on to the RAM console. In the left-side navigation pane, click RAM Roles. In the RAM Role Name column on the page that appears, you can view the name of the RAM role.
└AssumedRoleUserId String 34458433936495****:alice The ID of the temporary identity that you use to assume the role.

Examples

Sample requests

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

Sample success responses

XML format 

<AssumeRoleResponse>
    <RequestId>6894B13B-6D71-4EF5-88FA-F32781734A7F</RequestId>
    <AssumedRoleUser>
        <arn>acs:ram::123456789012****:assumed-role/AdminRole/alice</arn>
        <AssumedRoleUserId>34458433936495****:alice</AssumedRoleUserId>
    </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****:assumed-role/AdminRole/alice",
        "AssumedRoleUserId":"34458433936495****:alice"
        },
    "RequestId": "6894B13B-6D71-4EF5-88FA-F32781734A7F"
}

Error codes

HttpCode 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 32 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 value cannot be greater than the value of the MaxSessionDuration parameter.
400 InvalidParameter.PolicyGrammar The parameter Policy has not passed grammar check. The error message returned because the policy syntax 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 bytes 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.
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 server error has occurred.