Resource Access Management:Basic elements of policies

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.

Example:

"Effect": "Allow"

Action/NotAction

The Action element specifies one or more API operations that are allowed or denied. The NotAction element specifies the operations that are excluded when operations are allowed or denied. This means that except for the operations specified by NotAction, all other operations are allowed or denied. You can specify only one of these elements in a policy statement. This element is required.

Valid values of the Action/NotAction element: API operation names defined by Alibaba Cloud services.

Format of the Action/NotAction element: <ram-code>:<action-name>.

• ram-code: the RAM code of the Alibaba Cloud service. For more information, see the RAM Code column in Alibaba Cloud services that support RAM.

• action-name: the name of the related API operation.

In most cases, the values of the Action/NotAction element are not case-sensitive. However, to maintain consistent behavior, use the accurate operation prefix <ram-code> and operation name <action-name> as specified in the authorization documentation of the Alibaba Cloud service.

Examples:

• Action example

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

• NotAction example

  The following example allows all operations except RAM operations. The policy statement lists only the excluded operations (ram:*) rather than all allowed operations, which makes the policy statement shorter. However, the scope of allowed operations is large. Use this approach with caution to ensure that the policy meets your expectations.

  {
  	"Effect": "Allow",
  	"NotAction": "ram:*",
  	"Resource": "*"
  }

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 of the Resource element: Alibaba Cloud Resource Names (ARNs) of resources.

Format of the Resource element: acs:<ram-code>:<region>:<account-id>:<relative-id>. Use the accurate resource ARN as specified in the authorization documentation of the Alibaba Cloud service.

The Resource element contains the following fields:

• acs: the abbreviation of Alibaba Cloud Service, which indicates the public cloud platform of Alibaba Cloud.

• ram-code: the RAM code of the Alibaba Cloud service. For more information, see the RAM Code column in Alibaba Cloud services that support RAM.

• region: the region information. This parameter is set to an asterisk (*) for a global resource. 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 Alibaba Cloud account. Example: 123456789012****.

• relative-id: the resource description part related to the service. The semantics of this part are specified by the specific Alibaba Cloud service. The format of the relative-id element is similar to a file path. For example, the format of 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 Condition element specifies the conditions 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 consists of condition operators, condition keys, and condition values.

The name (key) of a condition key is case-sensitive. Whether the condition value (value) is case-sensitive depends on the conditional operator you use. For example, 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.

The following information describes the Condition element in detail:

• 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.

• Categories of conditional operators

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

  Category of conditional operators	Supported types
  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

  • Format of Alibaba Cloud common condition keys: 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, 8:00:00 PM on January 10, 2023 in UTC+8 can be expressed as 2023-01-10T20:00:00+08:00 or 2023-01-10T12:00:00Z.
    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 the request. Note The value of acs:SourceIp can be a specific 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 the MFA Required For Sign-in parameter in the security settings of a RAM user is set to Only When Risky Sign-in Is Detected, the acs:MFAPresent condition becomes invalid. For more information, see Manage the security settings of a RAM user.
    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. For 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 information about the Alibaba Cloud services and resource types that support this condition key, see the Resource Type Authorization information in Alibaba Cloud services that support tags.
    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 information about the Alibaba Cloud services and resource types that support this condition key, see the Resource Type Authorization information in Alibaba Cloud services that support tags.

  • Format of Alibaba Cloud service-level condition keys: <ram-code>:<condition-key>.

    For example, the OSS condition key oss:Delimiter is used to group object names when a ListObjects request is sent.

    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 who have enabled MFA and are from the IP address 203.0.113.2 to access 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 RAM users who have enabled MFA or are from the IP address 203.0.113.2 to access 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.

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 []. The logical relationship between multiple principals is OR. This means that all principals specified in the policy are authorized.

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 (acs:ram::<account-id>:root). 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 (acs:ram::<account-id>:user/<user-name>). <user-name> must be the same as 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 approach helps reduce security risks. When you create or modify a trust policy, you do not need to pay attention to the case of <user-name>. The system automatically converts it to 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 (acs:ram::<account-id>:role/<role-name>). <role-name> must be the same as 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 approach helps reduce security risks. When you create or modify a trust policy, you do not need to pay attention to the case of <role-name>. The system automatically converts it to 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 the identifier of the Alibaba Cloud service. The format is <service-name>.aliyuncs.com. For the value of <service-name>, see the complete service name provided by the Alibaba Cloud service. Example:

  "Principal": {
    "Service": [
      "ecs.aliyuncs.com"
    ]
  }

• Identity provider

  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). If you use SAML-based SSO, you must create a SAML IdP. The ARN format is acs:ram::<account-id>:saml-provider/<provider-name>. If you use OIDC-based SSO, you must create an OIDC IdP. The ARN format is acs:ram::<account-id>:oidc-provider/<provider-name>. 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>"
    ]
  }