AWS IAM documentation change
Summary
Restructured documentation with added examples, policy samples, and clarification about multivalued context key usage. Added detailed explanations of ForAllValues/ForAnyValue operators with tag key examples and evaluation tables.
Security assessment
The changes clarify proper use of condition set operators to prevent overly permissive policies (e.g., explicit warning about using ForAllValues with Allow effects). Added security best practice guidance about using Null checks to verify context key existence. However, there is no evidence of addressing a specific active vulnerability.
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.md b/IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.md index 674ba4768..1f24dc4c3 100644 --- a//IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.md +++ b//IAM/latest/UserGuide/reference_policies_condition-single-vs-multi-valued-context-keys.md @@ -5 +5 @@ -Multivalued context keys +Key pointsSet operators for multivalued context keys @@ -17,0 +18,2 @@ The difference between single-valued and multivalued context keys lies in the nu +For example, a request can originate from at most one VPC endpoint, so [aws:SourceVpce](./reference_policies_condition-keys.html#condition-keys-sourcevpce) is a single-valued context key. Since a service can have more than one service principal name that belongs to the service, [aws:PrincipalServiceNamesList](./reference_policies_condition-keys.html#condition-keys-principalservicenameslist) is a multivalued context key. + @@ -20 +22,3 @@ The difference between single-valued and multivalued context keys lies in the nu -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 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. + +## Key points @@ -22 +26,13 @@ Multivalued context keys require a condition set operator. Do not use condition -The _Single-valued_ and _Multivalued_ classifications are included in the description of each condition context key as _Value type_ in the [AWS global condition context keys](./reference_policies_condition-keys.html) topic. The [Service Authorization Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) uses a different value type classification for multivalued context keys, using an `ArrayOf` prefix followed by the condition operator category type, such as `ArrayOfString` or `ArrayOfARN`. + * The _Single-valued_ and _Multivalued_ classifications are included in the description of each condition context key as _Value type_ in the [AWS global condition context keys](./reference_policies_condition-keys.html) topic. + + * Multivalued context keys in the [Service Authorization Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) use an `ArrayOf` prefix followed by the condition operator category type, such as `ArrayOfString` or `ArrayOfARN`, indicating that the request may include multiple values for a condition context key. + + * You can use any available single-valued context key as a policy variable, but you cannot use a multivalued context key as a policy variable. For more information about policy variables, see [IAM policy elements: Variables and tags](./reference_policies_variables.html). + + * When using context keys that include key-value pairs, it's important to note that even though there can be multiple tag-key values, each `tag-key` can have only one value. + + * [aws:PrincipalTag/tag-key](./reference_policies_condition-keys.html#condition-keys-principaltag), [aws:RequestTag/tag-key](./reference_policies_condition-keys.html#condition-keys-requesttag) and [aws:ResourceTag/tag-key](./reference_policies_condition-keys.html#condition-keys-resourcetag) are single-valued context keys. + + * [aws:TagKeys](./reference_policies_condition-keys.html#condition-keys-tagkeys) defines what tag-keys are allowed in a request but does not include the tag-key values. Because you can include multiple tag key-value pairs in a request, `aws:TagKeys` is a multivalued context key. + + * Multivalued context keys require a condition set operator. Do not use condition set operators `ForAllValues` or `ForAnyValue` with single-valued context keys. Using condition set operators with single-valued context keys can lead to overly permissive policies. @@ -24 +39,0 @@ The _Single-valued_ and _Multivalued_ classifications are included in the descri -For example, a request can originate from at most one VPC endpoint, so [aws:SourceVpce](./reference_policies_condition-keys.html#condition-keys-sourcevpce) is a single-valued context key. Since a service can have more than one service principal name that belongs to the service, [aws:PrincipalServiceNamesList](./reference_policies_condition-keys.html#condition-keys-principalservicenameslist) is a multivalued context key. @@ -26 +40,0 @@ For example, a request can originate from at most one VPC endpoint, so [aws:Sour -You can use any available single-valued context key as a policy variable, but you cannot use a multivalued context key as a policy variable. For more information about policy variables, see [IAM policy elements: Variables and tags](./reference_policies_variables.html). @@ -28 +41,0 @@ You can use any available single-valued context key as a policy variable, but yo -When using context keys that include key-value pairs, it's important to note that even though there can be multiple tag-key values, each ``tag-key`` can have only one value. Therefore, `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. @@ -30 +43 @@ When using context keys that include key-value pairs, it's important to note tha -## Multivalued context keys +## Set operators for multivalued context keys @@ -36 +49,3 @@ The `ForAllValues` and `ForAnyValue` qualifiers add set-operation functionality - * `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](./reference_policies_elements_condition_operators.html#Conditions_Null) condition operator in your policy with a `false` value to check if the context key exists and its value is not null. +### ForAllValues + +The `ForAllValues` qualifier tests whether the value of every member of the request context matches the condition operator that follows the qualifier. The condition returns `true` if every context key value in the request matches a context key value in the policy. It also returns `true` if there are no context keys in the request. @@ -40 +55 @@ The `ForAllValues` and `ForAnyValue` qualifiers add set-operation functionality -Use caution if you use `ForAllValues` with an `Allow` effect, as 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 the `Null` 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](./access_tags.html#access_tags_control-tag-keys). +Use caution if you use `ForAllValues` with an `Allow` effect, as it can be overly permissive if the presence of missing context keys in the request context is unexpected. You should always include the [Null](./reference_policies_elements_condition_operators.html#Conditions_Null) 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](./access_tags.html#access_tags_control-tag-keys). @@ -42 +57 @@ Use caution if you use `ForAllValues` with an `Allow` effect, as it can be overl - * `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`. +#### Example ForAllValues set operator @@ -43,0 +59 @@ Use caution if you use `ForAllValues` with an `Allow` effect, as it can be overl +In the following example, ForAllValues is used with aws:TagKeys to allow users to delete specific tags assigned to an EC2 instance. This policy allows users to delete only the `environment` and `cost-center` tags. You can delete them separately or together. The tag-keys in the request must match exactly the specified keys in the policy. @@ -45,0 +62,18 @@ Use caution if you use `ForAllValues` with an `Allow` effect, as it can be overl + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "ec2:DeleteTags", + "Resource": "arn:aws:ec2:us-east-1:account-id:instance/*", + "Condition": { + "ForAllValues:StringEquals": { + "aws:TagKeys": ["environment","cost-center"] + }, + "Null": { + "aws:TagKeys": "false" + } + } + } + ] + } @@ -47 +81 @@ Use caution if you use `ForAllValues` with an `Allow` effect, as it can be overl -###### Note +The following table shows how AWS evaluates this policy based on the condition key values in your request. @@ -49 +83,221 @@ Use caution if you use `ForAllValues` with an `Allow` effect, as it can be overl -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. +Policy Condition | Request Context | Result +---|---|--- + + + "ForAllValues:StringEquals": { + "aws:TagKeys": [ + "environment", + "cost-center" + ] + }, + "Null": { + "aws:TagKeys": "false" + } + +| + + + aws:TagKeys: + – environment + +| **Match** + + + "ForAllValues:StringEquals": { + "aws:TagKeys": [ + "environment", + "cost-center" + ] + }, + "Null": { + "aws:TagKeys": "false" + } + +| + + + aws:TagKeys: + – cost-center + +| **Match** + + + "ForAllValues:StringEquals": { + "aws:TagKeys": [ + "environment", + "cost-center" + ] + }, + "Null": { + "aws:TagKeys": "false" + } + +| + + + aws:TagKeys: + – environment + – cost-center + +| **Match** + + + "ForAllValues:StringEquals": { + "aws:TagKeys": [ + "environment", + "cost-center" + ] + }, + "Null": { + "aws:TagKeys": "false" + } + +| + + + aws:TagKeys: + – environment + – dept + +| **No match** + + + "ForAllValues:StringEquals": { + "aws:TagKeys": [ + "environment", + "cost-center" + ] + }, + "Null": { + "aws:TagKeys": "false" + } + +| No `aws:TagKeys` in the request context. | **No match** + +Note that in the last example, the result is "No Match" because the Null condition check prevents matching when the context key is missing. This is a best practice to avoid overly permissive policies. + +### ForAnyValue + +The `ForAnyValue` 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 condition 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 if the key does not exist, the condition returns `false`. + +###### Important + +When using `ForAnyValue` with a `Deny` effect, if the context key is not present in the request, the policy evaluates as **No match**. For consistent behavior, add an explicit [Null](./reference_policies_elements_condition_operators.html#Conditions_Null) condition check in your policy to verify whether the context key exists. For details, see [Condition operator to check existence of condition keys ](./reference_policies_elements_condition_operators.html#Conditions_Null). + +#### Example ForAnyValue set operator + +In the following example, ForAnyValue is used with aws:TagKeys to allow users to delete specific tags assigned to an EC2 instance. This policy allows users to delete tags for an instance if the tag keys specified in the request include `environment` or `cost-center`. The request can include additional tag keys beyond those specified in the policy, but must include at least one of the specified keys to match the condition. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "ec2:DeleteTags", + "Resource": "arn:aws:ec2:us-east-1:account-id:instance/*", + "Condition": { + "ForAnyValue:StringEquals": { + "aws:TagKeys": ["environment","cost-center"] + } + } + } + ] + }