Overview

What is a RAM role?

A RAM role is a RAM identity type with attached policies. Unlike a RAM user, a role is not bound to a single person or application—any trusted principal can assume it. Roles have no long-term credentials such as passwords or AccessKey pairs. When a principal assumes a role, the Security Token Service (STS) generates temporary security credentials 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>, used to reference the role in policies or API calls. To find a role's ARN, see View a RAM role.

Why use RAM roles?

RAM roles improve access security and efficiency:

Temporary elevated privileges: Grant a principal elevated permissions for a specific task without maintaining long-term high-privilege credentials.
Cross-account resource access: Grant principals in one account access to resources in another, enabling centralized management without duplicate identities.
Secure service and application access: Applications on an Elastic Compute Service (ECS) instance or other services assume a role via AssumeRole for temporary credentials, eliminating hard-coded AccessKey pairs in application code.

Key concepts

Understand these concepts before working with RAM roles.

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	Any identity within the account—the account itself, RAM users, or other RAM roles—can assume the role. The account can be the role's owner or a different account.	A RAM user switches identity in the console or calls `AssumeRole` via the CLI or SDK.
Alibaba Cloud service	A specified cloud service can assume the role. This is called a service role.	Delegate a cloud service to act on your behalf. For example, attach an instance RAM role to an ECS instance so its applications can access 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 the trusted principal, any identity within that account can assume the role by default. To restrict access to specific RAM users or roles, Modify the trust policy of a RAM role.

Role assumption

Assuming a RAM role is how a trusted principal temporarily acquires the role's permissions. STS issues temporary security credentials and initiates a role session, during which the original identity's permissions are suspended. The role can belong to the same or a different account (cross-account 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 document attached to a RAM role that defines which principals—accounts, users, roles, or services—can assume it. It is a resource-based policy where the resource is the role itself.

Key functions:

Defines who can assume the role: The Principal element specifies trusted principals.
Controls assumption conditions: Add Condition elements to restrict when the role can be assumed, such as requiring MFA or a specific source IP.
Works with access policies: The trust policy defines who can assume the role; the access policies define what the role can do once assumed.

Example:

This 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"
}

Role session

When a principal assumes a role, it initiates a role session. STS temporary credentials are tied to this session, and all actions performed with them are attributed to the session.

A role session has:

Session name (RoleSessionName): A user-provided session identifier that appears in ActionTrail logs, enabling you to trace actions to the assuming principal.
Session duration: A fixed lifecycle; credentials expire when the session ends.

Note

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

Role chaining

Role chaining occurs when a role is used to assume another role. For example, a RAM user assumes Role A, then uses its STS token to assume Role B. The roles can be in the same or different accounts.

This pattern is common in multi-account environments. For example, a developer federates into a central jump account (Role A), then assumes a privileged role (Role B) in a production account for a specific task.

Chain roles using the Alibaba Cloud CLI, SDKs, or the console. Use role chaining.

Differences between RAM roles and RAM users

Roles and users are both RAM identities but serve different purposes.

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.

Use cases

Granting temporary elevated privileges

A developer with limited day-to-day permissions assumes a role with administrative privileges to perform a sensitive operation, such as modifying a production database. After the task, privileges revert to the limited set, enforcing least privilege.

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.
Cross-account resource access.
Granting access to Alibaba Cloud services

An application on an ECS instance needs to read from an OSS bucket. Instead of embedding an AccessKey pair, create a service role with read permissions and attach it to the instance. The application uses the automatically provided temporary credentials to access OSS.

For more information, see Instance RAM roles.
Providing access for federated users

Your enterprise uses an external IdP (such as Microsoft Entra ID or Okta). Configure identity federation with SAML 2.0 or OIDC and create a RAM role that trusts the IdP. Authenticated users assume the role to access Alibaba Cloud, enabling centralized user management without individual RAM users.

Overview of role-based SSO by using SAML and Overview of role-based SSO by using OIDC.

RAM role overview