Help Center/ Identity and Access Management_Identity and Access Management (New Edition)/ User Guide/ References/ Policy Reference/ JSON Element Reference
Updated on 2025-11-07 GMT+08:00
View PDF
Share

JSON Element Reference

A policy consists of JSON elements. This section introduces each of these elements individually. These elements are listed roughly in the order they are used in identity policies; however, the actual sequence of the elements is not significant—different orders will not result in inconsistent permissions. For instance, the "Resource" element can precede the "Action" element. It is important to note that certain JSON elements are mutually exclusive, meaning you cannot craft a policy that includes conflicting elements. As an example, you cannot employ both "Action" and "NotAction" within the same policy statement.

Version

The "Version" element specifies the policy version. The syntax of policies of different versions may be different. Currently, the value of the "Version" element in identity policies and trust policies is 5.0. You should always include a "Version" element and set it to 5.0. The following is an example.

The "Version" element is different from the version of an identity policy. The "Version" element is used in identity policies to specify the version of the identity policy language. An identity policy version is created each time you create or update an identity policy. You can quickly roll back to a previous version of the identity policy. For more information about identity policy versions, see Identity Policy Versions.

{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "obs:bucket:listBucket"
      ]
    }
  ]
}

Statement

"Statement" is the main element of an identity policy. It is mandatory. The "Statement" element is an array that can contain multiple statements. The array must be enclosed in square brackets ([]), and each statement must be enclosed in curly braces ({}). 
"Statement": [{...},{...},{...}]
In the following identity policy, the "Statement" element contains two statements, which grant the principal the permissions to list OBS buckets and view and list ECS servers. 
{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "obs:bucket:listBucket"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:servers:get",
        "ecs:servers:list"
      ]
    }
  ]
}

Sid

You can provide a statement ID ("Sid") as an optional identifier for each statement in a policy. "Sids" are strings that can contain zero or more characters. You can specify a "Sid" for each statement in a policy. However, IAM does not expose "Sids" in public APIs, meaning that you cannot retrieve a specific statement based on its "Sid". 
{
  "Version": "5.0",
  "Statement": [
    {
      "Sid": "StatementIDExample",
      "Effect": "Allow",
      "Action": [
        "obs:bucket:listBucket"
      ]
    }
  ]
}

Effect

"Effect" is mandatory. It specifies whether a statement in a policy allows or denies access. The value can be "Allow" or "Deny". By default, new IAM users do not have any permissions assigned and all requests are denied. To allow an IAM user to access resources, you must set "Effect" to "Allow". If the "Effect" of an action is both "Allow" and "Deny", the "Deny" permission takes precedence. For more information, see Policy Evaluation Logic. 
"Effect":"Allow"

Principal

You can use the "Principal" element in a resource policy to allow or deny access to resources. Currently, Huawei Cloud resource policies include only OBS bucket policies and trust policies. For details, see the "Resource-based policy" column of the table in Cloud Services for Using Identity Policies and Trust Agencies.

  • Account Principal

    The "IAM" in the "Principal" element indicates the account principal. For example, if the trusted principal is an account, you can specify the account ID in the trust policy to allow the account to access resources.

    For example, if the account ID is 55555555555555555555555555555555, you can specify the account principal in the "Principal" element as follows: 
    {
    "Version": "5.0",
    "Statement": [
        {
            "Principal": {
                "IAM": [
                    "55555555555555555555555555555555"
                ]
            },
            "Effect": "Allow",
            "Action": [
                "sts:agencies:assume"
            ]
        }
    ]
}
    The value of the "IAM" element is an array, so you can specify multiple principals in this element. 
    {
    "Version": "5.0",
    "Statement": [
        {
            "Principal": {
                "IAM": [
                    "55555555555555555555555555555555",
                    "ffffffffffffffffffffffffffffffff"
                ]
            },
            "Effect": "Allow",
            "Action": [
                "sts:agencies:assume"
            ]
        }
    ]
}
  • Cloud Service Principal
    The "Service" in the "Principal" element indicates the service principal. Assume that you want to create a trust policy for a trust agency whose principal is a cloud service. You can specify a Huawei Cloud service as the trusted principal and delegate permissions on resources of your account to the service.
    The following example describes how to grant permissions to Resource Governance Center (RGC) for managing resources in your account. 
    {
  "Version": "5.0",
  "Statement": [
    {
      "Action": [
        "sts:agencies:assume"
      ],
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "service.RGC"
        ]
      }
    }
  ]
}

