What are the elements of a permission policy - Resource Access Management

In RAM, a permission policy defines the permissions. A permission policy consists of basic elements, including Effect, Action/NotAction, Resource, Condition, and Principal.

Parameter	Description
Effect	The authorization effect. Valid values are: `Allow`: Grants permission. `Deny`: Revokes permission.
Action/NotAction	The operation on a resource. In a statement, you must specify either `Action` or `NotAction`. `Action`: The specific operations that are allowed or denied. `NotAction`: The exceptions to the specified operations. All operations except for those specified in `NotAction` are allowed or denied.
Resource	The object or objects that the statement covers.
Condition	The conditions required for the policy to take effect.
Principal	The entity that is allowed or denied access to a resource. This element is used only in resource-based policies, such as a RAM role trust policy.

Effect

The required Effect element specifies whether a statement allows or denies access.

Valid values are Allow and Deny.

Note

If a permission policy contains both Allow and Deny effects, Deny takes precedence.

Example:

"Effect": "Allow"

Action/NotAction

The Action element specifies the operations to allow or deny. The NotAction element specifies the operations that are excluded from the Allow or Deny effect. A statement must include either an Action or a NotAction element.

The value is the name of an API operation from an Alibaba Cloud service.

The format for the Action/NotAction element is <ram-code>:<action-name>.

ram-code: The RAM code of the Alibaba Cloud service. For more information, see the RAM Code column in Services that work with RAM.
action-name: The name of the API operation.

Values in Action and NotAction are generally not case-sensitive. However, to ensure consistent behavior, use the exact service prefix <ram-code> and action name <action-name> as specified in the documentation for each Alibaba Cloud service.

Examples:

Action example

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

NotAction example
The following example allows all operations except for RAM operations. Using NotAction to list only the excluded action (ram:*) makes the statement shorter than listing all allowed actions. However, this approach can grant broad permissions, so use NotAction with caution.
```
{
	"Effect": "Allow",
	"NotAction": "ram:*",
	"Resource": "*"
}
```

Resource

The required Resource element specifies one or more objects that the statement affects and is used in identity-based policies.

The value is a resource ARN (Aliyun Resource Name) from an Alibaba Cloud service.

The format of a resource ARN is acs:<ram-code>:<region>:<account-id>:<relative-id>. Use the exact resource ARN as specified in the authorization documentation for each Alibaba Cloud service.

The following table describes the format.

acs: An abbreviation for Alibaba Cloud Service, indicating the Alibaba Cloud public cloud platform.
ram-code: The RAM code of the Alibaba Cloud service. For more information, see the RAM Code column in Services that work with RAM.
region: The region. For global resources, which can be accessed without specifying a region, use an asterisk (*) for this field. For more information, see Regions and availability zones.
account-id: The ID of an Alibaba Cloud account. Example: 123456789012****.
relative-id: The part of the resource description that is related to the service. Its semantics are specified by the specific cloud service. The format of this part supports a tree-like structure (similar to a file path). For example, the format for an OSS object is: relative-id = "mybucket/dir1/object1.jpg".

Example:

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

Condition

The optional Condition element specifies the conditions required for a policy to take effect.

The Condition element is also known as a condition block. It consists of one or more condition clauses. A condition clause is composed of a condition operator, a condition key, and a condition value.

条件块判断逻辑

Note

The system does not validate the Condition element because it is optional. If you include conditions, ensure their spelling and case are correct.

The name (key) of a condition key is strictly case-sensitive, and whether a condition value (value) is case-sensitive depends on the condition operator that you use. For example, for a string-type condition key, the StringEquals operator performs a case-sensitive match between the value in the policy and the value in the request. The StringEqualsIgnoreCase operator performs a case-insensitive match.

The details of the Condition element are as follows:

Evaluation logic
- Condition match: A condition key can have one or more values. The condition is met if the key's value in the request matches any of the values specified in the policy (logical OR).
- Condition clause match: A condition clause is met only if all its condition keys are met (logical AND).
- Condition block match: A condition block is met only if all of its condition clauses are met (logical AND).
Condition operators
Condition operator types include String, Number, Date and time, Boolean, and IP address. For more information about the meanings and examples of condition operators, see Condition operators.

Condition keys

The format for global condition keys is acs:<condition-key>.

Global condition key	Type	Description
`acs:CurrentTime`	Date and time	The time when the web server receives the request. Note The time is in UTC and complies with the ISO 8601 standard. For example, 20:00:00 on January 10, 2023 (UTC+8) is represented as `2023-01-10T20:00:00+08:00` or `2023-01-10T12:00:00Z`.
`acs:SecureTransport`	Boolean	Specifies whether the request was sent over a secure channel, such as HTTPS.
`acs:SourceIp`	IP address	The client IP address from which the request was sent. Note The value of `acs:SourceIp` can be a specific IP address or a CIDR block. Do not write a specific IP address in CIDR format. For example, `10.0.0.1` cannot be written as `10.0.0.1/32`.
`acs:MFAPresent`	Boolean	Specifies whether the user logged in with multi-factor authentication (MFA). Note If the MFA for RAM user sign-in setting for the RAM user is set to Required Only for Unusual Logon, the `acs:MFAPresent` condition does not take effect. For more information, see Manage RAM user security settings.
`acs:PrincipalARN`	String	The identity of the principal making the request. This condition key is available only in Resource Directory control policies and RAM role trust policies. Example: `acs:ram:::role/resourcedirectory`. Note Currently, you can specify only the ARN of a RAM role, and the ARN must be in 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 principal belongs. This condition key can be used only in RAM role trust policies and OSS bucket policies.
`acs:PrincipalRDPath`	String	The path of the Alibaba Cloud account of the principal in the Resource Directory. This condition key can be used only in RAM role trust policies and OSS bucket policies.
`acs:RequestTag/<tag-key>`	String	The tag information passed in the request. <tag-key> is the tag key. Replace it with an actual value. For supported cloud services and resource types, see the Resource Type Authentication information in Cloud services that support tags.
`acs:ResourceTag/<tag-key>`	String	Specifies the information about the tags that are attached to the requested resource. <tag-key> is the tag key. Replace it with an actual value. For the supported cloud services and resource types, see the Resource Type Authorization information in Cloud services that support tags.

