
I Tried Using IAM Access Troubleshooter to Identify the Policy That Denied Access from the Authorization ID in an AccessDenied Error
This page has been translated by machine translation. View original
Introduction
On November 17, 2026, Access Troubleshooter was added to IAM.
Access Troubleshooter is a feature that attaches a unique identifier (authorization ID) to AccessDenied errors for supported services and APIs. Using this ID, you can retrieve the evaluated policies, the authorization context, and the evaluation results.
In this article, I attached an explicit Deny to a test role to cause a denial, and retrieved the denying policy and the policy document at the time of the denial from the authorization ID.
Prerequisites for the Test
I used AWS CLI 2.41.0. To retrieve the details of an authorization evaluation, I use the aws iam-toolbox subcommand.
According to the IAM User Guide, the credentials used to call the retrieval APIs require the following IAM permissions.
- iam:GetRequestAuthorizationDetails (retrieve the evaluation details)
- iam:GetRequestAuthorizationPolicy (retrieve the policy document)
Reproducing the Denial
Prepare a trust policy and a Deny policy, and create a test role. The Deny policy denies four read APIs, including iam:ListRoles, in a single statement.
trust-policy.json and deny-policy.json
trust-policy.json (replace <ACCOUNT_ID> with your own account ID)
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::<ACCOUNT_ID>:root" },
"Action": "sts:AssumeRole"
}
]
}
deny-policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyReadApis",
"Effect": "Deny",
"Action": [
"sqs:ListQueues",
"ec2:DescribeInstances",
"iam:ListRoles",
"kms:ListKeys"
],
"Resource": "*"
}
]
}
aws iam create-role --role-name access-troubleshooter-test --assume-role-policy-document file://trust-policy.json
aws iam put-role-policy --role-name access-troubleshooter-test --policy-name DenyReadApis --policy-document file://deny-policy.json
Since the Deny is attached to the role, run the command that triggers the denial with the role's temporary credentials.
aws sts assume-role --role-arn arn:aws:iam::<ACCOUNT_ID>:role/access-troubleshooter-test --role-session-name denied-test --duration-seconds 900
I set the returned temporary credentials in the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. When I ran aws iam list-roles in that state, the following AccessDenied error was returned. The authorization ID has been replaced with the example value from the AWS documentation.
aws: [ERROR]: An error occurred (AccessDenied) when calling the ListRoles operation: User: arn:aws:sts::111122223333:assumed-role/access-troubleshooter-test/denied-test is not authorized to perform: iam:ListRoles on resource: arn:aws:iam::111122223333:role/ with an explicit deny in an identity-based policy. Go to https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/authorization-details/EXAMPLE1a2b3c4d5e6f7g8h9i0j for complete details, or call the GetRequestAuthorizationDetails API with the following authorization id: EXAMPLE1a2b3c4d5e6f7g8h9i0j
The policy that denied the request is the role's inline policy. The policy ARN did not appear in the error message.
Retrieving the Authorization Evaluation Details
Unset the temporary credential environment variables to return to the original credentials, then call get-request-authorization-details.
Call the retrieval API in the Region where the denial occurred. This time the console URL in the error message was us-east-1, so I specified --region us-east-1. For <authorization-id>, enter the authorization ID from the error message.
aws iam-toolbox get-request-authorization-details --region us-east-1 --authorization-id <authorization-id>
When I ran this command 5 seconds after the denial, a ResourceNotFoundException was returned. When I re-ran it with the same authorization ID about 1 minute after the denial, it succeeded. The cause of the first exception was not a wrong ID, so if it is returned right after a denial, wait a while and run it again.
The evaluations in the response contained one evaluation for iam:ListRoles, and its evaluatedEffect was EXPLICIT_DENY. This evaluation has 5 checks.
| checkType | Target | evaluatedEffect | Matched policy |
|---|---|---|---|
| SERVICE_CONTROL_POLICY | root | ALLOW | p-FullAWSAccess |
| SERVICE_CONTROL_POLICY | OU | ALLOW | p-FullAWSAccess |
| SERVICE_CONTROL_POLICY | Account | ALLOW | p-FullAWSAccess |
| PRINCIPAL | - | EXPLICIT_DENY | inline:6111414566fd200b |
| SESSION | - | ALLOW | inline:5904601e6713d7c1 |
Because the test account belongs to AWS Organizations, SCP checks are listed.
To identify the denying policy, look for the check whose evaluatedEffect is EXPLICIT_DENY and look at its matchedPolicies. In this case, it is the PRINCIPAL check.
{
"checkType": "PRINCIPAL",
"evaluatedEffect": "EXPLICIT_DENY",
"relevantPolicyTypes": [
"IDENTITY_BASED_POLICY"
],
"matchedPolicies": [
{
"uri": "inline:6111414566fd200b",
"matchedStatements": [
{
"sid": "DenyReadApis",
"evaluatedEffect": "DENY"
}
]
}
]
}
The uri is the identifier of the denying policy, and the sid is the Sid of the denying statement.
The uri of the denying policy is not an ARN but an identifier that AWS assigned to the inline policy. The policies in the response contain an entry with the same uri, and attachedTo tells you which role it is attached to.
{
"type": "IDENTITY_BASED_POLICY",
"inline": true,
"uri": "inline:6111414566fd200b",
"attachedTo": [
{
"arn": "arn:aws:iam::111122223333:role/access-troubleshooter-test"
}
]
}
Retrieving the Policy Document at the Time of the Denial
Pass the authorization ID and the uri from policies to get-request-authorization-policy. For <policy-uri>, enter the uri of the denying policy (in this case, inline:6111414566fd200b).
aws iam-toolbox get-request-authorization-policy --region us-east-1 --authorization-id <authorization-id> --policy-uri <policy-uri>
{
"policyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyReadApis",
"Effect": "Deny",
"Action": [
"sqs:ListQueues",
"ec2:DescribeInstances",
"iam:ListRoles",
"kms:ListKeys"
],
"Resource": "*"
}
]
}
}
The policyDocument had the same content as the deny-policy.json I attached to the role.
Summary
Access Troubleshooter is a feature that lets you retrieve the evaluated policies, the result of each check, and the policy document at the time of the denial, from the authorization ID attached to an AccessDenied error.
For the explicit Deny on iam:ListRoles, I was able to identify the denying inline policy and the statement's Sid from the PRINCIPAL check.
When an IAM access denial occurs, if you can identify the authorization ID returned to the client side from the error message and so on, you may be able to investigate the cause efficiently with IAM Access Troubleshooter. Please give it a try.