Action

An "Action" element describes a specific operation that can be allowed or denied. Each operation is an action. Ensure that the "Statement" element contains the "Action" or "NotAction" element. Each cloud service has its own actions, which are prefixed with the cloud service name. For the complete list of actions supported by each cloud service, see Actions Supported by Identity Policy-based Authorization. Then, open the chapter of the cloud service and navigate to the "Actions" section. The following are examples of actions supported by some cloud services:

Huawei Cloud OBS: 
"Action": ["obs:object:PutObjectRetention"]
Huawei Cloud ECS: 
"Action": ["ecs:cloudServers:put"]
Huawei Cloud IAM: 
"Action": ["iam:users:listUsersV5"]
You can also specify multiple values for the "Action" element at the same time. 
"Action": ["obs:object:PutObjectRetention", "ecs:cloudServers:put", "iam:users:listUsersV5"]
You can also use the multi-character wildcard (*) and single-character wildcard (?) in the "Action" element to grant access to all operations of a specific cloud service. For example, the following "Action" element represent all ECS operations: 
"Action": ["ECS:*:*"]
You can also use the wildcard (*) or (?) as a part of the action name. For example, the following "Action" element represents all IAM credential actions that contain CredentialV5, including iam:credentials:createCredentialV5, iam:credentials:updateCredentialV5, and iam:credentials:deleteCredentialV5. 
"Action": ["iam:credentials:*CredentialV5"]

NotAction

"NotAction" matches all actions except the actions in the specified list. "NotAction" only requires you to list the actions that you do not want to match, instead of the actions that you want to match. When "NotAction" is used with "Effect": "Allow", all actions except the actions in the list are allowed. When "NotAction" is used with "Effect": "Deny", all actions except the actions in the list are denied. When you use "NotAction" with "Resource", you specify the resource scope for the policy.
  • "NotAction" and "Allow"
    You can use "NotAction" in a statement containing "Effect": "Allow" to allow all actions except the actions in the list. You may need to allow access to a large number of actions. You can use "NotAction" to modify the policy statement, making the list of actions shorter. For example, Huawei Cloud provides a wide range of cloud services, and you may need to create an identity policy to allow users to perform all operations except IAM operations. The following is an example identity policy: 
    {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "NotAction": [
        "IAM:*:*"
      ]
    }
  ]
}

    Be careful when using "NotAction" together with "Effect": "Allow" in the same statement or in different statements of a policy. "NotAction" matches all services and actions that are not explicitly listed or not applicable to the specified resources. This may grant users more permissions than you expect.

  • "NotAction" and "Deny"

    You can use "NotAction" in a statement containing "Effect": "Deny" to deny all actions except the actions in the list. This combination does not grant permissions of the listed services and actions, but denies all services and actions not listed. You still need to explicitly allow the permissions of the desired services and actions.

    In the following example, "Condition" denies non-IAM actions when the user did not pass multi-factor authentication (MFA) during login. If a user passes MFA and logs in, the "Condition" matches fail and the "Deny" statement will not be applied. However, note that this does not grant the user any permissions on any actions; it only explicitly denies all actions except IAM actions when the user did not pass MFA during login. 
    {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Deny",
      "NotAction": [
        "IAM:*:*"
      ],
      "Condition": {
        "BoolIfExists": {
          "g:MFAPresent": [
            "false"
          ]
        }
      }
    }
  ]
}

Resource

The "Resource" element in a policy statement specifies one or more resources to which the statement applies. Huawei Cloud uses URNs to identify resources. The URN format depends on the cloud service and specific resource. For details, see Using URNs to Identify Huawei Cloud Resources. Although URN formats vary, you can always use URNs to identify resources. For details about the URN format of a specific resource, see Actions Supported by Identity Policy-based Authorization. Then, open the section of the cloud service and navigate to the "Resources" section.

