Assume a RAM role - Resource Access Management - Alibaba Cloud Documentation Center

Assume a RAM role to temporarily obtain the permissions of the role for accessing Alibaba Cloud resources. You can assume a RAM role in the console, by using Alibaba Cloud CLI, or by calling the API operations of Security Token Service (STS).

What is role assumption

Unlike a RAM user, a RAM role cannot be used to log on to the console directly. You must first log on to the console as a RAM user or through SSO, and then switch to the target RAM role. This process is called role assumption.

When you switch identity in the console, the permissions of the original identity are temporarily suspended, and you operate with the permissions of the assumed RAM role instead. The assumed RAM role can belong to the same Alibaba Cloud account as the logged-on RAM user, or to a different account (cross-account role assumption).

How it works

The following example shows how role assumption works. In this example, RAM user Alice assumes the RAM role prod-role and accesses OSS as the role:

Request to assume the RAM role. RAM user Alice requests temporary credentials (an STS token) for the RAM role prod-role from Alibaba Cloud Security Token Service (STS). RAM verifies the identity of Alice (for example, by using an AccessKey pair), whether Alice has the permission to assume the role (sts:AssumeRole), and whether the trust policy of prod-role allows Alice to assume it (whether Principal matches Alice).
Get the STS token. After the verification passes, Alice gets the STS token returned by STS.
Access cloud resources as the role. Alice uses the STS token to access cloud resources such as OSS as the prod-role role. These requests are evaluated against the access policies of the prod-role role (for example, oss:*). The original credentials of Alice remain valid; only the requests made with the STS token use the permissions of the role.

Methods of role assumption

You can assume a RAM role in the following ways:

Switch identity in the console — After a RAM user logs on to the Alibaba Cloud Management Console, the user uses the Switch Identity feature to switch to the target role. This method is described in detail in this topic.
Call API operations — Administrators or developers use Alibaba Cloud CLI, SDK, or OpenAPI to call the AssumeRole operation (or other role assumption operations, such as AssumeRoleWithSAML) to obtain the STS token. This method is described in detail in this topic.
Role-based SSO — Users log on to the console through role-based SSO (based on the SAML 2.0 protocol) by using the identity provider (IdP) of their enterprise. When the console logon is completed, the user has already assumed the RAM role.
Bind the role to Alibaba Cloud resources — Bind or associate the role with specific Alibaba Cloud resources (such as an ECS instance, Function Compute, or an ACK/ACS Pod), and then use the built-in features of the Alibaba Cloud platform to complete role assumption. For more information, see Applications on Alibaba Cloud accessing Alibaba Cloud resources.
The last two scenarios are not described in detail in this topic. For usage instructions, see the referenced documents above.

How to assume a RAM role

Choose a method based on your scenario. For all available role assumption methods, see Methods of role assumption.

Manual operations in the console — Switch to the RAM role in the console to perform operations interactively.
Automation for programs or services — Call the operations of STS to obtain the STS token, and then use the token to access Alibaba Cloud resources programmatically.
Interactive operations on the command line — Use Alibaba Cloud CLI to perform operations as the RAM role.

Prerequisites

Before you assume a RAM role, make sure that the following requirements are met:

Target RAM role — The target RAM role is available, and its trust policy allows the original identity to assume the role. For example, the Principal keyword in the trust policy matches the original identity.
Permissions of the original identity — The original identity is granted the permission to assume the target role. Attach the system policy AliyunSTSAssumeRoleAccess or a custom policy that contains the sts:AssumeRole operation to the original identity. The system policy AliyunSTSAssumeRoleAccess allows a RAM user to assume all RAM roles. For more information about authorization, see Grant permissions to a RAM user.
Role-based SSO logon — If you log on through role-based SSO, you are already logged on as a RAM role. To switch to another role, make sure that the current role has the permission to assume the target role. For example, if the identity after role-based SSO logon is Role A and you want to switch to Role B, Role A must have an access policy that allows assuming Role B.
AccessKey pair (API and CLI only) — An AccessKey pair of a RAM user is prepared for programmatic authentication. For detailed steps, see Create and use an AccessKey pair for programmatic access.

Assume a RAM role in the console

After you log on to the console as a RAM user or through role-based SSO, you can assume a RAM role by switching identity.

Procedure1. Log on to the RAM console as a RAM user or through role-based SSO.

Hover over the profile picture in the upper-right corner and click Switch Identity.
On the Switch Role page, enter the information of the RAM role that you want to assume.
a. enterprise alias / default domain name / Alibaba Cloud account ID: Enter any one of the following: the enterprise alias (account alias) of the account that owns the RAM role, the default domain name, or the Alibaba Cloud account ID of the account that owns the role. To switch across accounts, enter the Alibaba Cloud account ID of the target account.
b. Role name: The name of the RAM role that you want to assume. Ask your administrator, or view it on the Identity Management > Roles page of the RAM console.
Click Submit.
After the identity is switched, you operate the console as the RAM role. The profile picture area in the upper-right corner of the console displays the current identity and the logon identity (the original identity). The panel includes a RAM role label that identifies the current identity type. At the bottom, the Back to Logon Identity and Sign Out buttons are provided.
(Optional) To switch back to the original logon identity, hover over the profile picture in the upper-right corner of the console and click Back to Logon Identity. After the switch, the permissions of the RAM role become invalid, and the permissions of the original identity are restored.
The following table describes the display formats of the logon identity and the current identity:

