Policy syntax structure

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.

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").

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)

<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/*"]

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

The following figure shows the criteria for determining whether a condition is met.

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.

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.

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.

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:

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