This topic describes the syntax structure and rules of policies in RAM to help you understand and use policies. In routine applications, you can quickly check out the following information if needed:

Policy structure

The policy structure includes the policy version number and authorization statement list. Each authorization statement includes the effect (authorization type), action (operation name list), resource (operational object list), and condition (requirement or restriction), where condition is optional.

The following figure shows the policy structure.

Figure 1. Policy structure


Format check (JSON)

RAM only supports descriptions in JSON format. When creating or updating a policy, RAM first verifies that the JSON format is correct.

  • For information about JSON syntax standards, see RFC 7159.
  • You can use an online JSON format validator and editor to verify the validity of JSON text.

Policy syntax

The following describes the policy syntax and the characters and rules used in policies.

Characters and rules

The JSON characters contained in policy are { } [ ] " , :. The special characters used for syntax description are = < > ( ) |.

The following describes the characters in detail:

  • When an element includes multiple values, separate them with commas (,) and use an ellipsis (...) to indicate omitted values, for example, [ <action_string>, <action_string>, ...]. A single value is allowed even if the syntax supports multiple values. Additionally, the two expressions are equivalent, for example, "Action": [<action_string>] = "Action": <action_string>.
  • An element with a question mark (?) is an optional element, for example, <condition_block?>.
  • When multiple values are separated by vertical bars (|), only one of the values can be used, for example, ("Allow" | "Deny").
  • An element enclosed with double quotation marks ("") is a text string, for example, <version_block> = "Version" : ("1").
Syntax description

Policy syntax is described as follows:

Policy = {
                    <Version _block>,
                    <Wollongong _block>
}
<Version _block> = "version": ("1 ")
<Direct_block> = "statement": [<Statement>, <Statement>,...]
<Statement> = { 
<Glast_block>,
<Action_block>,
<Think_block>,
<Condition _block? >
}
<Glast_block> = "effect": ("allow" | "deny ")  
<Action_block> = ("action" | "notaction "): 
("*" | [<Action_string>, <action_string>,...])
<Think_block> = ("resource" | "notresource "): 
("*" | [<Think_string>, <think_string>,...])
<Condition _block> = "condition": <condition _map>
<Condition _map> = {
<Maid> :{ 
<Condition_key_string>: <condition_value_list>,
<Condition_key_string>: <condition_value_list>,
...
},
<Maid> :{
<Condition_key_string>: <condition_value_list>,
<Condition_key_string>: <condition_value_list>,
...
}, ...
}  
<Condition_value_list> = [<condition _value>, <condition _value>,...]
<Condition _value> = ("string" | "Number" | "Boolean ")

Syntax details are described as follows:

  • Version: The number of currently supported policy versions is 1.
  • Authorization statements: A policy can include multiple authorization statements.
    • Each authorization statement can be denied or allowed. In an authorization statement, the action is a list listing multiple operations, and the resource is a list listing multiple objects.
    • Each authorization statement has independent conditions. A condition block supports multiple conditional operation types and logical combinations of these conditions.
  • Deny prevails: A user can be granted multiple policies. You must follow the "Deny prevails" principle when the authorization statement can be either denied or allowed.
  • Element values:
    • When element values are numbers or boolean values, they must be enclosed with double quotation marks ("") to prevent possible confusion with strings.
    • When element values are strings, fuzzy match through an asterisk (*) or a question mark (?) is supported.
      • An asterisk (*) represents 0 or several letters.
      • A question mark (?) represents a letter.

      For example, ecs:Describe* indicates all ECS API operation names starting with "Describe".

Policy usage rules

The following describes element usage rules in the policy syntax.

Effect (authorization type)

Possible values are Allow and Deny, for example, "Effect": "Allow".

Action (operation name list)

Multiple values are allowed. The values are the API operation names defined by Alibaba Cloud services and are in the following format:
<service-name>:<action-name>

Format description:

  • service-name indicates the name of an Alibaba Cloud product, such as ECS, RDS, SLB, OSS, and OTS.
  • action-name indicates the name of a service-related API operation.

Example:

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

Resource (operational object list)

