Help Center/ Identity and Access Management/ User Guide/ Permissions Management/ Policies/ Policy Grammar

Updated on 2024-12-25 GMT+08:00

View PDF

Policy Grammar

The following uses a custom policy for OBS as an example to describe the policy grammar.

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:bucket:ListAllMyBuckets",
                "obs:bucket:HeadBucket",
                "obs:bucket:ListBucket",
                "obs:bucket:GetBucketLocation"
            ],
            "Condition": {
                "StringEndWithIfExists": {
                    "g:UserName": [
                        "specialCharacter"
                    ]
                },
                "Bool": {
                    "g:MFAPresent": [
                        "true"
                    ]
                }
            },
            "Resource": [
                "obs:*:*:bucket:*"
            ]
        }
    ]
}

Policy Structure

A policy consists of a version and one or more statements (indicating different actions).

Figure 1 Policy structure
Click to enlarge

Policy Parameters

Policy parameters include Version and Statement, which are described in the following table. You can create custom policies by specifying the parameters. For details, see Custom Policy Use Cases.

**Table 1** Policy parameters
Parameter		Description	Value
Version		Policy version.	1.1: indicates policy-based access control.
Statement	Effect	Determines whether to allow or deny the operations defined in the action.	Allow Deny NOTE: If an action has both Allow and Deny effects, the Deny effect takes precedence.
	Action	Operations to be performed on the service.	Format: "Service name:Resource type:Operation". Wildcard characters () are supported, indicating all options. Actions are case insensitive. Example: obs:bucket:ListAllMybuckets: Permissions for listing all OBS buckets. View all actions of the service in its API Reference*, for example, see Supported Actions of OBS.
	Condition	Determines when a policy takes effect. A condition consists of a condition key and an operator.	Format: "Condition operator:{Condition key:[Value 1,Value 2]}" (the condition key is case insensitive) If you set multiple conditions, the policy takes effect only when all the conditions are met. Example: StringEndWithIfExists":{"g:UserName":["specialCharacter"]}: The statement is valid for users whose names end with specialCharacter.
	Resource	Resources on which the policy takes effect.	Format: Service name:region:domainId:Resource type:Resource path. The resource type is case insensitive. It supports wildcard characters (* ), which indicates all resources. For details about cloud services that support resource-level authorization and supported resource types, see Cloud Services that Support Resource-Level Authorization Using IAM. Example: obs:::bucket:: All OBS buckets. obs:::object:my-bucket/my-object/: All objects in the my-object directory of the my-bucket bucket.

Condition key

A condition key is a key in the Condition element of a statement. There are global and service-level condition keys.

Global condition keys (starting with g:) apply to all operations. IAM provides common global condition keys and special global condition keys.
- Common global condition keys: Cloud services do not need to provide user identity information. Instead, IAM automatically abstracts user information and authenticates users. For details, see Table 2.
- Special global condition keys: IAM obtains condition information from cloud services for authentication. Only certain cloud services support special global condition keys.
Service-level condition keys (starting with a service name abbreviation, for example, obs:) apply only to operations on the specified service. For details, see the user guide of the corresponding cloud service, for example, see OBS Request Conditions.

**Table 2** Common global condition keys
Global Condition Key	Type	Description
g:CurrentTime	Time	Time when an authentication request is received. The time is in ISO 8601 format, for example, 2012-11-11T23:59:59Z. (See an example in 1.)
g:DomainName	String	Account name of the requester. (See an example in 2.)
g:MFAPresent	Boolean	Whether to obtain a token through MFA authentication. (See an example in 3.)
g:MFAAge	Number	Validity period of a token obtained through MFA authentication. This condition must be used together with g:MFAPresent. (See an example in 4.)
g:PKITokenIssueTime	Time	Time when the PKI token is issued. The time is in ISO 8601 format, for example, 2012-11-11T23:59:59Z. (See an example in 5.)
g:ProjectName	String	Project name. (See an example in 6.)
g:UserId	String	IAM user ID. (See an example in 7.)
g:UserName	String	IAM username. (See an example in 8.)

**Table 3** Special global condition keys
Global Condition Key	Type	Description
g:SourceIp	IP Address	IP address of the user sending a request.
g:SourceVpc	String	VPC ID of the user sending a request.
g:SourceVpce	String	VPC endpoint ID of the user sending a request.
g:TagKeys	String	Resource tag key.
g:ResourceTag/{TagKey}	String	Resource tag key value.

g:CurrentTime

