GitHub Actions OIDC AccessDenied May Be a Trust-Policy Problem, Not a Permission-Policy Problem

GitHub Actions jobs encountering an authentication error when trying to assume an AWS role through OpenID Connect may not be due to insufficient permissions, but rather a mismatch in the identity trust policy. The issue arises when the GitHub identity and the AWS trust policy do not align, causing the OIDC identity to be denied access before the role can grant service permissions.

The failure is typically manifested as an authorization error from AWS during role assumption, rather than an AccessDenied error after successful role assumption and service access. To resolve this issue, the trust policy must be narrow and its claims should accurately reflect the actual workflow identity. The trust policy should include the AWS OIDC provider, the audience expected by AWS STS, and the GitHub subject claim as specified in the trust policy.

A common mistake is to simply grant broader AWS service permissions to the role, which only addresses the service-level permissions and not the underlying identity and trust problem. The solution lies in ensuring that the trust policy matches the actual GitHub subject format and context, including the environment and branch information. This ensures that the role can be successfully assumed by the GitHub identity.

To validate the corrected trust policy, it is essential to confirm that the GitHub actions have the appropriate permissions, the AWS account uses the intended OIDC provider, and the role trust policy correctly names that provider. Additionally, the audit and subject conditions in the trust policy should accurately match the repository's current format and the job's context.

This approach allows for a clean verification process, where the role assumption and STS identity check can be assessed before attempting any production deployments or mutations.