A resource refers to an operational object, such as an ECS VM instance or an OSS package. Alibaba Cloud service resources are named in the following format:

acs:<service-name>:<region>:<account-id>:<relative-id>

Format description:

  • acs is the abbreviation of Alibaba Cloud service, indicating the public cloud platform of Alibaba Cloud.
  • service-name indicates the name of an open service provided by Alibaba Cloud, such as ECS, OSS, and OTS.
  • region indicates region information. If this field is not supported, use a wildcard (*) instead.
  • account-id indicates the account ID, for example, 1234567890123456. You can also use a wildcard (*).
  • relative-id indicates service-related resources. Its meaning is specified by the specific service. The format of this field supports a tree structure similar to a file path. For example, relative-id = “mybucket/dir1/object1.jpg” represents an OSS object.

Example:

"Resource": ["acs:ecs:*:*:instance/inst-001", "acs:ecs:*:*:instance/inst-002", "acs:oss:*:*:mybucket", "acs:oss:*:*:mybucket/*"]
Condition (requirement or restriction)

A condition block consists of one or more conditional clauses. A conditional clause consists of an action type, condition keyword, and condition value.

Judgment logic
The following figure shows the criteria for determining whether a condition is met.
Figure 2. Judgment principle


The following describes the rules in detail:

  • One condition keyword corresponds to one or more values. When a conditions is checked, if the condition keyword value can match one of the specified values, the condition is met.
  • A conditional clause is met only if multiple condition keywords in the condition clause of the same conditional action type are all matched.
  • A condition block is met only if all its conditional clauses are met.
Conditional action type

The following conditional action types are supported: string, numeric, date (data and time), boolean, and IP address.

The following table describes the methods supported by each conditional action type.

String Numeric Date and time Boolean IP address
StringEquals NumericEquals DateEquals Bool IpAddress
StringNotEquals NumericNotEquals DateNotEquals - NotIpAddress
StringEqualsIgnoreCase NumericLessThan DateLessThan - -
StringNotEqualsIgnoreCase NumericLessThanEquals DateLessThanEquals - -
StringLike NumericGreaterThan DateGreaterThan - -
StringNotLike NumericGreaterThanEquals DateGreaterThanEquals - -
Conditions keyword (Condition-key)

The format of condition keywords reserved by Alibaba Cloud services is as follows:

acs:<condition-key>

The following table describes general condition keywords reserved by Alibaba Cloud services.

General condition keyword Type Description
acs: CurrentTime Date and time Time when the Web server receives a request.

Format: ISO 8601, for example, 2012-11-11T23: 59: 59Z

acs: SecureTransport Boolean Whether the request is sent over a secure channel, for example, HTTPS
acs: SourceIp IP address IP address of the client sending the request
ACS: mfapresent Boolean Whether MFA is used during user logon

The format of product-level condition keywords defined by Alibaba Cloud services is as follows:

<service-name>:<condition-key>

The following table describes condition keywords of some products:

Product name Condition keyword Type Description
ECS ECS: tag/<tag-key> String Tag keywords for ECS resources. You can customize the keyword.
RDS RDS: thinktag/<tag-key> String Tag keywords for RDS resources. You can customize the keyword.
OSS OSS: impressioniter String Delimiter used by OSS to group object names
OSS OSS: prefix String Prefix of OSS object name

Policy example

The following policy example contains two authorization statements:

  • The first authorization statement is to allow users to view (through the ecs:Describe* permission) all ECS resources in region East 1 (Hangzhou).
  • The second authorization statement is to allow users to read and query (through the oss:ListObjects and oss:GetObject permissions) objects from the OSS bucket mybucket only through the network with an IP address of 42.120.88.10 or 42.120.66.0/24.
{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ecs:Describe*",
            "Resource": "acs:ecs:cn-hangzhou:*:*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "oss:ListObjects",
                "oss:GetObject"
            ],
            "Resource": [
                "acs:oss:*:*:mybucket",
                "acs:oss:*:*:mybucket/*"
            ],
            "Condition":{
                "IpAddress": {
                    "acs:SourceIp": ["42.120.88.10", "42.120.66.0/24"]
                }
            }
        }
    ]
}