The following example indicates all OBS buckets in account xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. 
"Resource": ["obs::xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:bucket:*"]
  • Using Wildcards in Resource URNs

    You can use wildcards (* and?) in the parts (separated by colons) of the URN.

    • The asterisk (*) represents multiple characters.
    • The question mark (?) represents one character.
    You can use multiple asterisks (*) or question marks (?) in each part. If the asterisk (*) is the last character of a URN part, it can match more than one character.

    Do not use wildcards in the service part of a URN. For more information about URN parts, see Using URNs to Identify Huawei Cloud Resources.

    The following example indicates all IAM users in an account. Replace {account_id} with the actual account ID. 
    "Resource": ["iam:*:{account_id}:user:*"]
    The following example indicates all objects in the my-object directory of my-bucket in an account. Replace {account_id} with the actual account ID. 
    "Resource": ["obs:*:{account_id}:object:my-bucket/my-object/*"]
  • Specifying multiple resources
    The "Resource" element is an array. You can specify multiple resources in the array. The following example applies to all objects in the my-object directory of my-bucket OBS bucket as well as all agencies and trust agencies in IAM. Replace {account_id} with your account ID. 
    "Resource": [
    "obs:*:{account_id}:bucket:my-bucket/my-object/*",
    "iam:*:{account_id}:agency:*"
]
  • Using policy variables in resource URNs
    In the "Resource" element, you can use policy variables in the URN part that identifies a specific resource. For example, you can use ${g:UserName} as a part of the resource URN to indicate that the name of the current user must be included as a part of the resource name. 
    {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "obs:bucket:listBucket"
      ],
      "Resource": [
        "obs:*:*:bucket:${g:UserName}"
      ]
    }
  ]
}

Condition

The "Condition" element allows you to specify the conditions for a policy to take effect. The "Condition" element is optional. You can use condition keys and operators in the "Condition" element to specify specific conditions for a policy to take effect.

Condition key names are case-insensitive. Whether condition key values are case-sensitive depends on the operator you use.

