Last Updated: Jun 21, 2017

Basic concepts


A Textbook-Role (or a role as traditionally defined) indicates a permissions set. It is similar to a policy in RAM. If a role is granted to a user, this means that the corresponding permissions are granted to the user.


A RAM-Role differs from a textbook role. A RAM-Role is a virtual user (or shadow account). It is a type of RAM user. This type of virtual user has a fixed identity and can be granted policies. However, it does not have a fixed identity authentication key (a logon password or access key).

AM-Roles differ from normal RAM-Users in the way they are used. RAM-Roles must be assumed by an authorized real user. After assuming a role, the real user receives a temporary security token for this RAM-Role. Then, the user can use this temporary security token to access the resources authorized for the role.

Virtual users vs. Real users

The difference between a virtual user and a real user is that a real user’s identity can be directly authenticated. A real user has a logon password or access key. For example, Alibaba Cloud accounts, RAM-User accounts, and cloud service accounts are real users and have fixed authentication keys. However, a virtual user, such as a RAM-Role, does not have a fixed authentication key.

A RAM-Role must be Associated with a real user identity so that it becomes available. If a real user wants to use a RAM-Role that has been granted to the user, the real user must first log on using his identity and then perform the SwitchRole operation to switch from a Real Identity to a Role Identity. The user can then perform all operations authorized for this role identity, but the access permissions of the user’s real identity will not be available. To switch from the Role Identity back to Real Identity, the user needs to perform the Switch Back to Logon Identity operation. Then, the user will have the access permissions corresponding to his real identity, but not those of the role.

RAM-Roles are mainly used to address identity federation needs, such as associating with your enterprise’s local accounts to achieve SSO (Single-Sign-On), entrusting other Alibaba Cloud accounts and their RAM-Users to perform operations on your resources, and entrusting cloud service to perform operations on your resources.

Note: Unless otherwise stated, in this text, role will always refer to a RAM-Role.

There are several basic concepts related to RAM-Roles:

Concept Explanation
RoleARN A RoleARN is the global resource descriptor of a role. It is used to specify a role. RoleARNs follow Alibaba Cloud’s ARN naming rules. For example, the RoleARN for the ‘devops’ role under an Alibaba Cloud account would be: acs:ram::1234567890123456:role/devops.
Trusted Actors A role’s trusted actors are the real user identities that can assume this role. When creating a role, you must specify the trusted actors. A role can only be assumed by trusted actors.
Permission Policy A role can be bound to a permissions set, which we call a policy. Roles not bound to permissions can exist, but cannot be used.
AssumeRole By performing the AssumeRole operation, a real user can obtain a security token for a role. By calling the AssumeRole API, a real user obtains the role’s security token and can use this token to access cloud service APIs.
SwitchRole By performing the SwitchRole operation on the console, a real user can switch from the current logon identity to a role identity. After a real user logs on to the console, the user can switch to a role for which he is a trusted actor. Then, the user can use the role identity to perform operations on cloud resources. After switching to a role identity, the user’s real identity access permissions are no longer available. When the user no longer needs to use a role, he can switch from the role back to the original logon identity.
Role Token A role token is a temporary access key for the role identity. Role identities do not have fixed access keys, so when a real user wants to use a role, he must assume the role to obtain the corresponding role token. Then, the user can use this role token to call Alibaba Cloud service APIs.

