Syntax

This document describes the syntax structure and rules of authentication policies in RAM. You can find information about policy structure, policy syntax, elements usage, and policy example in this document.

Structure

A policy consists of the policy version and a list of authorization statements.

Each statement contains the following elements: Effect (authorization type), Action (specified operations), Resource (specified objects), and Condition (specified restrictions). The Condition element is optional.

An example of the basic policy structure is shown in the following figure.

Format

RAM only supports descriptions written in the JSON format. When creating or updating a policy, RAM will first check whether it is formatted correctly.

For information on JSON syntax standards, see RFC 7159. You can also use some online JSON format validators and editors to check the validity of the JSON text.

Syntax

Know the characters allowed to be used in a policy and the related rules, and the syntax descriptions.

Character rules

Policies include the JSON characters: { } [ ] " , :; and the description syntax uses these special characters: = < > ( ) |.

For using the preceding characters, the rules include:

• When an element permits multiple values, it can be expressed using commas and ellipses, for example: [<action_string>, <action_string>, ...]

• All syntaxes that support multiple values, also allow single values. The following two expressions are equivalent: "Action": [<action_string>] and "Action": <action_string>

• An element with a question mark indicates an optional element, for example: <condition_block?>

• When multiple values are separated by a vertical bar (|), this indicates that only one of the values can be selected. For example: ("Allow" | "Deny")

• An element enclosed with double quotes indicate a text string. For example: <version_block> = "Version" : ("1")

Syntax description

The syntax description is as follows:

policy  = {
     <version_block>,
     <statement_block>
}
<version_block> = "Version" : ("1")
<statement_block> = "Statement" : [ <statement>, <statement>, ... ]
<statement> = {
    <effect_block>,
    <action_block>,
    <resource_block>,
    <condition_block?>
}
<effect_block> = "Effect" : ("Allow" | "Deny")
<action_block> = ("Action" | "NotAction") :
    ("*" | [<action_string>, <action_string>, ...])
<resource_block> = ("Resource" | "NotResource") :
    ("*" | [<resource_string>, <resource_string>, ...])
<condition_block> = "Condition" : <condition_map>
<condition_map> = {
  <condition_type_string> : {
      <condition_key_string> : <condition_value_list>,
      <condition_key_string> : <condition_value_list>,
      ...
  },
  <condition_type_string> : {
      <condition_key_string> : <condition_value_list>,
      <condition_key_string> : <condition_value_list>,
      ...
  }, ...
}
<condition_value_list> = [<condition_value>, <condition_value>, ...]
<condition_value> = ("String" | "Number" | "Boolean")

For the preceding description, note the following:

• Version: The current policy version is 1.

• Statements: A single policy can have multiple authorization statements.

  • Each authorization statement can be either Deny or Allow. In an authorization statement, Action is a list of multiple operations and Resource is a list of multiple objects.

  • Each authorization statement supports independent conditions. A condition block can specify multiple condition operation types and logical combinations of these conditions.

• Deny takes priority: You can grant multiple policies to a single user. If these policies contain both Allow and Deny statements, the Deny statements have a higher priority.

• Values:

  • When the value of an element is a numeric or Boolean value, the format is similar to character strings. In such cases, the value must be placed in double quotes.

  • When the value of an element is a character string, the wildcards (*) and (?) can be used for fuzzy matching. In a fuzzy match,

    • (*) can be replaced by zero or more English letters.
    • (?) can be replaced by any 1 English letter.

    For example, “ecs:happ*” matches the ECS API operation names “happiness” and “happy”, but “ecs:happ?” only matches “happy”.

Elements usage

Know how to use the elements in a policy.

Effect

Effect specifies the authorization type. The Effect value can be either Allow or Deny. For example,

"Effect": "Allow"

Action

Action specifies the operations to be authorized. Action supports multiple values, which are API operation names defined by cloud services. The format for Action values is as follows:

<service-name>:<action-name>

Format description:

• service-name: Refers to the name of an Alibaba Cloud product, such as ECS, RDS, Server Load Balancer, OSS, and Table Store.

• action-name: Refers to the name of a service-related API.

Description example:

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

Resource

Resource generally specifies the operation objects, such as ECS virtual machine instances and OSS objects. Alibaba Cloud service resource names are formatted as follows:

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

Format description:

• acs: the abbreviation of Alibaba Cloud Service, indicating an Alibaba Cloud public cloud platform.

• service-name: the name of an open service provided by Alibaba Cloud, such as ECS, OSS, or Table Store.

• region: region information. If this option is not supported, use the wildcard “*” instead.

• account-id: the account ID, such as 1234567890123456. You can also enter the wildcard “*”.

• relative-id: the service-related resource. Its meaning is specified by the specific service. The format is similar to the tree-like structure of a file path. Using OSS as an example, relative-id = "mybucket/dir1/object1.jpg" indicates an OSS object.

Description example:

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

Condition

Condition specifies condition restrictions.

A condition block is composed of one or more condition clauses. A single condition clause consists of the condition operation type, condition keyword, and condition value.

Condition logic

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

• When one or more values are specified for a single condition keyword, the condition clause is met when the value of the condition keyword is equal to one designated value.

• A condition clause is met only when multiple condition keywords of the same operation type contained in the condition clause are met.

• A condition block is met only when all condition clauses under the condition block are met.

Condition operation type

Condition operations are categorized as string, numeric, date, Boolean, and IP address.

The condition operation types support the following methods:

Condition keyword

The condition keywords reserved by Alibaba Cloud service adopt the following naming format:

acs:<condition-key>

Alibaba Cloud service reserves the following general condition keywords:

Product-level condition keywords can be defined for cloud products, in the following format:

<service-name>:<condition-key>

The following table lists the condition keywords defined for some cloud products.

Policy example

The following policy contains two authorization statements.

• The first authorization statement grants permission to view all ECS resources in the East China 1 (Hangzhou) region (ecs:Describe*).

• The second authorization statement grants read permission (oss:ListObjects, oss:GetObject) for objects in the OSS bucket mybucket, and restricts the source IP address of requesters to be “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"]
                }
            }
        }
    ]
}