Obtains a Security Token Service (STS) token to assume a Resource Access Management (RAM) role.
Operation Description
Prerequisites
You cannot use an Alibaba Cloud account to call this operation. The requester of this operation can only be a RAM user or RAM role. Make sure that the AliyunSTSAssumeRoleAccess policy is attached to the requester. After this policy is attached to the requester, the requester has the management permissions on STS.
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:
- Cause of the error: The policy that is required to assume a RAM role is not attached to the requester. To resolve this issue, attach the AliyunSTSAssumeRoleAccess policy or a custom policy to the requester. For more information, see Can I specify the RAM role that a RAM user can assume? and Grant permissions to a RAM user.
- Cause of the error: The requester is not authorized to assume the RAM role. To resolve this issue, add the requester to the Principal element in the trust policy of the RAM role For more information, see Edit the trust policy of a RAM role.
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.
Authorization information
The following table is the authorization information corresponding to the API, which can be found in the RAM permission policy statement.Action Used in the element to grant the RAM user or RAM role permission to call this API. The specific instructions are as follows:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All resourcesis used in the Resource type column of the operation.
- Condition keyword: refers to the condition keyword defined by the cloud product itself.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operate | access level | Resource type | conditional keyword | Association operation |
|---|---|---|---|---|
| sts:AssumeRole | Write |
|
| without |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| DurationSeconds | long | No | The validity period of the STS token. Unit: seconds. Minimum value: 900. Maximum value: the value of the You can call the CreateRole or UpdateRole operation to configure the | 3600 |
| Policy | string | No | 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.
The value must be 1 to 2,048 characters in length. | {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"} |
| RoleArn | string | Yes | 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: You can view the ARN in the RAM console or by calling operations.
| acs:ram::123456789012****:role/adminrole |
| RoleSessionName | string | Yes | The custom name of the role session. Set this parameter based on your business requirements. In most cases, you can set this parameter to the identity of the API caller. For example, you can specify a username. You can specify The value must be 2 to 64 characters in length and can contain letters, digits, periods (.), at signs (@), hyphens (-), and underscores (_). | alice |
Response parameters
Example
Normal return example
JSONFormat
{
"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"
}XMLFormat
<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>Error codes
| Http code | Error code | Error message |
|---|---|---|
| 400 | InvalidParameter.DurationSeconds | The Min/Max value of DurationSeconds is 15min/1hr. |
| 400 | InvalidParameter.ExternalId | The parameter ExternalId is wrongly formed. |
| 400 | InvalidParameter.RoleArn | The parameter RoleArn is wrongly formed. |
| 400 | InvalidParameter.RoleSessionName | The parameter RoleSessionName is wrongly formed. |
| 400 | InvalidParameter.SerialNumber | The parameter SerialNumber is wrongly formed. |
| 400 | InvalidParameter.TokenCode | The parameter TokenCode is wrongly formed. |
| 400 | InvalidParameter.PolicyGrammar | The parameter Policy has not passed grammar check. |
| 400 | InvalidParameter.PolicySize | The size of Policy must be smaller than 2048 bytes. |
| 400 | InvalidParameter.ContentType | The ContentType request header must be either "application/json" or "application/x-www-form-urlencoded". |
| 403 | NoPermission | You are not authorized to do this action. You should be authorized by RAM. |
| 403 | AuthenticationFail.ApiUsername | The specified api username is not legal. |
| 403 | AuthenticationFail.ApiPassword | The specified api password is not legal. |
| 403 | NoPermission | No permission perform sts:AssumeRole on this Role. Maybe you are not authorized to perform sts:AssumeRole or the specified role does not trust you |
| 403 | NoPermission | Roles may not be assumed by root accounts. |
| 404 | EntityNotExist.Role | The specified Role not exists . |
| 500 | InternalError | STS Server Internal Error happened, please send the RequestId to us. |
For a list of error codes, visit the API error center.
Change history
| Change time | Summary of changes | Operate | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2022-09-27 | The error codes of the API operation has changed | |||||||||||
|