Logon scenario	Logon identity	Current identity
RAM user logon	`<RAM username>`	`<RoleName>/<RAM username>`
Role-based SSO logon (first time)	Not displayed	`<RoleName>/<RoleSessionName>`
Switch identity after role-based SSO logon	`<SSO role name>/<RoleSessionName>`	`<Switched role name>/<RoleSessionName>`

Field descriptions

RoleName: The name of the role that is currently assumed.
RoleSessionName: The session name. It is the RAM username when a RAM user logs on. In role-based SSO logon, it is provided by the IdP and remains unchanged after you switch identity.

Example

User Tom (UPN: tom@example.com, where UPN is the User Principal Name) logs on to the console through role-based SSO as the role test-saml-role1, and then switches to the role alice-testrole. Assume that the RoleSessionName is the UPN of the user. The logon identity and the current identity are as follows:

Logon identity: test-saml-role1/tom@example.com
Current identity: alice-testrole/tom@example.com

Assume a RAM role by calling API operations

You can call the operations of STS to assume a RAM role and obtain the STS token of the assumed role. When a program or service accesses Alibaba Cloud resources with the STS token, it can perform operations within the permissions of the assumed role.

Role assumption operations

The following table describes the role assumption operations of STS. Choose an operation based on the credentials or identity federation method of the caller.

API	Description
AssumeRole	Gets the STS token for assuming a RAM role. Applicable to role assumption scenarios that use credentials such as an AccessKey pair or an STS token.
AssumeRoleWithSAML	Gets the STS token by using a SAML assertion. Applicable to SAML role-based SSO scenarios.
AssumeRoleWithOIDC	Gets the STS token by using an OpenID Connect (OIDC) token. Applicable to OIDC role-based SSO scenarios.

When you call the operations above, you must use the RoleArn parameter to specify the RAM role that you want to assume. The ARN format is acs:ram::<Alibaba Cloud account ID>:role/<role name>.

You can also pass the Policy parameter (session policy) to further restrict the permissions of the assumed role within the current role session.

Required permissions

The permissions that are required vary depending on the operation that you use for role assumption:

If you use the AssumeRole operation, the caller must be granted the sts:AssumeRole operation permission. For example, you can attach the AliyunSTSAssumeRoleAccess system policy to the caller.
If you use the AssumeRoleWithSAML or AssumeRoleWithOIDC operation, you only need to correctly configure the trusted SAML or OIDC IdP in the trust policy of the target RAM role. There is no need to separately assign a RAM access policy to the external identity.
You can use the Alibaba Cloud software development kit (SDK) to call the role assumption operations to assume a RAM role. For sample code, see the related SDK documentation, such as Use an AccessKey pair and a RamRoleArn to get an STS token (Python SDK).

To verify that the STS token works, use it to call the GetCallerIdentity operation of STS. The response contains the ARN of the assumed role.

Assume a RAM role by using Alibaba Cloud CLI

The following example shows how to use Alibaba Cloud CLI to assume the RAM role admin-role and complete management tasks as the role.

Configure identity credentials for Alibaba Cloud CLI. This example uses the RamRoleArn mode, which uses the AccessKey pair of a RAM user as the authentication method to complete role assumption.
```
aliyun configure --profile RamRoleArnProfile --mode RamRoleArn
```

As prompted, enter the AccessKey ID, the AccessKey secret, the ARN of the role that you want to assume, the role session name, and other information. For more information about the parameters and usage, see Configure credentials for Alibaba Cloud CLI.

Configuring profile 'RamRoleArnProfile' in 'RamRoleArn' authenticate mode...
Access Key Id []: <yourAccessKeyID>
Access Key Secret []: <yourAccessKeySecret>
Sts Region []: cn-shanghai
Ram Role Arn []: acs:ram::012345678910****:role/admin-role
Role Session Name []: user-name
External ID []: abcd1234
Expired Seconds [900]: 900
Default Region Id []: cn-shanghai
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[RamRoleArnProfile] ...Done.

Expired Seconds keeps the default value 900 seconds (15 minutes) shown in the CLI prompt. This value differs from the default value (3,600 seconds) of the DurationSeconds parameter of the AssumeRole* operations.

After the authentication is completed, run the required commands with the profile. The identity used to run the commands is the assumed RAM role admin-role, not the RAM user that owns the AccessKey pair.
```
aliyun ram ListUsers --profile RamRoleArnProfile
```
aliyun sts GetCallerIdentity --profile RamRoleArnProfile. The response contains the ARN of the assumed role.
To assume another RAM role as the assumed role, see Role chaining.

