IAM Diagnostics
When to use
Any IAM investigation where the console alone is insufficient — access denied root cause analysis, policy evaluation logic, role trust chain debugging, cross-account access, permission boundaries, SCP interactions, federation issues, or credential problems.
Investigation workflow
Step 1 — Collect and triage
aws iam get-user --user-name <user>
aws iam list-attached-user-policies --user-name <user>
aws iam list-user-policies --user-name <user>
aws iam list-groups-for-user --user-name <user>
aws sts get-caller-identity
aws iam simulate-principal-policy --policy-source-arn <arn> --action-names <action> --resource-arns <resource>
Step 2 — Domain deep dive
aws iam get-role --role-name <role>
aws iam get-policy-version --policy-arn <arn> --version-id <version>
aws iam list-role-policies --role-name <role>
aws iam get-account-authorization-details
aws accessanalyzer list-findings --analyzer-arn <arn>
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRole
Read references/iam-guardrails.md before concluding on any IAM issue.
Gotchas: IAM
- Policy evaluation order: explicit Deny → SCP → resource policy → permission boundary → session policy → identity policy. Explicit deny in ANY layer wins.
- IAM policies have a 6,144 character limit (managed) or 10,240 (inline). Complex policies hit this.
- Permission boundaries set the MAXIMUM permissions. They don't grant permissions — identity policies do that. Effective permissions = intersection of boundary and identity policy.
- SCPs don't apply to the management account or service-linked roles.
- Role trust policies control WHO can assume the role. The assuming principal also needs sts:AssumeRole permission.
- Session policies (passed during AssumeRole) further restrict the role's permissions for that session. They don't grant additional permissions.
- IAM changes are eventually consistent. A policy change may take seconds to propagate globally.
- Wildcard (*) in Principal means EVERYONE including anonymous. Use specific account/role ARNs.
- Condition keys are case-sensitive. aws:SourceIp ≠ AWS:sourceip.
- Cross-account role assumption: the trust policy must allow the external account, AND the external account must have sts:AssumeRole permission.
- Service-linked roles are managed by AWS services. You cannot modify their permissions. You can only delete them if the service allows it.
- Access keys should be rotated regularly. Old keys remain active until explicitly deactivated.
- MFA conditions (aws:MultiFactorAuthPresent) don't work with long-term access keys in CLI — only with temporary credentials from STS.
Policy evaluation logic
| Step |
Check |
Effect |
| 1 |
Explicit Deny in any policy |
DENY (final) |
| 2 |
SCP (if in Organization) |
Must ALLOW (or implicit deny) |
| 3 |
Resource-based policy |
Can ALLOW (even without identity policy for same-account) |
| 4 |
Permission boundary |
Must ALLOW (if set) |
| 5 |
Session policy |
Must ALLOW (if set) |
| 6 |
Identity-based policy |
Must ALLOW |
Anti-hallucination rules
- Always cite specific policy documents, API responses, or CloudTrail events as evidence.
- Permission boundaries restrict, they don't grant. Never claim a boundary grants permissions.
- SCPs don't apply to the management account. Never claim SCPs restrict the management account.
- Policy evaluation has a specific order. Never skip layers in the evaluation.
- IAM changes are eventually consistent. Never claim changes are instant.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
30 runbooks
| Category |
IDs |
Covers |
| A — Access Denied |
A1-A4 |
Policy evaluation, explicit deny, implicit deny, resource policy |
| B — Role Issues |
B1-B4 |
Trust policy, cross-account assume, session duration, chained roles |
| C — Policy Management |
C1-C3 |
Policy size limits, policy versioning, managed vs inline |
| D — Permission Boundaries |
D1-D2 |
Boundary conflicts, effective permissions |
| E — SCP Interactions |
E1-E3 |
SCP deny, SCP + IAM evaluation, management account exemption |
| F — Federation |
F1-F3 |
SAML federation, OIDC federation, web identity |
| G — Credentials |
G1-G3 |
Access key rotation, temporary credentials, MFA issues |
| H — Cross-Account |
H1-H3 |
Cross-account roles, resource sharing, confused deputy |
| I — Service Roles |
I1-I2 |
Service-linked roles, service roles |
| Z — Catch-All |
Z1 |
General troubleshooting |
1---2name: iam-diagnostics3description: Use this skill to investigate and troubleshoot AWS IAM problems by analyzing policies, roles, trust relationships, and following structured runbooks. Activate when: access denied errors, policy evaluation confusion, role assumption failures, cross-account access issues, permission boundary conflicts, SCP restrictions, MFA enforcement problems, credential rotation issues, federation failures, service-linked role issues, or the user says something is wrong with IAM without naming specific symptoms.4---56# IAM Diagnostics78## When to use910Any IAM investigation where the console alone is insufficient — access denied root cause analysis, policy evaluation logic, role trust chain debugging, cross-account access, permission boundaries, SCP interactions, federation issues, or credential problems.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws iam get-user --user-name <user>18aws iam list-attached-user-policies --user-name <user>19aws iam list-user-policies --user-name <user>20aws iam list-groups-for-user --user-name <user>21aws sts get-caller-identity22aws iam simulate-principal-policy --policy-source-arn <arn> --action-names <action> --resource-arns <resource>23```2425### Step 2 — Domain deep dive2627```28aws iam get-role --role-name <role>29aws iam get-policy-version --policy-arn <arn> --version-id <version>30aws iam list-role-policies --role-name <role>31aws iam get-account-authorization-details32aws accessanalyzer list-findings --analyzer-arn <arn>33aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRole34```3536Read `references/iam-guardrails.md` before concluding on any IAM issue.3738## Gotchas: IAM3940- Policy evaluation order: explicit Deny → SCP → resource policy → permission boundary → session policy → identity policy. Explicit deny in ANY layer wins.41- IAM policies have a 6,144 character limit (managed) or 10,240 (inline). Complex policies hit this.42- Permission boundaries set the MAXIMUM permissions. They don't grant permissions — identity policies do that. Effective permissions = intersection of boundary and identity policy.43- SCPs don't apply to the management account or service-linked roles.44- Role trust policies control WHO can assume the role. The assuming principal also needs sts:AssumeRole permission.45- Session policies (passed during AssumeRole) further restrict the role's permissions for that session. They don't grant additional permissions.46- IAM changes are eventually consistent. A policy change may take seconds to propagate globally.47- Wildcard (*) in Principal means EVERYONE including anonymous. Use specific account/role ARNs.48- Condition keys are case-sensitive. aws:SourceIp ≠ AWS:sourceip.49- Cross-account role assumption: the trust policy must allow the external account, AND the external account must have sts:AssumeRole permission.50- Service-linked roles are managed by AWS services. You cannot modify their permissions. You can only delete them if the service allows it.51- Access keys should be rotated regularly. Old keys remain active until explicitly deactivated.52- MFA conditions (aws:MultiFactorAuthPresent) don't work with long-term access keys in CLI — only with temporary credentials from STS.5354### Policy evaluation logic5556| Step | Check | Effect |57|------|-------|--------|58| 1 | Explicit Deny in any policy | DENY (final) |59| 2 | SCP (if in Organization) | Must ALLOW (or implicit deny) |60| 3 | Resource-based policy | Can ALLOW (even without identity policy for same-account) |61| 4 | Permission boundary | Must ALLOW (if set) |62| 5 | Session policy | Must ALLOW (if set) |63| 6 | Identity-based policy | Must ALLOW |6465## Anti-hallucination rules66671. Always cite specific policy documents, API responses, or CloudTrail events as evidence.682. Permission boundaries restrict, they don't grant. Never claim a boundary grants permissions.693. SCPs don't apply to the management account. Never claim SCPs restrict the management account.704. Policy evaluation has a specific order. Never skip layers in the evaluation.715. IAM changes are eventually consistent. Never claim changes are instant.726. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.7374## 30 runbooks7576| Category | IDs | Covers |77|----------|-----|--------|78| A — Access Denied | A1-A4 | Policy evaluation, explicit deny, implicit deny, resource policy |79| B — Role Issues | B1-B4 | Trust policy, cross-account assume, session duration, chained roles |80| C — Policy Management | C1-C3 | Policy size limits, policy versioning, managed vs inline |81| D — Permission Boundaries | D1-D2 | Boundary conflicts, effective permissions |82| E — SCP Interactions | E1-E3 | SCP deny, SCP + IAM evaluation, management account exemption |83| F — Federation | F1-F3 | SAML federation, OIDC federation, web identity |84| G — Credentials | G1-G3 | Access key rotation, temporary credentials, MFA issues |85| H — Cross-Account | H1-H3 | Cross-account roles, resource sharing, confused deputy |86| I — Service Roles | I1-I2 | Service-linked roles, service roles |87| Z — Catch-All | Z1 | General troubleshooting |
aws-samples