Policy elements - Resource Access Management - Alibaba Cloud Documentation Center

This topic describes the elements of policies that are used in Resource Access Management (RAM) to define permissions. The elements are Effect, Action, Resource, Condition, and Principal.

Element	Description
Effect	Specifies whether a statement result is an explicit allow or an explicit deny. Valid values: Allow and Deny.
Action	Describes one or more API operations that are allowed or denied.
Resource	Specifies one or more objects that the statement covers.
Condition	Specifies the conditions that are required for a policy to take effect.
Principal	Specifies the principal that is allowed or denied access to a resource. This element is available only for resource-based policies, such as a trust policy that specifies a trusted entity to assume a RAM role.

Effect

The Effect element specifies whether a statement result is an explicit allow or an explicit deny. This element is required. Valid values: Allow and Deny.

Note

If a RAM policy includes an Allow statement and a Deny statement at the same time, the Deny statement takes precedence over the Allow statement.

Example:

"Effect": "Allow"

Action

The Action element describes one or more API operations that are allowed or denied. This element is required. Valid values: names of operations from Alibaba Cloud services.

Format: <ram-code>:<action-name>.

ram-code: the code that is used in RAM to indicate an Alibaba Cloud service. For more information, see the codes that are listed in the RAM code column in Services that work with RAM.
action-name: the name of one or more API operations in the service.

In most cases, the value of the Action element is not case-sensitive. However, we recommend that you specify <ram-code> and <action-name> based on the documents for permissions on Alibaba Cloud services. This helps ensure consistency.

Example:

"Action": [
  "oss:ListBuckets",
  "ecs:Describe*",
  "rds:Describe*"
]

Resource

The Resource element specifies one or more objects that the statement covers. This element is required and available only for identity-based policies. Valid values: Alibaba Cloud Resource Names (ARNs) of resources.

The Resource element is in the acs:<ram-code>:<region>:<account-id>:<relative-id> format. Make sure that you specify ARNs based on the documents for permissions on Alibaba Cloud services. The Resource element contains the following fields:

acs: the initialism of Alibaba Cloud Service, which indicates the public cloud of Alibaba Cloud.
ram-code: the code that is used in RAM to indicate an Alibaba Cloud service. For more information, see the codes that are listed in the RAM code column in Services that work with RAM.
region: information about the region. If the statement covers a global resource, set this field to an asterisk (*). A global resource can be accessed without the need to specify a region. For more information, see Regions and zones.
account-id: the ID of the Apsara Stack tenant account. For example, you can enter 123456789012****.
relative-id: the identifier of the service-related resource. The meaning of this element varies based on services. The format of the relative-id element is similar to a file path. For example, relative-id = "mybucket/dir1/object1.jpg" indicates an Object Storage Service (OSS) object.

Example:

"Resource": [
  "acs:ecs:*:*:instance/inst-001",
  "acs:ecs:*:*:instance/inst-002",
  "acs:oss:*:*:mybucket",
  "acs:oss:*:*:mybucket/*"
]

Condition

The Condition element specifies the conditions that are required for a policy to take effect. This element is optional. The Condition element is considered a condition block, which contains one or more conditions. Each Condition element consists of conditional operators, condition keys, and condition values.

条件块判断逻辑

Note

The Condition element is optional. The system does not check whether the Condition element is specified. If you want to specify a value for the Condition element, make sure that the spelling and capitalization are correct.

Condition keys are case-sensitive. Case sensitivity for condition values varies based on the conditional operators that you use. If the condition key is of the string type and you use the StringEquals conditional operator, the system performs a case-sensitive match by comparing the value in a request with the condition value. If the key is of the string type and you use the StringEqualsIgnoreCase conditional operator, the system performs a non-case-sensitive match by comparing the value in a request with the condition value.

Evaluation logic
- You can specify one or more values for a condition key. If the value in a request matches one of the specified values, the condition is met.
- A condition can have multiple keys that are attached to a single conditional operator. This type of condition is met only if all requirements for the keys are met.
- A condition block is met only if all conditions are met.

Conditional operators

Conditional operators can be classified into the following categories: string, number, date and time, Boolean, and IP address.

