All Products
Search
Document Center

Resource Access Management:Assume a RAM role

Last Updated:Feb 08, 2026

A Resource Access Management (RAM) role has no long-term credentials. A trusted principal must assume the role to obtain temporary security credentials and use the role's permissions. This topic explains how to assume a RAM role through the Alibaba Cloud Management Console, the Alibaba Cloud CLI, and the API.

Understanding role assumption

A RAM role does not have long-term security credentials like a password or AccessKey pair. To use a role, a trusted principal (such as a RAM user, an Alibaba Cloud service, or a federated user) must assume the role. This process, known as role assumption, provides the principal with temporary security credentials.

When a principal assumes a RAM role, they temporarily give up their own permissions and take on the permissions granted to the role. The role can be in the same Alibaba Cloud account as the principal or in a different account (cross-account access).

How it works

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

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

Role session duration

When a RAM role is assumed, a temporary session is created. The duration of the session is determined by the lesser of the following values:

  • Maximum session duration of the RAM role: An attribute of the role itself, configurable from 1 to 12 hours (default is 1 hour).

  • Requested session duration:

    • Console: The duration is determined by the global logon session expiration setting for your account, which applies to all RAM users and roles. This can be set from 1 to 24 hours (default is 6 hours).

    • API/CLI: The duration is specified by the DurationSeconds parameter in the AssumeRole call. This can be set from 15 minutes (900 seconds) up to the role's maximum session duration. The default duration is 1 hour (3,600 seconds).

For example, if a role's maximum session duration is 4 hours and you make an AssumeRole call requesting a duration of 8 hours, the session will only last for 4 hours. If you switch to the same role in the console, and the global logon session expiration is 2 hours, your role session will last for 2 hours.

To learn how to configure these settings, see Specify the maximum session duration for a RAM role and Manage the security settings of RAM users.

How to assume a role

Assume a RAM role in the console

After logging on to the console as a RAM user or a federated user, you can switch to a RAM role to perform tasks with that role's permissions.

Prerequisites

  • Log on as a RAM user

    The principal that is switching roles (either a RAM user or another role) must have the sts:AssumeRole permission in its access policy. You can grant this by attaching the AliyunSTSAssumeRoleAccess system policy or a custom policy. For more information, see Manage permissions for a RAM user.

    Note

    The AliyunSTSAssumeRoleAccess system policy grants permission to assume any role. For better security, create a custom policy that restricts this permission to specific RAM role ARNs.

  • Log on using role-based SSO

    The target RAM role's trust policy must allow the principal (or the principal's account) to assume it.

Procedure

  1. Log on to the RAM console as a RAM user or a federated user.

  2. Hover over the profile picture in the upper-right corner and click Switch Identity.

    Snipaste_2025-12-12_10-24-09

    切换身份

  3. On the Switch Role page, provide the following information:

    • Enterprise Alias / Domain / Account UID: Enter the RAM user's default logon suffix, or the account ID or alias of the Alibaba Cloud account that owns the role.

    • Role Name: Enter the name of the RAM role you want to assume.

  4. Click Submit.

    You are now using the permissions of the assumed RAM role. The navigation bar in the upper-right corner displays the current role and your original logon identity in the format CurrentRole/LogonIdentity.

    角色切换成功

    Logon method

    Displayed identity

    (CurrentRole/LogonIdentity)

    Logged on as a RAM user

    AssumedRoleName/RAMUserName

    Logged on via SSO (first assumed role)

    AssumedRoleName/RoleSessionNameFromIdP

    Logged on from an SSO role (role chaining)

    SecondAssumedRole/RoleSessionNameFromIdP

  5. (Optional) To stop using the RAM role, hover over the profile picture in the upper-right corner and click Back to Logon Identity. This restores your original permissions.

Note

If the switch fails, verify that your RAM user's access policy and the target RAM role's trust policy are configured correctly. A failure can occur if the trust policy includes conditions such as sts:ExternalId or sts:SourceIdentity that are not met by your session.

Assume a RAM role programmatically (API)

Your applications can call an API operation to assume a RAM role and receive temporary credentials.

API operations

API operation

Description

AssumeRole

The primary operation for assuming a role. The caller must be an authenticated principal (RAM user or role).

AssumeRoleWithSAML

Used in federation scenarios to exchange a SAML assertion from an IdP for temporary role credentials. The SAML assertion must be valid and unexpired at the time of the call.

AssumeRoleWithOIDC

Used in federation scenarios to exchange an OIDC identity token from an IdP for temporary role credentials. The OIDC token must be valid and unexpired at the time of the call.

Prerequisites

  • To call AssumeRole, the calling principal must have the sts:AssumeRole permission for the target RAM role. For example, you can attach the AliyunSTSAssumeRoleAccess system policy to the the calling principal.

  • To call AssumeRoleWithSAML or AssumeRoleWithOIDC, the target RAM role's trust policy must trust the corresponding IdP. The caller does not need an access policy.

We recommend using the Alibaba Cloud SDKs to call these API operations. The SDKs manage credential retrieval and logon for you. For examples, see Use an AccessKey pair and a RamRoleArn to obtain an STS token (Python SDK).

Note

If the switch fails, verify that your RAM user's access policy and the target RAM role's trust policy are configured correctly. A failure can occur if the trust policy includes conditions such as sts:ExternalId or sts:SourceIdentity that are not met by your session.

Assume a RAM role with the CLI

You can configure an Alibaba Cloud CLI profile to automatically assume a RAM role when you run commands.

  1. Create a profile using the RamRoleArn mode. This mode uses the credentials of a source profile (such as a RAM user's AccessKey pair) to assume the RAM role.

    aliyun configure --profile RamRoleArnProfile --mode RamRoleArn
  2. At the prompt, enter the AccessKey ID and secret of the RAM user who will assume the role, and the ARN of the role to assume (Ram Role Arn). For detailed parameter descriptions, 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.
  3. Run commands using the --profile option. The CLI automatically assumes the role and uses the temporary credentials to run the command.

    aliyun ram ListUsers --profile RamRoleArnProfile

For detailed steps, see Create and use an AccessKey pair for programmatic access.

Advanced use cases

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
Note

Role chaining can make it difficult to identify the original user in ActionTrail logs. To improve traceability, you can use the SourceIdentity condition key to pass the original user's identity through the role chain. For more information, see Use SourceIdentity for auditing and access control.

FAQ

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.

References