Resource Access Management:Assume a RAM role

How it works

The process of assuming a RAM role involves the following steps, which are brokered by Alibaba Cloud Security Token Service (STS).

1. Request credentials. A principal (such as RAM user Alice) makes an AssumeRole request to STS, specifying the ARN of the role to be assumed (such as prod-role).

2. Verify permissions. RAM verifies two things: (a) that Alice has the sts:AssumeRole permission in her access policies, and (b) that the trust policy of prod-role specifies Alice (or her account) as a trusted principal.

3. Get a temporary credential. If both checks pass, STS returns a temporary security credential (STS token).

4. Make a request. The principal uses the STS token to make a request to an Alibaba Cloud service, such as OSS. The service authorizes the request based on the access policies attached to prod-role.

Methods of assuming a role

A principal can assume a role in several ways, depending on the use case:

• Switching roles in the console: An authenticated RAM user can switch from their current identity to a RAM role to perform tasks in the Alibaba Cloud Management Console.

• Programmatic access (API/CLI/SDK): An application or script can call an API operation (such as AssumeRole and AssumeRoleWithSAML) to obtain temporary credentials for a RAM role. The Alibaba Cloud CLI and SDKs simplify this process.

• Identity federation (SAML/OIDC): Users from an external identity provider (IdP) can be granted access to assume a RAM role, enabling single sign-on (SSO) to the console or federated API access. For more information, see Role-based SSO.

• Service roles for Alibaba Cloud resources: An Alibaba Cloud service (like Elastic Compute Service or Function Compute) can assume a RAM role to access other resources on your behalf. This is commonly used for applications running on Alibaba Cloud infrastructure. For more information, see Applications on Alibaba Cloud accessing Alibaba Cloud resources.

This topic focuses on assuming a role via the console, CLI, and API. For information on federation and service roles, see the related documentation.

Cross-account access

You can use a RAM role to let principals in one account access resources in another.

This requires two main permission settings:

• The trust policy of the RAM role in the destination account must specify the source account (or a specific principal in it) as a trusted principal.

• The principal in the source account must have the sts:AssumeRole permission in its access policy.

For more information, see Access resources across Alibaba Cloud accounts.

Role chaining

Role chaining is when you use the credentials of one RAM role to assume a second role. For example, a user assumes Role-A, then uses the temporary credentials from Role-A to assume Role-B.

To enable role chaining, the first role (Role-A) must have an access policy allowing it to call sts:AssumeRole on the second role (Role-B). Additionally, the trust policy of Role-B must specify Role-A as a trusted principal.

The following example shows how to set up role chaining with the CLI.

1. Configure a CLI profile (such as RamRoleArnProfile) to assume the initial role (such as admin-role) in the chain. For instructions, see the "Assume a RAM role with the CLI" section in this topic.

2. Grant the source role permission to assume other roles. For example, attach the AliyunSTSAssumeRoleAccess policy to the source role.

3. Create the destination role (such as target-role) and configure its trust policy to trust the source role.

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

4. Configure a new CLI profile using the ChainableRamRoleArn mode.

   aliyun configure --profile ChainableProfile --mode ChainableRamRoleArn

5. At the prompt, specify the name of the source profile (RamRoleArnProfile) and the ARN of the destination role.

   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.

6. Use the new chained profile to run a command. The command is executed with the permissions of the final role in the chain. You can verify this by calling sts GetCallerIdentity.

   aliyun sts GetCallerIdentity

How can I allow a RAM user to assume only a specific RAM role?

Instead of attaching the AliyunSTSAssumeRoleAccess system policy, create a custom policy for the user. In this policy, set the Action to sts:AssumeRole and specify the ARN of the specific role they are allowed to assume in the Resource element. For an example, see the "How do I restrict a specific RAM user from assuming a specific RAM role? " section in FAQ about RAM roles and STS tokens.

Can the Alibaba Cloud account owner assume a RAM role?

No. The owner of an Alibaba Cloud account cannot assume a RAM role. Role assumption is designed for RAM users and roles) as well as federated users.

What should I do if a RAM role's temporary credentials are exposed?

If you suspect that temporary credentials have been compromised, you can immediately invalidate all active tokens for that RAM role. For instructions, see the "What do I do if an STS token is leaked? " section in FAQ about RAM roles and STS tokens.