Variables

Use Astran Identity and Access Management (IAM) policy variables as placeholders when you don't know the exact value of a resource or condition key when you write the policy.

note

If Astran cannot resolve a variable this might cause the entire statement to be invalid.

Introduction

In IAM policies, many actions allow you to provide a name for the specific resources that you want to control access to. For example, one permissions that the portal needs for the user is iam:SimulatePrincipalPolicy to be able to know if they can perform an action on a specific resource. The following policy allows users to use the iam:SimulatePrincipalPolicy action on any user, so that they can see if can perform a specific action.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iam:SimulatePrincipalPolicy",
      "Resource": "*"
    }
  ]
}

However this is not ideal. Why should any user be able to check the permissions of any other users ? What we need is to only be able to check the permissions of our user. That's where variables come in.

Using variables in policies

You can define dynamic values inside policies by using policy variables that set placeholders in a policy.

Variables are marked using a $ prefix followed by a pair of curly braces ({ }) that include the variable name of the value from the request.

When the policy is evaluated, the policy variables are replaced with values that come from the conditional context keys passed in the request. Variables can be used in identity-based policies. Identity-based policies used as permissions boundaries also support policy variables.

Global condition context keys can be used as variables in requests across Astran services. Service specific condition keys can also be used as variables when interacting with Astran resources, but are only available when requests are made against resources which support them. For a list of context keys available for each Astran service and resource, see the list of actions. Under certain circumstances, you can’t populate global condition context keys with a value. To learn more about each key, see Astran global condition context keys.

caution

• Key names are case-insensitive. For example, aws:username is equivalent to AWS:Username.
• You can use any single-valued condition key as a variable. You can't use a multivalued condition key as a variable.

Let's now fix the example above using the context key aws:PrincipalArn as a variable.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iam:SimulatePrincipalPolicy",
      "Resource": "${aws:PrincipalArn}"
    }
  ]
}

The variable is marked using a $ prefix followed by a pair of curly braces ({ }). Inside the ${ } characters, you can include the name of the value from the request that you want to use in the policy. The values you can use are discussed later on this page.

Where you can use policy variables

You can use policy variables in the Resource element and in comparisons in the Condition value element.

Policy variables with no value

When policy variables reference a condition context key that has no value or is not present in an authorization context for a request, the value is effectively null. There is no equal or like value. Condition context keys may not be present in the authorization context when:

• You are using service specific condition context keys in requests to resources that do not support that condition key.
• Other circumstances as listed for each global condition context key in Astran global condition context keys.

When you use a variable with no value in the condition element of an IAM policy, Condition operators like StringEquals or StringLike do not match, and the policy statement does not take effect.

Inverted condition operators like StringNotEquals or StringNotLike do match against a null value, as the value of the condition key they are testing against is not equal to or like the effectively null value.

Special characters

There are a few special predefined policy variables that have fixed values that enable you to represent characters that otherwise have special meaning. If these special characters are part of the string, you are trying to match and you inserted them literally they would be misinterpreted. For example, inserting an asterisk in the string would be interpreted as a wildcard, matching any characters, instead of as a literal . In these cases, you can use the following predefined policy variables:

• ${} - use where you need an (asterisk) character.
• ${?} - use where you need a ? (question mark) character.
• ${$} - use where you need a $ (dollar sign) character.

These predefined policy variables can be used in any string where you can use regular policy variables.

Specifying default values

To add a default value to a variable, surround the default value with single quotes (' '), and separate the variable text and the default value with a comma (,).

"Resource" : "${aws:username, 'arn:astran:iam::23dfb24b-2132-4d0d-a86e-6cd4c786e57f:user/default-value@astran.io'}"