How do I troubleshoot "Access Denied" errors in AWS DevOps Agent?

Short description

AWS DevOps Agent uses two AWS Identity and Access Management (IAM) identities. The IAM principal signs you into the console and the Operator Web App. The Agent Space role allows AWS DevOps Agent to discover resources in your AWS account.

To identify where the access issues occurred, check the Amazon Resource Name (ARN) in the error message. If the ARN contains your IAM user or role, then the IAM principal failed. If the ARN contains sourceAssociationRoleSession or monitorAssociationRoleSession, then the Agent Space role failed. After you identify the IAM identity that failed, troubleshoot the issue for that identity based on the error message that you received.

Note: For more information about the IAM managed polices that AWS DevOps Agent uses, see AIDevOpsAgentFullAccess, AIDevOpsOperatorAppAccessPolicy, and AIDevOpsAgentAccessPolicy.

Resolution

"User is not authorized to perform: aidevops:..."

If your IAM principal doesn't have permissions for AWS DevOps Agent, then you receive the "Not authorized" error.

To resolve this issue, attach an AWS managed policy for AWS DevOps Agent to your principal. For instructions, see Adding IAM identity permissions (console).

If the error message includes "No session policy allows the action," then your federated session has a restrictive session policy. Update your AWS IAM Identity Center permission set to include the aidevops: actions from your IAM policy. 

"403 Forbidden" in the Operator Web App

If the operator role doesn't have the required managed policy, or your session expired, then you receive 403 errors.

To resolve expired sessions, open the Agent Space, and then choose the Operator App tab. Choose the Operator Web App link to restart the session. Admin access sessions last only 30 minutes.

If you use IAM Identity Center authentication, then make sure that you added the user or group to the Agent Space.

If the 403 error occurs immediately for any user, then attach the AIDevOpsOperatorAppAccessPolicy managed policy to the operator role.

If the operator role has the managed policy but you still receive 403 errors, then your IAM principal might lack permission to generate a one-time login URL. The AIDevOpsAgentFullAccess policy includes the required aidevops:CreateOneTimeLoginSession action. However, you must manually add the action to custom or read-only policies.

Example policy statement:

{
    "Effect": "Allow",
    "Action": "aidevops:CreateOneTimeLoginSession",
    "Resource": "arn:aws:aidevops:us-east-1:123456789012:agentspace/YOUR-AGENTSPACE-ID"
}

Note: Replace us-east-1 with your AWS Region, 123456789012 with your account, and YOUR-AGENTSPACE-ID with your agent space ID.

"You are not authorized to view this Agent Space" in IAM Identity Center

If you didn't assign your IAM Identity Center user or group to the Agent Space, then you receive the "Not authorized" error message. To resolve this issue, add your user or group to the Agent Space.

If you assigned the user but you still receive errors, then confirm that the operator role has a trust policy with the sts:SetContext action. Also, make sure that the role has a trust policy that allows sts:AssumeRole and sts:TagSession.

Update the operator role's trust policy with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {"Service": "aidevops.amazonaws.com"},
            "Action": ["sts:AssumeRole", "sts:TagSession"],
            "Condition": {
                "StringEquals": {"aws:SourceAccount": "123456789012"},
                "ArnEquals": {"aws:SourceArn": "arn:aws:aidevops:US-EAST-1:123456789012:agentspace/YOUR-AGENTSPACE-ID"}
            }
        },
        {
            "Sid": "TrustedIdentityPropagation",
            "Effect": "Allow",
            "Principal": {"Service": "aidevops.amazonaws.com"},
            "Action": "sts:SetContext",
            "Condition": {
                "StringEquals": {"aws:SourceAccount": "123456789012"},
                "ArnEquals": {"aws:SourceArn": "arn:aws:aidevops:US-EAST-1:123456789012:agentspace/YOUR-AGENTSPACE-ID"},
                "ForAllValues:ArnEquals": {"sts:RequestContextProviders": ["arn:aws:iam::aws:contextProvider/IdentityCenter"]},
                "Null": {"sts:RequestContextProviders": "false"}
            }
        }
    ]
}

Note: Replace 123456789012 with your account ID, US-EAST-1 with your Region, and YOUR-AGENTSPACE-ID with your Agent Space ID.

To allow the operator role to resolve IAM Identity Center users at runtime, confirm that the role has an inline policy with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowDevOpsAgentSSOAccess",
            "Effect": "Allow",
            "Action": ["sso:ListInstances", "sso:DescribeInstance"],
            "Resource": "*"
        },
        {
            "Sid": "AllowDevOpsAgentIDCUserAccess",
            "Effect": "Allow",
            "Action": "identitystore:DescribeUser",
            "Resource": [
                "arn:aws:identitystore::123456789012:identitystore/*",
                "arn:aws:identitystore:::user/*"
            ]
        }
    ]
}

Note: Replace 123456789012 with your account ID.

After you update the trust policy and inline policy, sign out of the Operator Web App. Then, sign in again.

"Capability gap identified"

If the Agent Space role received "Access Denied" errors from an AWS service during resource discovery, then the console displays the "Capability gap identified" banner. This issue occurs if the Agent Space role lacks permission to call APIs in your account.

To resolve this issue, it's a best practice to auto-create a new role. Complete the following steps:

1. Open the AWS DevOps Agent console.
2. Select your Agent Space.
3. Choose the Capabilities tab.
4. Under Cloud, choose the account that has issues.
5. Choose Auto-create a new AWS DevOps Agent role.

The automatically created role uses the latest version of the AIDevOpsAgentAccessPolicy managed policy.

Or, to update an existing custom role to use the AIDevOpsAgentAccessPolicy managed policy, update the role's trust policy with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "aidevops.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {"aws:SourceAccount": "123456789012"},
            "ArnLike": {"aws:SourceArn": "arn:aws:aidevops:US-EAST-1:123456789012:agentspace/*"}
        }
    }]
}

Note: Replace 123456789012 with your account ID and US-EAST-1 with your Region.

If you correctly configured the role but the agent still fails, then a higher-priority policy might block the action. To resolve this issue, review your service control policies (SCPs) and permissions boundaries.

"Access Denied because no session policy allows the action"

If you receive "No session policy" errors after you add a permission to the Agent Space role, then the action isn't in the permission guardrail. The guardrail controls the actions that the agent can perform at runtime, regardless of what the role allows.

The guardrail uses the default AIDevOpsAgentAccessPolicy for its permissions. However, you must add specific read actions to your role's inline policy to use them. You can't add actions that aren't already in the guardrail.

If the resource has its own resource-based policy, then that policy must also grant access to the Agent Space role.

"Not authorized to perform: sts:AssumeRole" during cross-account investigation

If the role in the secondary account doesn't trust the AWS DevOps Agent service principal, then you receive the "Not authorized" error. AWS DevOps Agent directly assumes secondary account roles with aidevops.amazonaws.com.

To resolve this issue, update the trust policy in the secondary account to include the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "aidevops.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {"aws:SourceAccount": "PRIMARY-ACCOUNT-ID"},
            "ArnLike": {"aws:SourceArn": "arn:aws:aidevops:REGION:PRIMARY-ACCOUNT-ID:agentspace/*"}
        }
    }]
}

Note: Replace PRIMARY-ACCOUNT-ID with the Agent Space account's ID and REGION with the Agent Space account's Region.

Also, confirm that the secondary account's role has the AIDevOpsAgentAccessPolicy managed policy attached.

For more information, see Connecting multiple AWS Accounts.

Related information

Setting up IAM Identity Center authentication

Creating an Agent Space

How can I troubleshoot access denied or unauthorized operation errors with an IAM policy?