Category	Conditional operator
String	StringEquals StringNotEquals StringEqualsIgnoreCase StringNotEqualsIgnoreCase StringLike StringNotLike
Number	NumericEquals NumericNotEquals NumericLessThan NumericLessThanEquals NumericGreaterThan NumericGreaterThanEquals
Date and time	DateEquals DateNotEquals DateLessThan DateLessThanEquals DateGreaterThan DateGreaterThanEquals
Boolean	Bool
IP address	IpAddress NotIpAddress

Condition keys

The format of common condition keys is acs:<condition-key>.

Common condition key	Type	Description
`acs:CurrentTime`	Date and time	The time at which a request is received by the web server. Note Specify the time in the ISO 8601 standard. The time must be in UTC. For example, use `2023-01-10T20:00:00+08:00` or `2023-01-10T12:00:00Z` to indicate January 10, 2023, 20:00:00 (UTC+8).
`acs:SecureTransport`	Boolean	Specifies whether a secure channel is used to send a request. For example, a request can be sent over HTTPS.
`acs:SourceIp`	IP address	The IP address of the client that sends a request. Note The value of the `acs:SourceIp` field can be a single IP address or a CIDR block. If the value is a single IP address, you must specify the specific IP address rather than a CIDR block. For example, you must specify 10.0.0.1 rather than 10.0.0.1/32.
`acs:MFAPresent`	Boolean	Specifies whether multi-factor authentication (MFA) is used during user logon. Note If MFA for RAM User Logons is set to Required Only for Unusual Logon in the RAM user security settings, the `acs:MFAPresent` condition key becomes invalid. For more information, see Manage security settings of RAM users.
`acs:PrincipalARN`	String	The identity of the requester. The condition key can be used only in access control policies of resource directories and trust policies of RAM roles. Example: `acs:ram:::role/resourcedirectory`. Note You can specify an ARN only for a specified RAM role. The name can contain only lowercase letters. You can view the ARN of a RAM role on the role details page in the RAM console.
`acs:PrincipalRDId`	String	The ID of the resource directory to which the Alibaba Cloud account of the requester belongs. The condition key can be used only in trust policies of RAM roles and OSS bucket policies.
`acs:PrincipalRDPath`	String	The path in the resource directory to which the Alibaba Cloud account of the requester belongs. The condition key can be used only in trust policies of RAM roles and OSS bucket policies.
`acs:RequestTag/<tag-key>`	String	The tag that is passed in a request. <tag-key> indicates a tag key. Replace <tag-key> with the actual tag key. For more information about the supported Alibaba Cloud services and resource types, see Tag Ram Support in Services that work with Tag.
`acs:ResourceTag/<tag-key>`	String	The tag that is bound to the requested resource. <tag-key> indicates a tag key. Replace <tag-key> with the actual tag key. For more information about the supported Alibaba Cloud services and resource types, see Tag Ram Support in Services that work with Tag.

The format of a condition key that is specific to an Alibaba Cloud service is <ram-code>:<condition-key>.
For example, oss:Delimiter is used to group the names of objects that you want to list by calling the ListObjects operation.
For more information about condition keys of each cloud service, see the authorization document of each cloud service.

Examples

The logical relationship between two conditions in a statement is AND. If you want to set the logical relationship between the conditions to OR, you must specify the conditions separately in two statements.

Example 1: Allow only RAM users for whom MFA is enabled and who access ECS instances from the IP address 203.0.113.2 to access the ECS instances.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecs:*",
      "Resource": "*",
      "Condition": {
        "IpAddress": {
          "acs:SourceIp": [
            "203.0.113.2"
          ]
        },
        "Bool": {
          "acs:MFAPresent": [
            "true"
          ]
        }
      }
    }
  ]
}

Example 2: Allow only RAM users for whom MFA is enabled or who access ECS instances from the IP address 203.0.113.2 to access the ECS instances.

