How do I troubleshoot explicit deny in a service control policy errors?

Short description

You can directly attach multiple Service Control Policies (SCPs) to an AWS Account or inherit the SCPs from Organizational Units (OUs). In these scenarios, it can be difficult to identify what SCP is blocking your operation. For SCPs that cause "Access denied" errors, these errors show an "explicit deny in a service control policy" message, but don't specify the responsible policy.

To identify the specific SCP, you must decode the authorization failure message to extract the policy statement ID. Then, search for that statement across all SCPs in your organization.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Resolution

Identify the SCP denial in the error message

When an SCP blocks an action, you receive an access denied error similar to the following message:

"You are not authorized to perform this operation. User: arn:aws:sts::999888777666:assumed-role/ReadOnly/Tom is not authorized to perform: ec2:RunInstances on resource: arn:aws:ec2:us-east-1:999888777666:instance/* with an explicit deny in a service control policy. Encoded authorization failure message: XQ_jqde5rHje6j9P-qke7-HNpHWzSWvxYobhcCPSpfOmLTkOylRBKd0eE4Xx4U_E_ldKR9tvnBpWYTze099CuiTFCVNOgC0ak83nVxE33wnOdmD-NH2GudDwuySmkEbTiBiMkyr0iRCmQqJMQLVvd0TH_Vx7kqDx1M1yKTRwOs7saSO6e_jTHFziPsTy8AkJF6kx2x0B3ywr7oX78ev9T-ga_dQ_A7m9Xw9a4ebMbzc"

The error message includes an encoded authorization failure message. This encoded message contains details about the policy statement that denied the request.

Decode the authorization failure message

To decode the error message and identify the blocking statement, complete the following steps:

1. Copy the encoded message from your error output.

2. In the Account for the member account where the error occurred, run the following AWS CLI command:

   aws sts decode-authorization-message --encoded-message <ENCODED_MESSAGE> --query DecodedMessage --output text | jq '.'

   The following is an example with an encoded message:

   aws sts decode-authorization-message --encoded-message "XQ_jqde5rHje6j9Pqke7HNpHWzSWvxYobhcCPSpfOmLTkOylRBKd0eE4Xx4U_E_ldKR9tvnBpWYTze099CuiTFCVNOgC0ak83nVxE33wnOd mD... --query DecodedMessage --output text | jq '.'

3. Review the decoded output. Look for the statementId field under matchedStatements:

   {
     "allowed": false,
     "explicitDeny": true,
     "matchedStatements": {
       "items": [
         {
           "statementId": "ExplicitDenyDuetoMissingTags",
           "effect": "DENY",
           "principals": {
             "items": [
               {
                 "value": "AROA5KXXXXXXXGB3Y2W:ReadOnly:Tom"
               }
             ]
           }
         }
       ]
     }
   }

4. Note the statementId value and the conditions that launched the denial. In the preceding example, the statementId value is ExplicitDenyDuetoMissingTags.

Important: The IAM principal that decodes the message must have the sts:DecodeAuthorizationMessage permission.

Locate the SCP in the management account

After you identify the statement ID, complete the following steps:

1. Sign in to the AWS Organizations console in your management account.
2. In the navigation pane, choose Policies, then choose Service control policies.
3. Review the SCPs that are attached to the affected account.
4. Choose AWS accounts.
5. Select the affected account
6. Choose the Policies tab to view attached and inherited SCPs
7. Open each SCP that's attached to your account or inherited from parent OUs.
8. Search for the statementId value that you noted. This SCP with the matching statement ID is the SCP that's causing the denial.

Analyze the blocking statement

After you identify the SCP, review the SCP to determine why the SCP is blocking your action.

Example SCP statement causing the denial

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Deny",
      "Action": [
        "ec2:RunInstances"
      ],
      "Resource": [
        "arn:aws:ec2:*:*:instance/*",
        "arn:aws:ec2:*:*:volume/*"
      ],
      "Condition": {
        "StringNotEquals": {
          "aws:RequestTag/team": "true"
        }
      }

Compare the SCP conditions with the context from your decoded message:

• SCP requirement: The policy requires aws:RequestTag/team to equal "true"
• Your request: Check the decoded message's context section for the aws:RequestTag/team key
• Mismatch identification: If the key is missing from your request context, then you didn't include the tag. If the value is different, such as "false" or "team-a", then the key value doesn't match the required value.

In the preceding example, the following issues cause the error:

• The SCP denies Amazon Elastic Compute Cloud (Amazon EC2) instance launches when the team tag is not set to "true."
• The decoded message shows the request was made without the required tag.
• The condition key "aws:RequestTag/team" was not present in the request context.

Note: It's a best practice to use descriptive statement IDs (Sid) in your SCPs instead of generic names like "Statement1" or "Statement2". Descriptive Sids such as "DenyEC2WithoutTeamTag", "RestrictToApprovedRegions", or "RequireMFAForIAMChanges" make it easier to identify the SCP that blocks an operation.

Related information

Managing organization policies with AWS Organizations

Policy evaluation logic

SCP syntax

Troubleshooting AWS Organizations