Single-valued vs. multivalued context keys
The difference between single-valued and multivalued context keys depends on the number of values in the request context, not the number of values in the policy condition.
-
Single-valued condition context keys have at most one value in the request context. For example, you can tag resources in Amazon. Resource tags are stored as tag key-value pairs. A resource tag key can have a single tag value. Therefore, aws:ResourceTag/tag-key is a single-valued context key. Do not use a condition set operator with a single-valued context key.
-
Multivalued condition context keys can have multiple values in the request context. For example, you can tag resources in Amazon and include multiple tag key-value pairs in a request. Therefore, aws:TagKeys is a multivalued context key. Multivalued context keys require a condition set operator.
Important
Multivalued context keys require a condition set operator. Do not use condition set
operators ForAllValues
or ForAnyValue
with single-valued
context keys. To learn more about condition set operators, see Multivalued
context keys.
The Single-valued and Multivalued
classifications are included in the description of each condition context key as
Value type in the Amazon global condition context
keys topic. The Service Authorization Reference uses a different value type classification for
multivalued context keys in the following format: an ArrayOf
prefix followed by
the condition operator category type. For example, ArrayOfString
or
ArrayOfARN
.
You can use any available single-valued context key as a policy variable. You cannot use a multivalued context key as a policy variable. For more information about policy variables, see IAM policy elements: Variables and tags.
Multivalued context keys require condition set operators ForAllValues
or
ForAnyValue
. Context keys that include key-value pairs such as aws:RequestTag/tag-key and aws:ResourceTag/tag-key
can cause confusion because there can be multiple
values. But since each
tag-key
can have only one value,
tag-key
aws:RequestTag
and aws:ResourceTag
are both single-valued
context keys. Using condition set operators with single-valued context keys can lead to
overly permissive policies.
Multivalued context keys
To compare your condition context key against a request context key with multiple values, you must use the
ForAllValues
or ForAnyValue
set operators. These set operators
are used to compare two sets of values, such as the set of tags in a request and the set of
tags in a policy condition.
The ForAllValues
and ForAnyValue
qualifiers add set-operation
functionality to the condition operator so that you can test request context keys with
multiple values against multiple context key values in a policy condition. Additionally, if
you include a multivalued string context key in your policy with a wildcard or a variable,
you must also use the StringLike
condition operator. Multiple condition key values
must be enclosed in brackets like an array. For
example, "Key2":["Value2A", "Value2B"]
.
-
ForAllValues
– This qualifier tests whether the value of every member of the request set is a subset of the condition context key set. The condition returns true if every context key value in the request matches at least one context key value in the policy. It also returns true if there are no context keys in the request, or if the context key value resolves to a null dataset, such as an empty string. To prevent missing context keys or context keys with empty values from evaluating to true, you can include the Null condition operator in your policy with a false value to check if the context key exists and its value is not null.Important
Use caution if you use
ForAllValues
with anAllow
effect because it can be overly permissive if the presence of missing context keys or context keys with empty values in the request context is unexpected. You can include theNull
condition operator in your policy with a false value to check if the context key exists and its value is not null. For an example, see Controlling access based on tag keys. -
ForAnyValue
– This qualifier tests whether at least one member of the set of request context key values matches at least one member of the set of context key values in your policy condition. The context key returns true if any one of the context key values in the request matches any one of the context key values in the policy. For no matching context key or a null dataset, the condition returns false.
Note
The difference between single-valued and multivalued context keys depends on the number of values in the request context, not the number of values in the policy condition.