{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ecs:*",
            "Resource": "*",
            "Condition": {
                "IpAddress": {
                    "acs:SourceIp": [
                        "203.0.113.2"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "ecs:*",
            "Resource": "*",
            "Condition": {
                "Bool": {
                    "acs:MFAPresent": [
                        "true"
                    ]
                }
            }
        }
    ]
}

Principal

The Principal element specifies the principal that is allowed or denied access to a resource. This element is available only for resource-based policies. For example, you can use the Principal element to specify a trusted entity to assume a RAM role in a trust policy. The Principal element is required in resource-based policies.

Note

You cannot specify the Principal element in identity-based policies. Identity-based policies are attached to RAM identities, such as RAM users, RAM user groups, and RAM roles. The RAM identities to which identity-based policies are attached are the principals.

You can specify multiple types of principals for the Principal element in a policy. You can also specify multiple principals of the same type for the Principal element in a policy. If you specify multiple types of principals, separate the types with commas (,). If you specify multiple principals of the same type, separate the principals with commas (,) and enclose the principals with brackets []. Multiple principals are associated with each other by the OR operator. The policy is attached to all principals in the policy.

Example:

"Principal": {
  "RAM": [
    "acs:ram::123456789012****:root",
    "acs:ram::987654321098****:root"
  ],
  "Service": "ecs.aliyuncs.com"
}

Principals are authenticated RAM entities, which are divided into the following types:

Alibaba Cloud account
If you set the Principal element to an Alibaba Cloud account in a policy, the policy is attached to all RAM users and RAM roles that belong to the Alibaba Cloud account. You must specify the ARN of the Alibaba Cloud account in the policy. The ARN is in the acs:ram::<account-id>:root format. Example:
```
"Principal": {
    "RAM": "acs:ram::123456789012****:root"
}
```
Note
If you set the Principal element to an Alibaba Cloud account in a policy, the policy is not attached to the Alibaba Cloud account.
RAM user
If you set the Principal element to a RAM user in a policy, you must specify the ARN of the RAM user in the acs:ram::<account-id>:user/<user-name> format. Make sure that <user-name> is the name of the RAM user. Example:
```
"Principal": {
  "RAM": [
    "acs:ram::123456789012****:user/<user1-name>",
    "acs:ram::123456789012****:user/<user2-name>"
  ]
}
```
When you specify the ARN of the RAM user, fuzzy match by using asterisks (*) is not supported.
Important
If the value of the Principal element contains the ARN of the RAM user that will assume a RAM role when you create or modify a trust policy, the system converts the ARN into an ID when the system saves the policy. For example, the system may convert the ARN to 29695932303672****. The ID is displayed in the trust policy only after the RAM user is deleted. After the RAM user is deleted, you can delete the ID or replace the ID with the ARN of an existing RAM user. This helps reduce security risks. When you create or modify a trust policy, the value of <user-name> is not case-sensitive. The system automatically converts the value that you entered into a standard ARN.
RAM role
If you set the Principal element to a RAM role in a policy, you must specify the ARN of the RAM role in the acs:ram::<account-id>:role/<role-name> format. Make sure that <role-name> is the name of the RAM role. Example:
```
"Principal": {
  "RAM": [
    "acs:ram::123456789012****:role/<role-name>"
  ]
}
```
When you specify the ARN of the RAM role, fuzzy match by using asterisks (*) is not supported.
Important
If the value of the Principal element contains the ARN of the RAM role that will assume another RAM role when you create or modify a trust policy, the system converts the ARN into an ID when the system saves the policy. For example, the system may convert the ARN to 38915594982675****. The ID is displayed in the trust policy only after the RAM role that will assume another RAM role is deleted. After the RAM role that will assume another RAM role is deleted, you can delete the ID or replace the ID with the ARN of an existing RAM role. This helps reduce security risks. When you create or modify a trust policy, the value of <role-name> is not case-sensitive. The system automatically converts the value that you entered into a standard ARN.
Alibaba Cloud service
If you set the Principal element to an Alibaba Cloud service in a policy, you must specify the name of the Alibaba Cloud service. The service name is in the <service-name>.aliyuncs.com format. Make sure that you set <service-name> to a valid value. Example:
```
"Principal": {
  "Service": [
    "ecs.aliyuncs.com"
  ]
}
```
Identity provider (IdP)
If you set the Principal element to an IdP in a policy, you must specify the ARN of the IdP. Alibaba Cloud supports single sign-on (SSO) based on Security Assertion Markup Language (SAML) 2.0 and OpenID Connect (OIDC). The ARN of the SAML IdP is in the acs:ram::<account-id>:saml-provider/<provider-name> format. To implement OIDC-based SSO, you must create an OIDC IdP. The ARN of the OIDC IdP is in the acs:ram::<account-id>:oidc-provider/<provider-name> format. The value of the ARN in the Principal element is case-sensitive. Make sure that you specify a valid ARN.
```
"Principal": {
  "Federated": [
    "acs:ram::123456789012****:saml-provider/<provider-name>"
  ]
}
```