Example: The following policy grants permission to create agencies in IAM from March 1, 2023, 08:00 GMT+08:00 to March 30, 2023, 08:00 GMT+08:00. The value of the g:CurrentTime condition key is in UTC format.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          "DateGreaterThan": {
                                   "g:CurrentTime": ["2023-03-01T00:00:00Z"]
                          },
                          "DateLessThan": {
                                   "g:CurrentTime": ["2023-03-30T00:00:00Z"]
                          }
                  }
         }]
}

g: DomainName

Example: The following policy only allows user zhangsan to create agencies in IAM.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          "StringEquals": {
                                   "g:DomainName": ["zhangsan"]
                          }
                  }
         }]
}

g:MFAPresent

Example: The following policy allows users who obtain credentials using MFA to create agencies in IAM.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          "Bool": {
                                   "g:MFAPresent": ["true"]
                          }
                  }
         }]
}

g:MFAAge

Example: The following policy allows users who obtain credentials using MFA with the valid period greater than 900s to create agencies in IAM.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          " NumberGreaterThanEquals ": {
                                   "g:MFAAge": ["900"]
                          }
                  }
         }]
}

g:PKITokenIssueTime
Example: The following policy allows users who use the PKI token issued before March 1 08:00, 2023 (Beijing Time) to create agencies in IAM.

The value of the g:PKITokenIssueTime condition key is in UTC format.
```
{
	"Version": "1.1",
	"Statement": [{
		"Effect": "Allow",
		"Action": ["iam:roles:createRoles"],
		"Condition": {
			"DateLessThan": {
				"g:PKITokenIssueTime": ["2023-03-01T00:00:00Z"]
			}
		}
	}]
}
```

g:ProjectName

Example: The following policy allows users who obtain credentials in CN North-Beijing to create agencies in IAM.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          " StringEquals ": {
                                   "g: ProjectName ": ["cn-north-4"]
                          }
                  }
         }]
}

g: UserId

Example: The following policy allows user whose ID is xxxxxxxxxxx… to create agencies in IAM.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          "StringEquals": {
                                   "g: UserId ": ["xxxxxxxxxxx…"]
                          }
                  }
         }]
}

g: UserName

Example: The following policy allows user lisi to create agencies in IAM.

{
         "Version": "1.1",
         "Statement": [{
                  "Effect": "Allow",
                  "Action": ["iam:roles:createRoles"],
                  "Condition": {
                          "StringEquals": {
                                   "g: UserName ": ["lisi"]
                          }
                  }
         }]
}

Multivalued condition keys
1. ForAllValues: Tests whether the value of every member of the request set is a subset of the condition key set. The condition returns true if every key value in the request matches at least one value in the policy.
```
{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ims:images:share"
            ],
            "Condition": {
                "ForAllValues:StringEquals": {
                    "ims:TargetOrgPaths": [
                        "orgPath1",
                        "orgPath2",
                        "orgPath3"
                    ]
                }
            }
        }
    ]
}
```
  This policy shows how to use the ForAllValues qualifier with the StringEquals condition operator. The condition determines whether to allow sharing with the member accounts in organization path orgPath1, orgPath2, or orgPath3.
  
  Assume a user makes a request to share IMS with the member accounts in organization paths orgPath1 and orgPath3. The request is allowed because the user's requested attributes all match values specified in the policy.
  
  If the user's request includes orgPath1, orgPath2, orgPath3, and orgPath4, the request fails because orgPath4 is not included in the condition operator.
2. ForAnyValue: Tests whether at least one member of the set of request values matches at least one member of the set of condition key values. The condition returns true if any one of the key values in the request matches any one of the condition values in the policy. For no matching key or a null dataset, the condition returns false.
```
{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ims:images:share"
            ],
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "ims:TargetOrgPaths": [
                        "orgPath1",
                        "orgPath2",
                        "orgPath3"
                    ]
                }
            }
        }
    ]
}
```
  This policy shows how to use the ForAnyValue qualifier with the StringEquals condition operator. The condition determines whether to allow sharing with the member accounts in organization path orgPath1, orgPath2, or orgPath3.
  
  Assume a user makes a request to share IMS with the member accounts in organization path orgPath1 or orgPath4. The request is allowed because the user's requested attributes all match values specified in the policy.
  
  If the user initiates a request to share IMS with the member accounts in organization path orgPath4 or orgPath5, the request fails because orgPath4 and orgPath5 are not included in the condition operator.

Condition operators

Figure 2 Condition operators
Click to enlarge

If a single condition operator includes multiple values for one key, that condition operator is evaluated using a logical OR. The condition returns true if any one of the key values in the request matches any one of the condition values in the policy.

