All Products
Search
Document Center

Resource Access Management:AssumeRole

Last Updated:Jul 25, 2024

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:

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.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • 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 Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • 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.
OperationAccess levelResource typeCondition keyAssociated operation
sts:AssumeRoleget
  • Role
    acs:ram::{#accountId}:role/{#RoleName}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DurationSecondslongNo

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 .

3600
PolicystringNo

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 2,048 characters in length.

For more information about policy elements and sample policies, see Policy elements and Overview of sample policies.

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

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. The following items describe the validity periods of storage addresses:

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

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 RoleSessionName to identify API callers that assume the same RAM role in ActionTrail logs. This allows you to track the users that perform the operations.

The value must be 2 to 64 characters in length and can contain letters, digits, and the following special characters: . @ - _.

alice
ExternalIdstringNo

The external ID of the RAM role.

This parameter is provided by an external party and is used to prevent the confused deputy problem. For more information, see Use ExternalId to prevent the confused deputy problem.

The value must be 2 to 1,224 characters in length and can contain letters, digits, and the following special characters: = , . @ : / - _. The regular expression for this parameter is [\w+=,.@:\/-]*.

abcd1234

For more information about common request parameters, see Common parameters.

Response parameters

ParameterTypeDescriptionExample
object

The response parameters.

RequestIdstring

The ID of the request.

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

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

AssumedRoleIdstring

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

34458433936495****:alice
Arnstring

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

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

The STS credentials.

SecurityTokenstring

The STS token.

Note Alibaba Cloud STS does not impose limits on the length of STS tokens. We strongly recommend that you do not specify a maximum length for STS tokens.
********
Expirationstring

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

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

The AccessKey secret.

wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****
AccessKeyIdstring

The AccessKey ID.

STS.L4aBSCSJVMuKg5U1****

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError message
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 2048 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.
500InternalErrorSTS Server Internal Error happened, please send the RequestId to us.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2022-09-27The Error code has changedView Change Details