Example 1: The following condition contains the StringEquals operator and the condition key g:UserName. This ensures that only requests initiated by Bob are allowed. If the user bob submits a request, the request will be denied. 
{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "StringEquals": {
          "g:UserName": [
            "Bob"
          ]
        }
      }
    }
  ]
}
Example 2: The following condition contains the StringEquals operator, and the condition key is g:userName. This ensures that only requests initiated by Bob are allowed. If the user bob submits a request, the request will be denied. 
{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "StringEquals": {
          "g:userName": [
            "Bob"
          ]
        }
      }
    }
  ]
}
Example 3: The following condition contains the operator StringEqualsIgnoreCase, and the condition key is g:userName. This condition matches users bob and Bob. 
{
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "StringEqualsIgnoreCase": {
          "g:userName": [
            "Bob"
          ]
        }
      }
    }
  ]
}
  • Operators
    An operator, a condition key, and a condition value together form a complete conditional statement. A policy will take effect only when the request information satisfies its condition. Operators can have the "IfExists" suffix added, which means the policy will take effect either if the corresponding request value does not exist or if it exists and meets the condition. For instance, "StringEqualsIfExists" signifies that the policy will take effect if the request value does not exist or if it equals the condition value.
    1. A request value is the value of the condition key in the request context. A condition value is the value of the condition key configured in the policy.
    2. The absence of a request value and an empty value are two distinct concepts. An empty request value indicates that the request value exists but is empty. For example, if the condition key is a string, "None" indicates that it does not exist, while an empty string means it exists but has no value. For multivalued keys, "None" also means it does not exist, and an empty array shows it exists with no values.
    3. Negated operators, such as StringNotEquals, do match against the "None" value, as the value is not equal to the specified string value.
    • String operators
      • Policy variables: supported
      • Wildcard: supported only by StringMatch and StringNotMatch
      Table 1 String operators

      Type

      Operator

      Description

      String

      StringEquals

      Exact matching, case-sensitive

      StringNotEquals

      Negated matching, case-sensitive

      StringEqualsIgnoreCase

      Exact matching, ignoring case

      StringNotEqualsIgnoreCase

      Negated matching, ignoring case

      StringLike (not recommended)

      Case-insensitive matching. Any condition value appears as a consecutive substring of the request value. Wildcards are not supported.

      StringNotLike (not recommended)

      Case-insensitive matching. None of the condition values appears as a consecutive substring of the request value. Wildcards are not supported.

      StringMatch (recommended)

      Case-sensitive matching. Any condition value matches the request value. Wildcards (*) and (?) are supported. If StringMatch contains multiple values, the set operators ForAllValues and ForAnyValue can be used.

      StringNotMatch (recommended)

      Case-sensitive matching. None of the condition values matches the request value. Wildcards (*) and (?) are supported. If StringNotMatch contains multiple values, the set operators ForAllValues and ForAnyValue can be used.

      StringStartWith

      Consecutive substrings as the prefix, case-insensitive

      StringEndWith

      Consecutive substrings as the suffix, case-insensitive

      StringNotStartWith

      Consecutive substrings not as the prefix, case-insensitive

      StringNotEndWith

      Consecutive substrings not as the suffix, case-insensitive
      The following example allows only the requester whose username is ZhangSan to query the IAM user list. 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "StringEquals": {
          "g:UserName": [
            "ZhangSan"
          ]
        }
      }
    }
  ]
}
      If the request context does not contain the key you specified in the policy condition, these values do not match. In the following example, if the principal is an IAM user, the g:PrincipalTag/job-category key exists in the request context only when a tag is added for the IAM user. If the principal is an IAM trust agency and a tag is added to the trust agency or a session tag is added to the temporary security credential of the trust agency, the g:PrincipalTag/job-category key also exists in the request context. If a request is initiated using a subject without a tag, false is returned. Therefore, the subject without a tag is denied access to the user list. 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "StringEquals": {
          "g:PrincipalTag/job-category": [
            "admin"
          ]
        }
      }
    }
  ]
}
      The following table describes how IAM evaluates this policy based on the condition key values in the request.
      Table 2 How IAM evaluates the policy

      Identity Policy Condition

      Request Context

      Result

      		 
      "StringEquals": {
	"g:PrincipalTag/job-category": [
		"admin"
	]
}
      		 
      g:PrincipalTag/job-category: admin

      Match

      		 
      "StringEquals": {
	"g:PrincipalTag/job-category": [
		"admin"
	]
}
      		 
      g:PrincipalTag/job-category: operator

      No match

      		 
      "StringEquals": {
	"g:PrincipalTag/job-category": [
		"admin"
	]
}
      		 
      No g:PrincipalTag/job-category in the request context.

      No match
    • Number operators
      • Policy variables: supported
      • Wildcard: not supported
      Table 3 Number 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": "5.0",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:bucket:ListBucket"
            ],
            "Resource": [
                "OBS:*:*:bucket:example_bucket"
            ],
            "Condition": {
                "NumberLessThanEquals": {
                    "obs:max-keys": [
                        "10"
                    ]
                }
            }
        }
    ]
}
    • Date operators

      The date type is used to match UTC time in RFC 3339 format.

      • Policy variables: supported
      • Wildcard: not supported
      Table 4 Date operators

      Type

      Operator

      Description

      Date

      DateEquals

      Matching

      DateNotEquals

      Negated matching

      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
      The following example allows the requester to query the IAM user list only before September 9, 2025. 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "DateLessThan": {
          "g:CurrentTime": [
            "2025-09-09T00:00:00Z"
          ]
        }
      }
    }
  ]
}
    • Boolean operators
      • Policy variables: supported
      • Wildcard: not supported
      Table 5 Boolean operators

      Type

      Operator

      Description

      Bool

      Bool

      The value can be true or false (case-insensitive). If the request value is the same as the condition key value, the request is matched. If the request value does not exist, the request is not matched.
      For example, the following policy allows only the requester with MFA enabled to modify permanent access keys. 
      {
    "Version": "5.0",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:credentials:updateCredentialV5"
            ],
            "Condition": {
                "Bool": {
                    "g:MFAPresent": [
                        "true"
                    ]
                }
            }
        }
    ]
}
    • IP address operators
      • Policy variables: supported
      • Wildcard: not supported
      Table 6 IP address operators

      Type

      Operator

      Description

      IP

      IpAddress

      IP address or IP address range

      For multi-value condition keys, you can enter an IP address or IP address range. The semantics are as follows:

      • ForAnyValue: The policy takes effect only if any IP address (including IP addresses in the IP address range) in the request context is in any IP address range specified in the user policy.
      • ForAllValues: The policy takes effect only if all IP addresses (including IP addresses in the IP address range) in the request context is in any network segments specified in the user policy.

      NotIpAddress

      All IP addresses beyond a specific IP address or IP address range

      For multi-value condition keys, you can enter an IP address or IP address range. The semantics are as follows:

      • ForAnyValue: The policy takes effect only when any IP address (including IP addresses in the IP address range) of the request context is not in all IP address ranges configured in the user policy.
      • ForAllValues: The policy takes effect only when all IP addresses (including IP addresses in the IP address range) of the request context is not in all IP address ranges configured in the user policy.
      Example: Only requests with IP addresses ranging from 10.27.128.0 to 10.27.128.255 are permitted to modify the designated permanent access keys. For detailed information on the g:SourceIp condition key, refer to Global Condition Key. 
      {
	"Version": "5.0",
	"Statement": [{
		"Effect": "Allow",
		"Action": [
			"iam:credentials:updateCredentialV5"
		],
		"Condition": {
			"IpAddress": {
				"g:SourceIp": [
					"10.27.128.0/24"
				]
			}
		}
	}]
}
    • Null operators
      • Policy variables: supported
      • Wildcard: not supported
      Table 7 Null operators

      Type

      Operator

      Description

      Null

      Null

      Null condition operator checks if a condition key is absent. The value can be true or false (case-insensitive). Value true indicates that the key does not exist and its value is null; false indicates that the key exists and its value is not null.
      For example, you can use this operator to allow only the bucket creation requests from VPCs. 
      {
    "Version": "5.0",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "obs:bucket:CreateBucket"
            ],
            "Condition": {
                "Null": {
                    "obs:SourceVpc": [
                        "false"
                    ]
                }
            }
        }
    ]
}
    • Operator suffix IfExists
      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.

      Other condition factors in the statement can still cause a mismatch. If you use a negated operator (for example, StringNotEqualsIfExists), regardless of whether IfExists is added, the result is equivalent. For example, if "Effect" is set to "Deny" and StringNotEquals is used, the request is denied even if the condition key does not exist.

      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:users:listUsersV5"
      ],
      "Condition": {
        "StringEqualsIfExists": {
          "g:PrincipalTag/job": [
            "iam-user"
          ]
        }
      }
    }
  ]
}
      The following table describes how the condition key values in the request are used to evaluate this policy.
      Table 8 Using condition key values to evaluate this policy

      Policy Condition

      Request Context

      Result

      		 
      "Condition": {
	"StringEqualsIfExists": {
		"g:PrincipalTag/job": [
			"iam-user"
		]
	}
}
      		 
      g:PrincipalTag/job:iam-user

      Match

      		 
      "Condition": {
	"StringEqualsIfExists": {
		"g:PrincipalTag/job": [
			"iam-user"
		]
	}
}
      		 
      g:PrincipalTag/job:admin

      No match

      		 
      "Condition": {
	"StringEqualsIfExists": {
		"g:PrincipalTag/job": [
			"iam-user"
		]
	}
}
      		 
      No g:PrincipalTag/job tag in the request context

      No match
  • Conditions with multiple condition keys or values

    You can use the "Condition" element to write policies that have multiple condition keys or a single condition key with multiple values.

    • Evaluation logic for multiple condition keys or values

      A "Condition" element can contain multiple operators, and each operator can contain multiple key-value pairs of condition keys.

      • If your policy statement has multiple operators, the AND operation logic is used to evaluate these operators.
      • If your policy statement contains multiple condition keys in one operator, the AND operation logic is used to evaluate these condition keys.
      • If a single operator contains multiple values of a condition key, the OR operation logic is used to evaluate these values.
      • If a single operator (for example, StringNotEquals) contains multiple values of a condition key, the NOR operation logic is used to evaluate these values.

      All condition keys in the "Condition" element must be evaluated to true to allow or deny an action.

      The following figure illustrates the evaluation logic with multiple operators and condition key-value pairs.
      Figure 1 Evaluation logic with multiple operators and condition key-value pairs

      For example, the following IAM identity policy illustrates how the preceding evaluation logic is represented in a policy. This condition block contains the condition operator StringEquals and the condition keys g:UserName and g:PrincipalTag/job. All condition keys in the "Condition" element must be evaluated to true for the "Allow" or "Deny" effect.

      This identity policy grants all IAM permissions to users whose username is bob or alice and who have the tag "job":"admin". 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "IAM:*:*"
      ],
      "Condition": {
        "StringEquals": {
          "g:UserName": [
            "bob",
            "alice"
          ],
          "g:PrincipalTag/job": [
            "admin"
          ]
        }
      }
    }
  ]
}
      The following table describes how IAM evaluates identity policies based on the condition key values in the request.
      Table 9 How condition key values are used to evaluate identity policies

      Identity Policy Condition

      Request Context

      Result

      		 
      "Condition": {
	"StringEquals": {
		"g:UserName": [
			"bob",
			"alice"
		],
		"g:PrincipalTag/job": [
			"admin"
		]
	}
}
      		 
      g:UserName: "bob"
