What is a RAM role?

A Resource Access Management (RAM) role is a RAM identity that is attached specific policies, much like a RAM user. However, a role is not uniquely associated with a single person or application. Instead, it is assumed by any trusted principal—such as a user or another service—that requires its permissions. A role does not have long-term credentials like a password or an AccessKey pair. When a principal assumes a role, the Security Token Service (STS) dynamically generates temporary security credentials that are valid only for that session.

Each RAM role is a resource in your account with a unique Alibaba Cloud Resource Name (ARN): acs:ram::<account-id>:role/<role-name>. You use the ARN to reference the role in policies or API calls. To learn how to find a role's ARN, see View the information about a RAM role.

Why use RAM roles?

RAM roles offer a more secure and efficient way to manage access to your Alibaba Cloud resources.

Temporary elevated privileges: You can use a role to temporarily grant a principal a higher level of permissions to perform a specific task. This reduces the risk associated with long-term, high-privilege credentials.
Cross-account resource access: You can use a role to grant principals in one Alibaba Cloud account access to resources in another account. This allows for centralized management and secure resource sharing without creating and managing duplicate identities.
Secure service and application access: Applications running on an Elastic Compute Service (ECS) instance or other services can assume a role to obtain temporary credentials by calling the AssumeRole operation. This avoids hard-coding AccessKey pairs in your application code.

Key concepts

Understanding the following concepts is essential for using RAM roles effectively.

Principal

A principal is an identity that can assume a role. The role's trust policy defines which principals are trusted. Principals fall into three types:

Type	Description	Common use cases
Alibaba Cloud account	An account itself or RAM users or other RAM roles within that account—can assume the role. The account can be the same one that owns the role or a different one.	A RAM user switches identity in the console or call the `AssumeRole` operation using the CLI or SDK to assume a role.
Alibaba Cloud service	A specified cloud service can assume the role. This type of role is called a service role.	Delegate a cloud service to act on your behalf. For example, assign an instance RAM role to an ECS instance so applications running on it can access data in an Object Storage Service (OSS) bucket. Many cloud services also use a service-linked role—a predefined role linked to the service—to enable its functionality.
Identity provider (IdP)	Users from a specified IdP (supporting SAML 2.0 or OIDC) can assume the role. This enables identity federation.	Users from your corporate IdP can use role-based single sign-on (SSO) to log on to the Alibaba Cloud console. Federated users can call the `AssumeRoleWithSAML` or `AssumeRoleWithOIDC` operations, providing a token from the IdP (a SAML assertion or ID token) to obtain temporary credentials.

Note

When an Alibaba Cloud account is specified as the trusted principal, any identity within that account can assume the role by default. You can refine this by modifying the role's trust policy to restrict access to specific RAM users or roles. For more information, see Modify the trust policy of a RAM role.

Role assumption

Assuming a RAM role is the process by which a trusted principal temporarily acquires the permissions of the role. When a role is assumed, the Security Token Service (STS) issues a set of temporary security credentials. This action initiates a role session, during which the original identity's permissions are suspended. The assumed role can belong to the same account or a different account (cross-account role assumption).

You can assume a role by switching identity in the console or by calling API operations such as AssumeRole or AssumeRoleWithSAML / AssumeRoleWithOIDC.

Trust policy

A trust policy is a required, JSON-formatted document attached to a RAM role. It defines which principals (accounts, users, roles, or cloud services) can assume the role. This policy is a resource-based policy where the resource is the role itself.

Key functions:

Defines who can assume the role: The Principal element of the trust policy specifies the trusted principals.
Controls the conditions for assumption: You can add Condition elements to further restrict when the role can be assumed, such as requiring MFA or a specific source IP address.
Works with access policies: The trust policy defines who can assume the role, while the access policies attached to the role define what the role can do after it is assumed.

Example:

The following trust policy allows any identity in account 123456789012**** to assume the role:

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::123456789012****:root"
        ]
      }
    }
  ],
  "Version": "1"
}

Differences between RAM roles and RAM users

While both are RAM identities, roles and users serve different purposes. The following table highlights the key differences.

Comparison item	RAM user	RAM role
Usage	Represents a specific person or application and is used directly	Represents a set of permissions and must be assumed by a principal
Credentials	Has long-term credentials (password and/or AccessKey pair)	Has no long-term credentials. Temporary credentials (STS tokens) are generated upon assumption
Credential validity	Long-term (until manually changed or deleted)	Temporary and expire after a configurable duration
Trust policy	None	Requires a trust policy to define who can assume the role

For limitations on RAM roles, see Limitations.

Role session

When a principal assumes a role, it initiates a role session. The temporary credentials issued by STS are associated with this session. Any actions performed using these credentials are attributed to the role session.

A role session has:

Session name (RoleSessionName): A user-provided identifier for the session. It appears in ActionTrail logs so you can trace actions to the user or application that assumed the role.
Session duration: A fixed lifecycle; credentials expire when the session ends.

Note

You can pass an inline session policy when assuming a role. The effective permissions of the role session are the intersection of the role's access policies and the session policy. This allows you to dynamically scope down the role's permissions for a specific session. For more information, see the Policy parameter in the AssumeRole API reference.

Role chaining

Role chaining occurs when you use a role to assume a second role. For example, a RAM user assumes Role A, then uses the STS token from Role A to assume Role B. The roles can be in the same or different accounts.

Role chaining is common in complex multi-account environments. For example, a developer might federate into a central "jump" account (assuming Role A), and from there, assume a more privileged role (Role B) in a production account to perform a specific task.

You can chain roles using the Alibaba Cloud CLI, SDKs, or by switching roles in the console. For more information, see Use role chaining.

Use cases

Granting temporary elevated privileges
A developer works day-to-day with a RAM user that has limited permissions. When they need to perform a sensitive operation, such as modifying a production database, they can assume a role that grants the necessary administrative permissions for that task. After completing the task, they stop using the role, and their privileges revert to the limited set. This adheres to the principle of least privilege.
For more information, see Methods to assume a RAM role.
Delegating access between accounts
An organization has separate Alibaba Cloud accounts for development (Account A) and production (Account B). To allow a CI/CD pipeline running in Account A to deploy an application to ECS in Account B, you can:
1. Create a role in Account B that trusts Account A.
2. Grant the CI/CD service role in Account A permission to assume that role in Account B.
3. The CI/CD pipeline assumes the role in Account B to obtain credentials for deploying the application.
For more information, see Cross-account resource access.
Granting access to Alibaba Cloud services
An application running on an ECS instance needs to read objects from an OSS bucket. Instead of embedding an AccessKey pair in the application, you create a service role for ECS that has read permissions for the bucket. You then attach this role to the ECS instance. The application can then use the automatically provided temporary credentials to access OSS securely.
For more information, see Instance RAM roles.
Providing access for federated users
Your enterprise uses an external IdP (like Microsoft Entra ID or Okta). To allow employees to access the Alibaba Cloud console, you can configure identity federation using SAML 2.0 or OIDC and create a RAM role that trusts the IdP. When a user logs on, the IdP authenticates them and they assume the role to access Alibaba Cloud. This allows you to manage users centrally in your IdP without creating individual RAM users in Alibaba Cloud.
For more information, see Overview of role-based SSO by using SAML and Overview of role-based SSO by using OIDC.

Resource Access Management:RAM role overview