Policy Variables

Introduction

When creating a custom policy, you can use policy variables as placeholders in the Resource or Condition element of a statement. When the policy is evaluated, these placeholders are automatically replaced with the values of the conditional context keys passed in the request.

Policy Variable Syntax and Replacement Rules

Policy variables are marked using a $ prefix followed by a pair of curly braces ({ }). In the curly braces ({ }), enter the name of the target conditional context key passed in the request, for example, ${g:UserName}. When the policy is evaluated, ${g:UserName} is automatically replaced with the value of the g:UserName condition key.

You can use a policy variable for Condition values in any position. The variable for the Resource element must appear in the fifth part separated by colons (:), for example, OBS:*:*:bucket:${g:UserName}.

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, a multivalued condition key (one condition key has multiple values) fails to be replaced even if it exists in the request context.

If the condition key specified by the variable fails to be replaced, you can use its original text string as the 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, ${key, 'default'} will be replaced with 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.

If you want the dollar sign ($), which identifies a policy variable, to be interpreted literally, use ${$}. 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 ${g:UserName, 'A single quote is '', two quotes are ''''.'} is replaced with the default value, it would be A single quote is ', two quotes are ''.

Policy variables are replaced only once. If the replacement still contains variables, they would not be replaced anymore. For example, when ${g:UserName, '${g:UserName}'} is replaced with the default value, it would be ${g:UserName}. The ${g:UserName} would not be replaced again.

Policy Variable Replacement Failures

Policy variables will fail to be replaced in the following scenarios:

• The variable does not exist in the request context, for example, "${g:UserName}" will fail to be resolved for non-IAM user logins.
• The variable identifier is invalid, for example, "${foo" or "${foo, 'default'".
• The default value in the variable is invalid, for example, ${key, value}, ${foo, 'default}, or ${foo, 'default''}.
• The variable is empty, for example, ${}, ${ }, or ${ }.
• The variable contains spaces, for example, ${g:user id}.
• There is variable nesting, for example, ${var1${var2}}.

Examples of Using Policy Variables

• Using variables in the Resource element
  • In the following policy, if you log in as IAM user test_user_name (the value of g:UserName), you are allowed to perform action obs:bucket:CreateBucket on OBS bucket OBS:*:*:bucket:test_user_name ("*" is a wildcard character).

    {
    	"Version": "1.1",
    	"Statement": [{
    		"Effect": "Allow",
    		"Action": [
    			"obs:bucket:CreateBucket"
    		],
    		"Resource": [
    			"OBS:*:*:bucket:${g:UserName}"
    		]
    	}]
    }

  • In the following policy, if you log in as IAM user test_user_name (the value of g:UserName), you are allowed to perform action obs:bucket:CreateBucket on OBS bucket OBS:*:*:bucket:prefix_test_user_name_suffix ("*" is a wildcard character).

    {
    	"Version": "1.1",
    	"Statement": [{
    		"Effect": "Allow",
    		"Action": [
    			"obs:bucket:CreateBucket"
    		],
    		"Resource": [
    			"OBS:*:*:bucket:prefix_${g:UserName}_suffix"
    		]
    	}]
    }

• Using variables in the Condition element
  In the following policy, if you log in as IAM user test_user_name (the value of g:UserName), you are allowed to perform action iam:agencies:getAgency.

  {
  	"Version": "1.1",
  	"Statement": [{
  		"Effect": "Allow",
  		"Action": [
  			"iam:agencies:getAgency"
  		],
  		"Condition": {
  			"StringEquals": {
  				"g:UserName": [
  					"${g:UserName}"
  				]
  			}
  		}
  	}]
  }