The format for service-specific condition keys is <ram-code>:<condition-key>.
For example, the OSS condition key oss:Delimiter specifies the character for grouping object names in a ListObjects request.
For the condition keys of each Alibaba Cloud service, see the authorization documentation for that service.

Condition examples

Conditions in a single statement are evaluated using a logical AND. If you want to use a logical OR for your conditions, you must place them in separate statements.

Example 1: Allow a RAM user to access ECS instances only if the user has enabled MFA and initiates the access request from the IP address 203.0.113.2.

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

Example 2: Allow a RAM user to access ECS instances only if the user has enabled MFA or initiates the access request from the IP address 203.0.113.2.

{
    "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, which is required in resource-based policies, specifies the entity that is allowed or denied access. For example, in a RAM role trust policy, you use the Principal element to specify which entity can assume the role.

Note

You cannot use the Principal element in an identity-based policy. In an identity-based policy, the RAM entity (RAM user, user group, or RAM role) to which the policy is attached is the implicit principal.

You can add multiple principal types to the Principal element and specify multiple principals for each type. Use a comma (,) to separate different principal types. For a single principal type with multiple values, use square brackets ([ ]) and separate the values with a comma (,). The relationship between multiple principals is a logical OR, which means that all principals specified in the policy are granted permissions.

Principal example:

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

A principal is an authenticated RAM entity. It can be one of the following types:

Alibaba Cloud account
You can set an Alibaba Cloud account as a principal. This grants permissions to the RAM users and RAM roles under that account. When you specify an Alibaba Cloud account, you must use its ARN (acs:ram::<account-id>:root). Example:
```
"Principal": {
    "RAM": "acs:ram::123456789012****:root"
}
```
Note
This ARN represents the account itself, not a specific root user identity.
RAM user
You can set a RAM user as a principal. You must specify the ARN of the RAM user (acs:ram::<account-id>:user/<user-name>), where <user-name> must match the name of the RAM user. Example:
```
"Principal": {
  "RAM": [
    "acs:ram::123456789012****:user/<user1-name>",
    "acs:ram::123456789012****:user/<user2-name>"
  ]
}
```
When you specify a RAM user in the Principal element, you cannot use a wildcard character (*) for partial matching. You must specify the exact RAM user.
Important
In a RAM role trust policy, if the Principal element contains the ARN of a specific RAM user, the system converts this ARN to an ID (for example, 29695932303672****) when you save the trust policy. You are not usually aware of this ID. The ID is displayed in the trust policy only if the RAM user is deleted. In this case, you can delete the ID or modify it to the correct RAM user ARN. This approach helps reduce security risks. In addition, when you create or update a trust policy, you do not need to be concerned about the letter case of <user-name> because the system automatically converts it to a standard ARN.
RAM role
You can set a RAM role as a principal. You must specify the ARN of the RAM role (acs:ram::<account-id>:role/<role-name>), where <role-name> must match the name of the RAM role. Example:
```
"Principal": {
  "RAM": [
    "acs:ram::123456789012****:role/<role-name>"
  ]
}
```
When you specify a RAM role in the Principal element, you cannot use a wildcard character (*) for partial matching. You must specify the exact RAM role.
Important
In a RAM role trust policy, if the Principal element contains the ARN of a specified RAM role, the system converts this ARN to an ID (such as 38915594982675****) when you save the trust policy. You are typically not aware of this ID. It is displayed in the trust policy only if the specified RAM role is deleted. In this case, you can delete the ID or replace it with the correct RAM role ARN. This approach helps reduce security risks. Additionally, when you create or update a trust policy, you do not need to be concerned about the case sensitivity of <role-name> because the system automatically converts it to a standard ARN.
Alibaba Cloud service
You can set an Alibaba Cloud service as a principal. You must specify the service name for the service. The service name is the identifier of an Alibaba Cloud service and typically follows the format <service-name>.aliyuncs.com. For <service-name>, use the full service name provided by the specific Alibaba Cloud service. Example:
```
"Principal": {
  "Service": [
    "ecs.aliyuncs.com"
  ]
}
```
Identity provider
You can specify an identity provider (IdP) as a principal by using its ARN. Alibaba Cloud supports single sign-on (SSO) through SAML 2.0 and OIDC. For SAML SSO, use the ARN of a SAML identity provider. The corresponding ARN is acs:ram::<account-id>:saml-provider/<provider-name>. To use SSO based on OIDC, you must create an OIDC identity provider. The corresponding ARN is acs:ram::<account-id>:oidc-provider/<provider-name>. In the Principal element, ARN values are case-sensitive. Use the standard ARN of the identity provider that is provided by the system.
```
"Principal": {
  "Federated": [
    "acs:ram::123456789012****:saml-provider/<provider-name>"
  ]
}
```