Assume a RAM role

How it works

Alibaba Cloud Security Token Service (STS) brokers role assumption through the following steps:

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 these ways:

• 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 for single sign-on (SSO) to the console or federated API access. Role-based SSO.

• Service roles for Alibaba Cloud resources: An Alibaba Cloud service (like ECS or Function Compute) can assume a RAM role to access other resources on your behalf. Applications on Alibaba Cloud accessing Alibaba Cloud resources.

The following sections cover assuming a role via the console, CLI, and API.

Cross-account access

A RAM role enables principals in one account to access resources in another.

This requires:

• 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.

Access resources across Alibaba Cloud accounts.

Role chaining

Role chaining uses the credentials of one assumed role to assume a second role. For example, a user assumes Role-A, then uses Role-A's temporary credentials to assume Role-B.

Role-A must have an access policy allowing sts:AssumeRole on Role-B, and the trust policy of Role-B must list Role-A as a trusted principal.

The following example sets 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 AliyunSTSAssumeRoleAccess, create a custom policy with Action set to sts:AssumeRole and the specific role ARN in the Resource element. 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 Alibaba Cloud account owner cannot assume a RAM role. Role assumption is for RAM users, roles, and federated users.

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

If temporary credentials are compromised, immediately invalidate all active tokens for that role. See the "What do I do if an STS token is leaked? " section in FAQ about RAM roles and STS tokens.