If role assumption fails

If the administrator configures special condition rules for the target RAM role, such as sts:ExternalId or sts:SourceIdentity, or if the target role trusts only specific principals such as a specific RAM user, role assumption may fail.

If role assumption fails or an API call returns a permission-related error, check the access policies granted to the original identity and the trust policy of the target role.

Cross-account role assumption

Cross-account role assumption allows you to use an identity (a RAM user or a RAM role) under one Alibaba Cloud account to assume a RAM role under another Alibaba Cloud account, and thereby access the resources of that account.

Cross-account role assumption requires the following conditions:

The target role must trust the source account, or a RAM user or RAM role under the source account. This is defined by the Principal keyword in the trust policy of the target role.
The original identity must have the sts:AssumeRole operation permission.
For more information, see Perform cross-account role assumption.

Role chaining

Role chaining is the process in which a RAM identity (or a role-based SSO identity) assumes one role and then continues to assume other roles as that role. Role chaining builds on the standard role assumption mechanism described in this topic.

To allow Role A to continue assuming Role B, Role A must be granted the sts:AssumeRole operation permission, and Role B must trust Role A.

The following example uses Alibaba Cloud CLI to show how to use role chaining:

Follow the example in Use the CLI to assume a RAM role to configure Alibaba Cloud CLI and assume the role admin-role (the source role).
Add the system policy AliyunSTSAssumeRoleAccess to the role admin-role.

Create the target RAM role, for example, named target-role. Modify the trust policy of the target role and specify the identity as admin-role in the Principal keyword:

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::<ACCOUNT_ID>:role/admin-role"
        ]
      }
    }
  ],
  "Version": "1"
}

Use the ChainableProfile mode to configure Alibaba Cloud CLI.

aliyun configure --profile ChainableProfile --mode ChainableRamRoleArn

As prompted, enter the source profile name, the ARN of the role that you want to continue assuming, and other information.

Configuring profile 'ChainableProfile' in 'ChainableRamRoleArn' authenticate mode...
Source Profile []: RamRoleArnProfile
Sts Region []: cn-shanghai
Ram Role Arn []: acs:ram::012345678910****:role/target-role
Role Session Name []: user-name
External ID []: abcd1234
Expired Seconds [900]: 900
Default Region Id []: cn-shanghai
Default Output Format [json]: json (Only support json)
Default Language [zh|en] zh: en
Saving profile[ChainableProfile] ...Done.

After the authentication is completed, run the following command to view the identity information of the current caller. The response contains the ARN of the target role.
```
aliyun sts GetCallerIdentity --profile ChainableProfile
```
In role chaining scenarios, tracing the identity of the initial role caller through audit logs becomes difficult. As a best practice, enable auditing of role assumption.

Role session duration

A role session is a time-limited access session established after a principal, such as a RAM user or another trusted entity, successfully assumes a role. The role session duration controls how long you can perform operations as the role. After the session expires, you must assume the role again to get a new session.

Console

Determining factor	Default value	Valid range	Description
Maximum session duration	1 hour	1 to 12 hours	Can be configured for each role individually.
Logon session expiration	6 hours	1 to 24 hours	A global setting that affects all RAM users and RAM roles.

The effective session duration is the lesser of the two factors above. For example, if the logon session expiration is set to 8 hours and the maximum session duration of Role A is set to 1 hour, after you switch to Role A, the session duration is 1 hour. After the session expires, switch identity again to assume the role.

OpenAPI

Determining factor	Default value	Valid range	Description
Maximum session duration	1 hour	1 to 12 hours	Can be configured for each role individually.
`DurationSeconds` parameter	3,600 seconds (1 hour)	900 seconds (15 minutes) to the maximum session duration	Specified when you call the `AssumeRole*` operations.
Validity of the SAML response/OIDC token	Determined by the IdP (usually 1 hour)	Determined by the IdP	Only for role-based SSO scenarios, when you get an STS token through the `AssumeRoleWithSAML` or `AssumeRoleWithOIDC` operation.

The effective session duration is the lesser of the factors above. After the session expires, call the AssumeRole* operations again to assume the role.

To learn how to configure the maximum session duration and the logon session expiration, see Configure the maximum session duration of a RAM role and Configure the logon session expiration.

FAQ

How do I restrict a user to assuming only specific RAM roles

The system policy AliyunSTSAssumeRoleAccess allows assuming all RAM roles. To restrict role assumption to specific RAM roles, configure a custom access policy for the original identity and modify the trust policy of the target role. For more information, see How do I restrict a specific RAM user from assuming a specific RAM role.

Can an Alibaba Cloud account assume a RAM role

No. An Alibaba Cloud account (root account) cannot switch to a RAM role in the console, and cannot assume a RAM role by calling the AssumeRole operation.

What do I do if the temporary credentials obtained through role assumption are leaked

If the temporary credentials that you obtained through role assumption are leaked, you can revoke all STS tokens that have been issued. For more information, see What do I do if an STS token is leaked.

Resource Access Management:Assume a RAM role