Solving the Misleading 'User is not authorized' Error in AWS CodeBuild

The Misleading “User is not authorized to access connection” Error in AWS CodeBuild — and Why Your IAM Policy Looks Fine

AWS CodeBuild triggers an OAuthProviderException when pulling source from GitHub via CodeConnections. The error misleadingly blames the API caller instead of the CodeBuild service role.

Why This Matters

The technical reality of this error involves undocumented permission requirements and silent failures due to resource-level scoping restrictions. While engineers expect a standard IAM denial, AWS surfaces a generic provider exception that masks whether the failure is due to a missing action or an invalid resource scope, leading to prolonged debugging sessions.

Key Insights

• The ‘User’ referenced in the OAuthProviderException is actually the CodeBuild service role, not the IAM principal making the API call (Morgan Wowk, 2026).
• Undocumented permission requirements exist where codestar-connections:GetConnectionToken must be granted alongside UseConnection for UpdateProject to succeed.
• Resource-level scoping fails for specific list actions—ListConnections, ListInstallationTargets, and ListTagsForResource—which require resources: [’*’] to function.

Working Examples

Recommended split IAM policy configuration to handle both ARN-scoped and global list actions across legacy and current service prefixes.

# Statement 1: list-level actions that don't accept ARN scoping.
statement {
sid = "CodeConnectionsListLevel"
effect = "Allow"
actions = [
"codestar-connections:ListConnections",
"codestar-connections:ListInstallationTargets",
"codestar-connections:ListTagsForResource",
"codeconnections:ListConnections",
"codeconnections:ListInstallationTargets",
"codeconnections:ListTagsForResource",
]
resources = ["//"]
}

# Statement 2: resource-level actions you can safely scope.
statement {
sid = "CodeConnectionsResourceLevel"
effect = "Allow"
actions = [
"codestar-connections:GetConnection",
"codestar-connections:GetConnectionToken",
"codestar-connections:PassConnection",
"codestar-connections:UseConnection",
"codeconnections:GetConnection",
"codeconnections:GetConnectionToken",
"codeconnections:PassConnection",
"codeconnections:UseConnection",
]
resources = [aws_codestarconnections_connection.your_connection.arn]
}

Practical Applications

• Use Case (CI/CD Pipelines): Configuring AWS CodeBuild projects to clone GitHub repositories using both codestar-connections:* and codeconnections:* prefixes for compatibility.
• Pitfall (IAM Simulation): Testing permissions on the calling user rather than the service role, resulting in false positives from the IAM simulator.

References:

• https://dev.to/morganw/the-misleading-user-is-not-authorized-to-access-connection-error-in-aws-codebuild-and-why-your-191a