DocsICP FilingConsole
Documentation

AssumeRole

Updated at:
Copy as MD
Product
My Favorites

Obtains a temporary identity credential (STS token) to assume a RAM role.

Operation description

Common scenarios

  • Temporary access authorization: Typically, invoke API operations from the server side to prevent access key leaks. However, in some file upload scenarios, it is better to use direct client-side uploads to avoid the overhead of server-side forwarding. In this case, the server can issue a temporary security token (STS token), and the client can use the STS token to directly upload resources. For more information, see Use temporary security tokens for mobile applications to access Alibaba Cloud.

  • Cross-account access: If you have multiple Alibaba Cloud accounts, such as Account A and Account B, and you want Account B to access specific resources of Account A. In this case, you can create a RAM role in Account A with Account B as the trusted entity, and grant authorization to a Resource Access Management (RAM) user or RAM role in Account B to assume the role. Then, the RAM user or RAM role in Account B can access the specific resources of Account A by assuming the role. For more information, see Access resources across Alibaba Cloud accounts.

Before you begin

You cannot invoke this operation by using an Alibaba Cloud account. You can only invoke this operation as a RAM user or a RAM role. Make sure that the caller (the RAM user or RAM role) is granted the authorization for STS role assumption (AliyunSTSAssumeRoleAccess).

Otherwise, the following error is returned:

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

Causes and solutions:

Best practices

An STS token is valid for a specified period after it is issued. We recommend that you set a reasonable token validity period and reuse the token within the validity period. This prevents the rate limit on STS token issuance from affecting your business when the request rate increases. For more information about the rate limit, see Is there a limit on how many times you can invoke the STS service?. You can set the token validity period by using the DurationSeconds request parameter.

In scenarios such as uploading or downloading OSS files from mobile clients, the access volume is large. Even if you reuse STS tokens, the throttling requirements may not be met. To prevent STS throttling from becoming a bottleneck for OSS access, try the OSS solution of including a signature in a URL. For more information, see Include a signature in a URL and Server-side signing and direct upload.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

sts:AssumeRole

get

*Role

acs:ram::{#accountId}:role/{#RoleName}
  • sts:SourceIdentity
  • sts:SetSourceIdentity

Request parameters

Parameter

Type

Required

Description

Example
DurationSeconds

integer

No

The validity period of the token. Unit: seconds.

The minimum validity period is 900 seconds, and the maximum validity period is the MaxSessionDuration value of the RAM role to be assumed. Default value: 3600.

You can set the MaxSessionDuration parameter by calling the CreateRole or UpdateRole operation. For more information, see CreateRole or UpdateRole.

3600
Policy

string

No

The additional access policy attached to the STS token to further restrict the permissions of the STS token. Details:

  • If this access policy is specified, the final access policy of the STS token is the intersection of the RAM role access policy and this access policy.

  • If this access policy is not specified, the final access policy of the STS token is the RAM role access policy.

The value must be 1 to 2,048 characters in length.

For more information about access policy elements and examples, see Basic elements of a access policy and Access policy examples.

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

string

Yes

The ARN of the RAM role to be assumed.

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 of the RAM role in the RAM console or by calling an API operation. Details:

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

string

Yes

The name of the role session.

This parameter is user-defined. Typically, set this parameter to the identity of the user who calls the API operation, such as the username. In ActionTrail logs, even if the operations are performed by the same RAM role, you can identify the actual operator based on the RoleSessionName to implement user-level access auditing.

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

alice
ExternalId

string

No

The external ID of the role.

This parameter is provided by an external party to identify the role. The main purpose is 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: =,.@:/-_. Regular expression: [\w+=,.@:\/-]*.

abcd1234
SourceIdentity

string

No

The source identity.

When you assume a role, you can specify the source identity of the caller as the initial identity of the session. The source identity persists throughout the chained sessions of role assumption and cannot be changed. This ensures the traceability and security of operations.

The value of SourceIdentity must be 2 to 64 characters in length and can contain letters, digits, and the following special characters: =,.@-_. Regular expression: [\w+=,.@-]*. You cannot use values that start with acs:, aliyun:, or alibabacloud:. These prefixes are reserved for internal use by Alibaba Cloud.

Alice

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

Response elements

Element

Type

Description

Example

object

The response parameters.

RequestId

string

The request ID.

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

object

The temporary identity used for role assumption.

AssumedRoleId

string

The ID of the temporary identity.

34458433936495****:alice
Arn

string

The ARN of the temporary identity.

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

object

The access credential.

SecurityToken

string

The security token.

Note

The length of the security token is not fixed. Do not limit the maximum length of the security token.

********
Expiration

string

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

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

string

The AccessKey secret.

wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pK****
AccessKeyId

string

The AccessKey ID.

STS.L4aBSCSJVMuKg5U1****
SourceIdentity

string

The source identity.

When you assume a role, you can specify the source identity of the caller as the initial identity of the session. The source identity persists throughout the chained sessions of role assumption and cannot be changed. This ensures the traceability and security of operations.

If the source identity is not specified, this field is not returned.

Alice

Examples

Success response

JSON format

{
  "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****"
  },
  "SourceIdentity": "Alice"
}

Error codes

HTTP status code

Error code

Error message

Description
400 InvalidParameter.DurationSeconds The Min/Max value of DurationSeconds is 15min/1hr. DurationSeconds parameter is illegal, DurationSeconds minimum value is 15 minutes, maximum value is 1 hour
400 InvalidParameter.ExternalId The parameter ExternalId is wrongly formed. Parameters
400 InvalidParameter.RoleArn The parameter RoleArn is wrongly formed. Parameters
400 InvalidParameter.RoleSessionName The parameter RoleSessionName is wrongly formed. The format of the RoleSessionName parameter is invalid.
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. Parameter Policy syntax format check failed
400 InvalidParameter.PolicySize The size of Policy must be smaller than 2048 bytes. The policy parameter is invalid. The policy length must be less than 2048 bytes.
400 InvalidParameter.ContentType The ContentType request header must be either "application/json" or "application/x-www-form-urlencoded".
500 InternalError STS Server Internal Error happened, please send the RequestId to us. STS server internal exception
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.
404 EntityNotExist.Role The specified Role not exists .

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.