g:PrincipalTag/job: "admin"

      Match

      		 
      "Condition": {
	"StringEquals": {
		"g:UserName": [
			"bob",
			"alice"
		],
		"g:PrincipalTag/job": [
			"admin"
		]
	}
}
      		 
      g:UserName: "alice"
The request context does not contain the principal tag.

      No match

      		 
      "Condition": {
	"StringEquals": {
		"g:UserName": [
			"bob",
			"alice"
		],
		"g:PrincipalTag/job": [
			"admin"
		]
	}
}
      		 
      g:UserName: "other-user"
g:PrincipalTag/job: "admin"

      No match

      		 
      "Condition": {
	"StringEquals": {
		"g:UserName": [
			"bob",
			"alice"
		],
		"g:PrincipalTag/job": [
			"admin"
		]
	}
}
      		 
      g:UserName: "alice"
g:PrincipalTag/job: "iam-user"

      No match
    • Evaluation logic of negated operators

      Some operators (such as StringNotEquals or StringNotMatch) compare condition key-value pairs in a policy with context key-value pairs in a request using negated matching. When negated operators are used to specify multiple values for a single condition key in a policy, the negated operators work in a similar way to the NOR logic. In negated matching, IAM compares the context key-value pairs in a request with the condition key-value pairs in a policy one by one. The logical NOR or NOT OR returns true only when all values are false.

      The following figure illustrates how negated operators are evaluated with multiple operators and condition key-value pairs.
      Figure 2 Evaluation logic of negated operators
      The following example describes that the result authentication is true when the requester's username is not in the list corresponding to the negated condition key. 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "IAM:*:*"
      ],
      "Condition": {
        "StringNotEquals": {
          "g:UserName": [
            "alice",
            "bob"
          ]
        }
      }
    }
  ]
}
      The following table describes how IAM evaluates this identity policy based on the condition key values in the request.
      Table 10 How condition key values are used to evaluate this identity policy

      Policy Condition

      Request Context

      Result

      		 
      "Condition": {
	"StringNotEquals": {
		"g:UserName": [
			"alice",
			"bob"
		]
	}
}
      		 
      g:UserName: alice

      No match

      		 
      "Condition": {
	"StringNotEquals": {
		"g:UserName": [
			"alice",
			"bob"
		]
	}
}
      		 
      g:UserName: bob

      No match

      		 
      "Condition": {
	"StringNotEquals": {
		"g:UserName": [
			"alice",
			"bob"
		]
	}
}
      		 
      g:UserName: other-user

      Match
  • Single-valued and multivalued condition keys

    The difference between single-valued and multivalued condition keys depends on the number of values in the request context, not the number of values in the policy condition. To check whether each cloud service supports single-valued or multivalued condition keys:

    Check Actions Supported by Identity Policy-based Authorization. Open the chapter of the specified cloud service and navigate to the "Conditions" section.
    • A single-valued condition key has at most one value in the request context. For example, when you tag a resource in a cloud service, each resource tag is stored as a key-value pair. As a resource tag key can contain only one tag value, g:ResourceTag/key-name is a single-valued condition key.
    • A multivalued condition key has multiple values in the request context. For example, when you tag a resource in a cloud service, you can include multiple tag key-value pairs in the request. Therefore, g:TagKeys is a multivalued condition key.
    Set operators of multivalued condition keys
    • ForAllValues

      Checks whether the value of each member in the request context is a subset of the condition key set. The condition returns true if every key value in the request context matches at least one value in the policy. Note: If the key in the request context is empty, the condition returns true. If the key does not exist in the request context, the condition returns false.

      The following example describes how to allow sharing with the member accounts in any of the following organization paths: orgPath1, orgPath2, and orgPath3. 
      {
    "Version": "5.0",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ims:images:share"
            ],
            "Condition": {
                "ForAllValues:StringEquals": {
                    "ims:TargetOrgPaths": [
                        "orgPath1",
                        "orgPath2",
                        "orgPath3"
                    ]
                }
            }
        }
    ]
}
      The following table describes how IAM evaluates this identity policy based on the key values in the request context.
      Table 11 How key values in the request context are used to evaluate the identity policy

      Policy Condition

      Request Context

      Result

      		 
      "Condition": {
	"ForAllValues:StringEquals": {
		"ims:TargetOrgPaths": [
			"orgPath1",
			"orgPath2",
			"orgPath3"
		]
	}
}
      		 
      ims:TargetOrgPaths: 
