AWS IAM medium security documentation change
Summary
Expanded explanation of request context evaluation with a concrete MFA policy example and added guidance about null/missing context keys
Security assessment
The change adds explicit documentation about security-critical MFA policy enforcement (aws:MultiFactorAuthAge) and addresses potential security misconfigurations with ForAllValues/Null operator handling. The note about preventing missing keys from evaluating to true directly addresses a security-relevant policy evaluation edge case.
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_elements_condition.md b/IAM/latest/UserGuide/reference_policies_elements_condition.md index 06543f619..3b2a39b6b 100644 --- a//IAM/latest/UserGuide/reference_policies_elements_condition.md +++ b//IAM/latest/UserGuide/reference_policies_elements_condition.md @@ -54 +54 @@ As a best practice, make sure that members of your account follow a consistent n -When a [principal](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#principal) makes a [request](./intro-structure.html#intro-structure-request) to AWS, AWS gathers the request information into a request context. The information is used to evaluate and authorize the request. You can use the `Condition` element of a JSON policy to test specific context keys against the request context. For example, you can create a policy that uses the [aws:CurrentTime](./reference_policies_condition-keys.html#condition-keys-currenttime) context key to [allow a user to perform actions within only a specific range of dates](./reference_policies_examples_aws-dates.html). +When a [principal](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#principal) makes a [request](./intro-structure.html#intro-structure-request) to AWS, AWS gathers the request information into a request context. The request context includes information about the principal, resources, actions, and other environmental properties. Policy evaluation matches the properties in the policy against the properties sent in the request to evaluate and authorize actions you can perform in AWS. @@ -56 +56,20 @@ When a [principal](https://docs.aws.amazon.com/glossary/latest/reference/glos-ch -When a request is submitted, AWS evaluates each context key in the policy and returns a value of _true_ , _false_ , _not present_ , and occasionally _null_ (an empty data string). A context key that is not present in the request is considered a mismatch. For example, the following policy allows removing your own multi-factor authentication (MFA) device, but only if you have signed in using MFA in the last hour (3,600 seconds). +You can use the `Condition` element of a JSON policy to test specific context keys against the request context. For example, you can create a policy that uses the [aws:CurrentTime](./reference_policies_condition-keys.html#condition-keys-currenttime) context key to [allow a user to perform actions within only a specific range of dates](./reference_policies_examples_aws-dates.html). + +The following example shows a represdentation of the request context when Martha Rivera sends a request to deactivate her MFA device. + + + Principal: AROA123456789EXAMPLE + Action: **iam:DeactivateMFADevice** + Resource: **arn:aws:iam::user/martha_rivera** + Context: + – aws:UserId=AROA123456789EXAMPLE:martha_rivera + – aws:PrincipalAccount=1123456789012 + – aws:PrincipalOrgId=o-example + – aws:PrincipalARN=arn:aws:iam::1123456789012:assumed-role/TestAR + – aws:MultiFactorAuthPresent=true + – **aws:MultiFactorAuthAge=2800** + – aws:CurrentTime=... + – aws:EpochTime=... + – aws:SourceIp=... + +The request context is matched aginst a policy that allows users to remove their own multi-factor authentication (MFA) device, but only if they have signed in using MFA in the last hour (3,600 seconds). @@ -73,0 +93,4 @@ When a request is submitted, AWS evaluates each context key in the policy and re +In this example, the policy matches the request context: the action is the same, the resource matches the “*” wildcard, and the value for `aws:MultiFactorAuthAge` is 2800, which is less than 3600, so the policy allows this authorization request. + +AWS evaluates each context key in the policy and returns a value of _true_ or _false_. A context key that is not present in the request is considered a mismatch. + @@ -82 +104,0 @@ The request context can return the following values: - * **Null** – For context keys that are defined by the user, such as passing tags in a request, it is possible to include an empty string. In this case, the value in the request context is _null_. A null value might return true in some cases. For example, if you use the multivalued `[ForAllValues](./reference_policies_condition-single-vs-multi-valued-context-keys.html#reference_policies_condition-multi-valued-context-keys)` condition operator with the `[aws:TagKeys](./reference_policies_condition-keys.html#condition-keys-tagkeys)` context key, you can experience unexpected results if the request context returns _null_. For more information, see [aws:TagKeys](./reference_policies_condition-keys.html#condition-keys-tagkeys) and [Multivalued context keys](./reference_policies_condition-single-vs-multi-valued-context-keys.html#reference_policies_condition-multi-valued-context-keys). @@ -85,0 +108,3 @@ The request context can return the following values: +###### Note + +In some cases, when the condition key value is not present, the condition can still return true. For example, if you add the `[ForAllValues](./reference_policies_condition-single-vs-multi-valued-context-keys.html#reference_policies_condition-multi-valued-context-keys)` qualifier, the request returns true if the context key is not in the request. To prevent missing context keys or context keys with empty values from evaluating to true, you can include the [Null condition operator](./reference_policies_elements_condition_operators.html#Conditions_Null) in your policy with a `false` value to check if the context key exists and its value is not null.