Role application scenarios:

  • Temporarily authorize a mobile app client to perform operations on the resources under your control

    Scenario: Enterprise A has developed a mobile app and has bought OSS. The mobile app must upload and download data to and from OSS, but A does not want to allow all apps to use the AppServer to transmit data. A wants to allow the app to directly upload and download data to and from OSS. Because the mobile app runs on user devices, these devices are out of A’s control. For security reasons, A cannot save the access key in the app. A wants to minimize its security risks by, for example, giving each app an access token with only the minimum permissions it needs when directly connected to OSS and restricting the access duration to a short period of time (such as 30 minutes).

    Solution: Alibaba Cloud account A creates a role in RAM and gives this role the appropriate permissions. Then, it allows AppServer (giving it a RAM user identity) to use this role. When the app needs to directly connect to OSS to upload and download data, AppServer can use this role to obtain the role’s temporary security token and send it to the app. The app can use the temporary security token to directly access OSS APIs. If more precise control of the permissions of each app is required, when using the role, the AppServer can further restrict the resource operation permissions of the temporary security token. For example, if different app users can perform operations only on certain subdirectories, the AppServer can make these restrictions when using the role.

  • Cross-account resource operations and authorization management

    Scenario: There are two enterprises, A and B. A has purchased multiple cloud resources and uses them to conduct its businesses. A wants to focus on its business systems, so it entrusts or grants cloud resource O&M, monitoring management, and other tasks to enterprise B. Enterprise B will further delegate O&M tasks to its employees. B needs to precisely control the operations its employees can perform on A’s cloud resources. If A and B terminate this O&M entrustment contract, A is able to revoke B’s permissions at will.

    Solution: Alibaba Cloud account A creates a role in RAM and gives this role the appropriate permissions. Then, it allows Alibaba Cloud account B to use this role. If account B has employees (RAM-Users) who need to use this role, it can independently control their permissions. When performing O&M operations on behalf of A, account B’s RAM-users can use the role identity to perform operations on A’s resources. If accounts A and B terminate their contract, A just needs to revoke B’s permission to use this role. Once account B’s permission to use this role is revoked, all RAM-Users of account B will automatically lose their permission to use this role.

Role types

RAM supports two types of roles: User Roles and Service Roles.

  • User roles

    Roles that can be assumed by RAM-Users are called User Roles. RAM-Users permitted to assume roles can belong to your Alibaba Cloud account or another Alibaba Cloud account. User roles are used to solve problems such as Cross-account Access and Temporary Authorization.

  • Service roles

    Roles that can be assumed by cloud services are called Service Roles. Service roles are used to authorize cloud services to perform operations on resources on your behalf.

Create and use roles

Create roles

To create a RAM-Role on the RAM console, complete the following steps:

  1. Select the role type.
  2. Select the trusted actor identities.
  3. Enter the role name.
  4. Bind a permission policy to the role.

Create a role to be used by RAM-Users

  1. Log on to the RAM console and click Roles.
  2. On the Role Management page, click New Role.
  3. In the Create Role window, click Select Role Type to select a role type and then follow the role creation steps.

    • If you create a role to be used by the RAM-Users under your own account (such as authorizing a mobile app client to directly perform operations on OSS resources), you can select your Alibaba Cloud account as the trusted Alibaba Cloud account.

    • If you create a role to be used by the RAM-Users under another Alibaba Cloud account (such as for cross-account resource authorization), you need to select an Alibaba Cloud account and enter its ID in the Trusted Alibaba Cloud account ID field, as shown in the following figure.


  4. After creating a role, you can click or Authorize to grant permissions to it, or click Close to finish.


    If you did not choose to grant role permissions in step 4, you can also click Authorize next to the role on the Role Management page to grant permissions. The role authorization method is similar to the normal RAM-User authorization method. For details, refer to User Authorization.authorize

After creating a role, you can click the role and go to the Role Details page to get detailed information.

Create a role to be used by cloud services

Operation procedure: Log on to the RAM console and select Role Management > Create Role. In the role creation window, select Service Role and then follow the role creation steps.

Use a role

AssumeRole must be performed using RAM user identities

In order to follow best security practices, assuming roles with trusted Alibaba Cloud accounts is not permitted. Therefore, you need to use a trusted account to create a RAM-User account, and grant the AssumeRole permission to the RAM-User account. Then, you can assume the role by using this RAM-User identity.

  1. Create a RAM-User and create an access key or set a logon password for this user.
  2. Grant permissions to this RAM-User. During authorization, you can select an AliyunSTSAssumeRoleAccess system authorization policy.

The RAM-User uses the role identity to access cloud service APIs

After a RAM-User is granted AssumeRole permission, the user can use the access key to call the STS AssumeRole API to obtain a temporary security token for this role. For the AssumeRole API calling method, refer to the STS API Documentation.

The RAM-User uses the role identity to perform console operations

If a RAM-User needs to use the role identity to perform console operations, the RAM-User must first log on to the console with the logon identity. Then, using the “SwitchRole” method, the user can use the role identity to perform console operations.

For example, the RAM-User Alice under company2 (enterprise alias) logs on to the console, the user can move the mouse pointer to the account name on the upper-right corner and click Switch Role. Alice needs to select the corresponding company alias and role name (here, we assume that the user has been granted permission to assume the ‘ecs-admin’ role of company1 (enterprise alias). After switching to the role, Alice can use the role identity to access the console.

Thank you! We've received your feedback.