orgPath1
orgPath3

      Match

      		 
      "Condition": {
	"ForAllValues:StringEquals": {
		"ims:TargetOrgPaths": [
			"orgPath1",
			"orgPath2",
			"orgPath3"
		]
	}
}
      		 
      ims:TargetOrgPaths:
orgPath1
orgPath2
orgPath3
orgPath4

      No match
    • ForAnyValue

      Tests whether at least one member of the request context 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 context matches any one of the condition values in the policy. If no key value in the request context matches any condition value in the policy, or if no corresponding key exists in the request context, the condition returns false.

      In the following example, the identity policy allows sharing if any organization path of the requesting organization contains elements of orgPath1, orgPath2, or orgPath3. 
      {
    "Version": "5.0",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ims:images:share"
            ],
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "ims:TargetOrgPaths": [
                        "orgPath1",
                        "orgPath2",
                        "orgPath3"
                    ]
                }
            }
        }
    ]
}
      The following table describes how IAM evaluates this identity policy based on the condition key values in the request.
      Table 12 How key values in the request context are used to evaluate the identity policy

      Policy Condition

      Request Context

      Result

      		 
      "Condition": {
	"ForAnyValue:StringEquals": {
		"ims:TargetOrgPaths": [
			"orgPath1",
			"orgPath2",
			"orgPath3"
		]
	}
}
      		 
      ims:TargetOrgPaths:
