AWS IAM documentation change
Summary
Expanded documentation about policy evaluation logic with new PARC model explanation, detailed request context components, and example scenarios
Security assessment
The changes enhance documentation about policy evaluation mechanics and security controls (like permissions boundaries/RCPs) but do not address a specific vulnerability. The PARC model explanation helps users design secure policies but is a general documentation improvement.
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_evaluation-logic_policy-eval-reqcontext.md b/IAM/latest/UserGuide/reference_policies_evaluation-logic_policy-eval-reqcontext.md index 25ddd9b5b..a749c82cc 100644 --- a//IAM/latest/UserGuide/reference_policies_evaluation-logic_policy-eval-reqcontext.md +++ b//IAM/latest/UserGuide/reference_policies_evaluation-logic_policy-eval-reqcontext.md @@ -4,0 +5,2 @@ +Understanding the PARC modelImportance of the request contextHow AWS uses the request contextExample policy evaluation using the PARC model + @@ -7 +9 @@ -AWS processes the request to gather the following information into a _request context_ : +When AWS evaluates and authorizes a request, it assembles the request information into a _request context_. The request context contains any information that can be used in policy evaluation. @@ -9 +11 @@ AWS processes the request to gather the following information into a _request co - * **Actions** – The actions that the principal wants to perform. + * **Principal** – The user, role, or federated user that sent the request. Information about the principal includes the policies that are associated with that principal. @@ -11 +13 @@ AWS processes the request to gather the following information into a _request co - * **Resources** – The AWS resource object upon which the actions or operations are performed. + * **Actions** – One or more actions that the principal wants to perform. @@ -13 +15,3 @@ AWS processes the request to gather the following information into a _request co - * **Principal** – The user, role, or federated user that sent the request. Information about the principal includes the policies that are associated with that principal. + * **Resources** – One or more AWS resource objects upon which the actions or operations are performed. + + * **Resource data** – Data related to the resource that is being requested. This can include information such as a DynamoDB table name or a tag on an Amazon EC2 instance. @@ -17 +20,0 @@ AWS processes the request to gather the following information into a _request co - * **Resource data** – Data related to the resource that is being requested. This can include information such as a DynamoDB table name or a tag on an Amazon EC2 instance. @@ -20,0 +24,37 @@ AWS processes the request to gather the following information into a _request co +This information is compared against applicable policies to determine whether to allow or deny the request. You can organize this property information using the **Principal** , **Action** , **Resource** , and **Condition** (PARC) model to better understand how AWS policies are evaluated. + +## Understanding the PARC model + +The PARC model represents the request context based on the four JSON elements in the policy language: + + * [Principal](./reference_policies_elements_principal.html) – The entity making the request. A principal represents a human user or programmatic workload that can be authenticated and then authorized to perform actions in AWS accounts. + + * [Action](./reference_policies_elements_action.html) – The operation being performed. Often the action will map to an API action. + + * [Resource](./reference_policies_elements_resource.html) – The AWS resource on which the action is being performed. + + * [Condition](./reference_policies_elements_condition.html) – Additional constraints that must be met for the request to be allowed. + + + + +The following shows an example of how the PARC model might represent a request context: + + + Principal: AIDA123456789EXAMPLE + Action: s3:CreateBucket + Resource: arn:aws:s3:::amzn-s3-demo-bucket1 + Context: + - aws:UserId=AIDA123456789EXAMPLE:BobsSession + - aws:PrincipalAccount=123456789012 + - aws:PrincipalOrgId=o-example + - aws:PrincipalARN=arn:aws:iam::AIDA123456789EXAMPLE:role/HR + - aws:MultiFactorAuthPresent=true + - aws:CurrentTime=... + - aws:EpochTime=... + - aws:SourceIp=... + - aws:PrincipalTag/dept=123 + - aws:PrincipalTag/project=blue + - aws:RequestTag/dept=123 + +## Importance of the request context @@ -22 +62 @@ AWS processes the request to gather the following information into a _request co -AWS then uses this information to find policies that apply to the request context. +Understanding the request context and how it interacts with policy evaluation is crucial for: @@ -24 +64 @@ AWS then uses this information to find policies that apply to the request contex -How AWS evaluates policies depends on the types of policies that apply to the request context. The following policy types, listed in order of frequency, are available for use within a single AWS account. For more information about these policy types, see [Policies and permissions in AWS Identity and Access Management](./access_policies.html). To learn how AWS evaluates policies for cross-account access, see [Cross-account policy evaluation logic](./reference_policies_evaluation-logic-cross-account.html). + * Troubleshooting access issues @@ -26 +66,29 @@ How AWS evaluates policies depends on the types of policies that apply to the re - * **AWS Organizations resource control policies (RCPs)** – AWS Organizations RCPs specify the maximum available permissions for resources within accounts in an organization or organizational unit (OU). RCPs apply to resources in member accounts and impact the effective permissions for principals, including the AWS account root user, regardless of whether the principals belong to your organization. RCPs don't apply to resources in the organization management account and to calls made by service-linked roles. + * Designing effective and secure policies + + * Understanding the full scope of permissions granted by a policy + + * Predicting the outcome of policy evaluations in different scenarios + + + + +By visualizing the request context using the PARC model, you can more easily understand how AWS makes authorization decisions and design your policies more effectively. + +## How AWS uses the request context + +When evaluating policies, AWS compares the information in the request context with the information specified in all applicable policies. This includes identity-based policies, resource-based policies, IAM permissions boundaries, Organizations SCPs, Organizations RCPs, and session policies. + +For each policy type, AWS uses the request context to check: + + * Whether the policy applies to the request based on the principal. + + * Whether the requested action is allowed on the specified resource. + + * Whether any conditions specified in the policy are met by the request context. + + + + +How AWS evaluates policies depends on the types of policies that apply to the request context. These policy types are available for use within a single AWS account. For more information about these policy types, see [Policies and permissions in AWS Identity and Access Management](./access_policies.html). To learn how AWS evaluates policies for cross-account access, see [Cross-account policy evaluation logic](./reference_policies_evaluation-logic-cross-account.html). + + * **AWS Organizations resource control policies (RCPs)** – AWS Organizations RCPs specify the maximum available permissions for resources within accounts in an organization or organizational unit (OU). RCPs apply to resources in member accounts and impact the effective permissions for principals, including the AWS account root user, regardless of whether the principals belong to your organization. RCPs don't apply to resources in the organization management account and to calls made by service-linked roles. If an RCP is present, permissions granted by identity-based and resource-based policies to resources in your member accounts are only effective if the RCP allows the action. @@ -32 +100 @@ How AWS evaluates policies depends on the types of policies that apply to the re - * **IAM permissions boundaries** – Permissions boundaries are a feature that sets the maximum permissions that an identity-based policy can grant to an IAM entity (user or role). When you set a permissions boundary for an entity, the entity can perform only the actions that are allowed by both its identity-based policies and its permissions boundary. In some cases, an implicit deny in a permissions boundary can limit the permissions granted by a resource-based policy. For more information, see [How AWS enforcement code logic evaluates requests to allow or deny access](./reference_policies_evaluation-logic_policy-eval-denyallow.html). + * **Permissions boundaries** – Permissions boundaries are a feature that sets the maximum permissions that an identity-based policy can grant to an IAM entity (user or role). When you set a permissions boundary for an entity, the entity can perform only the actions that are allowed by both its identity-based policies and its permissions boundary. In some cases, an implicit deny in a permissions boundary can limit the permissions granted by a resource-based policy. For more information, see [How AWS enforcement code logic evaluates requests to allow or deny access](./reference_policies_evaluation-logic_policy-eval-denyallow.html). @@ -46,0 +115,137 @@ Remember, an explicit deny in any of these policies overrides the allow. +## Example policy evaluation using the PARC model + +To illustrate how the request context interacts with policy evaluation, let's consider an example policy: + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:CreateBucket", + "Resource": "arn:aws:s3:::amzn-s3-demo-bucket1", + "Condition": { + "StringEquals": { + "aws:PrincipalTag/dept": "123" + } + } + } + ] + } + +In this example, the policy would allow the `CreateBucket` action only when the request context includes an aws:PrincipalTag/dept value of "123" and the resource matches the `amzn-s3-demo-bucket1` bucket name. The following table shows how AWS uses the request context to evaluate this policy and make authorization decisions. + +Policy | Request context | Evaluation result +---|---|--- + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:CreateBucket", + "Resource": "arn:aws:s3:::amzn-s3-demo-bucket1", + "Condition": { + "StringEquals": { + "aws:PrincipalTag/dept": "123" + } + } + } + ] + } + +| + + + Principal: AIDA123456789EXAMPLE + Action: s3:CreateBucket + Resource: arn:aws:s3:::amzn-s3-demo-bucket1 + Context: + - aws:PrincipalTag/dept=123 + +| **Match** + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:CreateBucket", + "Resource": "arn:aws:s3:::amzn-s3-demo-bucket1", + "Condition": { + "StringEquals": { + "aws:PrincipalTag/dept": "123" + } + } + } + ] + } + +| + + + Principal: AIDA123456789EXAMPLE + Action: s3:DeleteBucket + Resource: arn:aws:s3:::amzn-s3-demo-bucket1 + Context: + - aws:PrincipalTag/dept=123 + +| **No match** + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:CreateBucket", + "Resource": "arn:aws:s3:::amzn-s3-demo-bucket1", + "Condition": { + "StringEquals": { + "aws:PrincipalTag/dept": "123" + } + } + } + ] + }