For negated matching condition operators (such as StringNotEquals), the request value cannot match any of the condition values based on the condition operators.
If your policy has multiple condition operators or multiple keys attached to a single condition operator, the conditions are evaluated using a logical AND.

Operator

An operator, a condition key, and a condition value together constitute a complete condition statement. A policy takes effect only when its request conditions are met. The operator suffix IfExists indicates that a policy takes effect if a request value is empty or meets the specified condition. For example, if the operator StringEqualsIfExists is selected for a policy, the policy takes effect if a request value is empty or equal to the specified condition value. Operators are string operators. They are not case-sensitive unless otherwise specified.

String condition operators

**Table 4** String condition operators
Type	Operator	Description
String	StringEquals	Exact matching, case sensitive
	StringNotEquals	Negated matching, case sensitive
	StringEqualsIgnoreCase	Exact matching
	StringNotEqualsIgnoreCase	Negated matching
	StringMatch	Case-sensitive matching. The values are regular expressions that support only multi-character match wildcards (*) and single-character match wildcards (?).
	StringNotMatch	Negated case-sensitive matching. The values are regular expressions that support only multi-character match wildcards (*) and single-character match wildcards (?).

For example, the following statement contains a Condition element that uses "g:DomainName" to specify that the principal whose domain name is "ZhangSan" can obtain the object content and metadata.

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:object:GetObject"
            ],
            "Condition": {
                "StringEquals": {
                    "g:DomainName": [
                        "ZhangSan"
                    ]
                }
            }
        }
    ]
}

Numeric condition operators

**Table 5** Numeric condition operators
Type	Operator	Description
Number	NumberEquals	Matching
	NumberNotEquals	Negated matching
	NumberLessThan	"Less than" matching
	NumberLessThanEquals	"Less than or equals" matching
	NumberGreaterThan	"Greater than" matching
	NumberGreaterThanEquals	"Greater than or equals" matching

For example, the following statement contains a Condition element that uses the "NumericLessThanEquals" condition operator with the "obs:max-keys" key to specify that the requester can list up to 10 objects in "example_bucket" at a time.

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:bucket:ListBucket"
            ],
            "Resource": [
                "OBS:*:*:bucket:example_bucket"
            ],
            "Condition": {
                "NumberLessThanEquals": {
                    "obs:max-keys": [
                        "10"
                    ]
                }
            }
        }
    ]
}

Date condition operators

**Table 6** Date condition operators
Type	Operator	Description
Date	DateLessThan	Matching before a specific date and time
	DateLessThanEquals	Matching at or before a specific date and time
	DateGreaterThan	Matching after a specific date and time
	DateGreaterThanEquals	Matching at or after a specific date and time

For example, the following statement contains a Condition element that uses the "DateLessThan" condition operator with the "g:CurrentTime" key to specify that the requester can create buckets only before August 1, 2022.

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:bucket:CreateBucket"
            ],
            "Condition": {
                "DateLessThan": {
                    "g:CurrentTime": [
                        "2022-08-01T00:00:00Z"
                    ]
                }
            }
        }
    ]
}

Bool condition operators

**Table 7** Bool condition operators
Type	Operator	Description
Bool	Bool	Boolean conditions let you construct Condition elements that restrict access based on comparing a key to "true" or "false."

For example, this identity-based policy uses the Bool condition operator with the "g:MFAPresent" key to allow only requesters with MFA enabled can modify specified permanent access keys.

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:credentials:updateCredential"
            ],
            "Condition": {
                "Bool": {
                    "g:MFAPresent": [
                        "true"
                    ]
                }
            }
        }
    ]
}

Null condition operators

**Table 8** Null condition operators
Type	Operator	Description
Null	Null	Use a Null condition operator to check if a condition key is absent at the time of authorization. In the policy statement, use either "true" (the key does not exist or is null) or "false" (the key exists and its value is not null).

For example, you can use this condition operator to specify that only requests of creating buckets from VPCs are allowed.

{
    "Version": "1.1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                " obs:bucket:CreateBucket"
            ],
            "Condition": {
                "Null": {
                    "obs:SourceVpc": [
                        "false"
                    ]
                }
            }
        }
    ]
}

IfExists operator suffix
You can add "IfExists" to the end of any condition operator name except the "Null condition", for example, StringEqualsIfExists. If the policy key is present in the context of the request, process the key as specified in the policy. If the key is not present, evaluate the Condition element as true.

Parent topic: Policies

Previous topic: Policy Content

Next topic: Policy Variables

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot