aws iam simulate-principal-policy
aws iam simulate-principal-policy --policy-source-arn <user-or-role-arn> --action-names s3:GetObject tells you whether that principal's IAM policies allow the action, without calling the real service. The EvalDecision is allowed, explicitDeny or implicitDeny, and MatchedStatements points to the statement responsible.
What the command does
It runs the IAM policy simulator against the identity-based policies attached to a user, group or role (including those inherited from groups, and the permissions boundary). You name one or more actions and, optionally, resources and condition context keys. Nothing is actually executed, so it is safe for testing destructive permissions such as s3:DeleteBucket.
It answers "do this role's policies allow it?", which is most of the work of debugging AccessDenied errors. It is not a complete replica of a real request; see the gotchas.
Syntax
aws iam simulate-principal-policy \
--policy-source-arn <user|group|role ARN> \
--action-names <service:Action> [...] \
[--resource-arns <arn> ...] \
[--context-entries ContextKeyName=...,ContextKeyValues=...,ContextKeyType=...] \
[--policy-input-list file://extra-policy.json]Worked examples
Can this role read objects in a bucket?
aws iam simulate-principal-policy \
--policy-source-arn arn:aws:iam::123456789012:role/orders-api-task \
--action-names s3:GetObject s3:PutObject \
--resource-arns "arn:aws:s3:::orders-exports/*" \
--query "EvaluationResults[].[EvalActionName,EvalDecision]" --output tableWhy is it denied? Show which statements matched and any missing context:
aws iam simulate-principal-policy \
--policy-source-arn arn:aws:iam::123456789012:role/orders-api-task \
--action-names dynamodb:DeleteItem \
--resource-arns arn:aws:dynamodb:eu-west-2:123456789012:table/orders \
--query "EvaluationResults[0].{decision:EvalDecision,matched:MatchedStatements[].SourcePolicyId,missing:MissingContextValues}"An empty matched with implicitDeny means no statement allows the action. explicitDeny with a matched policy ID tells you exactly which policy to read.
Test a condition, such as a policy that requires MFA or a source IP:
aws iam simulate-principal-policy \
--policy-source-arn arn:aws:iam::123456789012:user/alex \
--action-names ec2:TerminateInstances \
--context-entries ContextKeyName=aws:MultiFactorAuthPresent,ContextKeyValues=true,ContextKeyType=booleanTry a draft policy before attaching it, on top of what the role already has:
aws iam simulate-principal-policy \
--policy-source-arn arn:aws:iam::123456789012:role/orders-api-task \
--policy-input-list file://draft-policy.json \
--action-names sqs:SendMessage \
--resource-arns arn:aws:sqs:eu-west-2:123456789012:ordersReading the result
| EvalDecision | Meaning | Next step |
|---|---|---|
allowed | An identity policy allows it and nothing in scope denies it | If the real call still fails, look at resource policies, SCPs, KMS key policies or session policies |
implicitDeny | No statement allows the action on that resource | Add an Allow, checking the resource ARN format carefully |
explicitDeny | A Deny statement matched | Find it via MatchedStatements; a boundary deny is shown in PermissionsBoundaryDecisionDetail |
Gotchas
- Resource policies are not evaluated unless you supply them with
--resource-policy. An S3 bucket policy denying access will not show up otherwise. - Organizations policies. When the account is in an organisation, results include an
OrganizationsDecisionDetailfield for SCPs; check it before assuming IAM is the problem. See explicit deny in a service control policy. - Session context is missing. Session policies, session tags and the actual source IP of a real request are not known to the simulator unless you pass them as context.
- Wildcard resources by default. Without
--resource-arnsthe simulator uses*, which can reportallowedfor something that is denied on the specific resource you care about. - The caller needs permission too:
iam:SimulatePrincipalPolicy, and the ability to read the target's policies.
Questions
What is the difference between simulate-principal-policy and simulate-custom-policy?
simulate-principal-policy uses the policies already attached to a real user, group or role. simulate-custom-policy evaluates only the policy documents you pass in, with no principal involved.
Can I simulate an SSO permission set?
Yes, indirectly. Find the AWSReservedSSO_ role that the permission set created in the target account and pass its ARN as --policy-source-arn.
Why does the simulator say allowed but the call fails?
Something outside identity policies is denying it: a resource policy, an SCP, a KMS key policy, a VPC endpoint policy, or a session policy. Decode the real error with sts decode-authorization-message if it is encoded.
Permission errors after a deploy are a common out-of-hours page. CloudConsole is built to show the alarms and logs around such failures on a phone, so you can judge whether it can wait until morning.
About the app → · Download on the App Store