orgPath1
orgPath4

      Match

      		 
      "Condition": {
	"ForAnyValue:StringEquals": {
		"ims:TargetOrgPaths": [
			"orgPath1",
			"orgPath2",
			"orgPath3"
		]
	}
}
      		 
      ims:TargetOrgPaths:
orgPath4
orgPath5

      No match

Policy Variables

When you write "Resource" or "Condition", you can define dynamic values inside policies by using policy variables that set placeholders in a policy. During authentication, these placeholders are automatically replaced with the values of the conditional context keys passed in the request. Variables are marked using a $ prefix followed by a pair of curly braces ({ }) that include the variable name of the value from the request. For example, the variable ${g:UserName} is automatically replaced with the value of the g:UserName condition key during authentication.

If the condition key specified by the variable fails to be replaced, you can use its default value. To add a default value to a variable, enclose the default value in a pair of single quotation marks (' ') and separate the condition key name from the default value with a comma and space (, ). For example, if the key in ${key, 'default'} does not exist or fails to be replaced, replace the variable with the text string default. Condition key names are case-insensitive, but default values are case-sensitive. Spaces before and after the condition key name and the default value's single quotation marks are ignored. For example, if the principal is an IAM user, ${ g:username , 'Default_User_Name' } will be replaced with the value of g:UserName. For other principals, ${ g:username , 'Default_User_Name' } will be replaced with Default_User_Name.

  • Special characters

    If you want the wildcards (* and ?) and policy variable identifier ($) to be interpreted literally, change them to ${*}, ${?}, and ${$}, respectively. If you want to insert a single quotation mark (') in the default value of a policy variable, use a pair of single quotation marks (''). For example, when you use the default value to replace the variable ${g:UserName, 'A single quote is '', two quotes are ''''.'}, it would be A single quote is ', two quotes are ''.

    The variables are replaced only once. If the replacement still contains variables, they would not be replaced any more. For example, after ${g:UserName, '${g:UserName}${*}'} is replaced with the default value ${g:UserName}${*}, the variables ${g:UserName} and ${*} in the default value would not be replaced again.

  • Using variables
    A variable is a placeholder that can contain dynamic values.

    If the specified conditional context key does not exist in the request or is a multivalued condition key, the replacement fails and the entire statement may be invalid.

    For example, the request contains the g:UserName condition key only when the principal is an IAM user. For other principals, the request does not contain the g:UserName condition key and therefore does not match any resource and condition key that contains ${g:UserName}.

    Similarly, the condition key g:CalledVia cannot be used as a variable because it is a multivalued condition key.

    • Using variables in the Resource element
      In the identity policy preset in the service-linked agency for the Config service, the "iam::${g:DomainId}:agency:rms_tracker_agency_v5" variable is used in the Resource element to specify the trust agency URN of the corresponding account: 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:agencies:attachPolicyV5",
        "iam:agencies:detachPolicyV5"
      ],
      "Resource": [
        "iam::${g:DomainId}:agency:rms_tracker_agency_v5"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PolicyURN": "iam::system:policy:ConfigTrackAgencyPolicy"
        }
      }
    }
  ]
}
    • Using variables in the Condition element
      The following identity policy denies cross-organization access to resources: 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Deny",
      "Action": [
        "*"
      ],
      "Resource": [
        "*"
      ],
      "Condition": {
        "StringNotEquals": {
          "g:ResourceOrgId": "${g:PrincipalOrgId}"
        },
        "Null": {
          "g:ResourceOrgId": "false"
        }
      }
    }
  ]
}
    • Using variables with tags
      By setting the MaxAllowedMfaAge tag for each IAM user, the IAM user can only invoke IAM APIs within the duration specified by MaxAllowedMfaAge after multi-factor authentication. 
      {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:*"
      ],
      "Condition": {
        "NumberLessThanEquals": {
          "g:MFAAge": "${g:PrincipalTag/MaxAllowedMfaAge}"
        }
      }
    }
  ]
}
  • Specifying a default value

    To add a default value to a variable, enclose the default value with a pair of single quotes (' ') and separate the variable text from the default value with a comma and space (, ).

    For example, tag each IAM user with MaxAllowedMfaAge. The following identity policy only allows IAM API access for IAM users who are authenticated with MFA within the number of seconds specified by MaxAllowedMfaAge. If MaxAllowedMfaAge is not specified, 600 seconds are used by default.

    {
  "Version": "5.0",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:*"
      ],
      "Condition": {
        "NumberLessThanEquals": {
          "g:MFAAge": "${g:PrincipalTag/MaxAllowedMfaAge, '600'}"
        }
      }
    }
  ]
}
Parent topic: Policy Reference