How do I troubleshoot IAM "AccessDenied" or "Not authorized to perform AssumeRoleWithWebIdentity" federation errors from my identity provider?

Short description

The API action AssumeRoleWithWebIdentity error occurred because the IAM trust policy isn't configured correctly or the IAM role in the IdP isn't configured correctly.

Resolution

To resolve this issue, follow the instructions to create an IAM role for OpenID Connect (OIDC) federation. Then, follow these guidelines to configure the IAM role trust policy.

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

IAM role trust policy

Make sure that the IAM role trust policy is configured correctly for your IdP.

Example role trust policy for GitHub IdP

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::012345678910:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:GitHubOrg/GitHubRepo:ref:refs/heads/GitHubBranch"
        }
      }
    }
  ]
}

IAM role configuration

Make sure that the IAM role is configured with the correct Amazon Resource Name (ARN) for your IdP. The steps to configure the IAM role vary from different IdPs and AWS services.

For example, to get the service account's IAM role ARN for Amazon Elastic Kubernetes Service (Amazon EKS), run the following command:

kubectl describe serviceaccount serviceaccount_name -n namespace_name

From the output, confirm that the IAM role ARN is the one that you want to assume. If the IAM role ARN is correct, then follow the steps to assign the IAM role to your Kubernetes service account. If the IAM role ARN is incorrect, then follow the steps to update the ARN in Create and associate role.

For more information, see Create an IAM OIDC provider for your cluster.

CloudTrail Event History

The API action AssumeRoleWithWebIdentity failures are logged in AWS CloudTrail Event history. You can view all supported services and integrations and event types, such as create, modify, delete, and non-mutable activities, from the past 90 days. You don't need to set up a trail to use CloudTrail Event history.

Compare the PrincipalId value logged in the CloudTrail Event history in the role trust policy to confirm the values passed in the API request.

For example, if the value arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com:sts.amazonaws.com:repo:reponame-rn/new-repo:environment:dev is logged in the PrincipalId of the CloudTrail event, then use the following trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:reponame-rn/new-repo:environment:dev"
        }
      }
    }
  ]
}

For more information, see Viewing recent management events with the console.

Configuration best practices

To troubleshoot configuration issues, follow these best practices:

• Incomplete Principal ARN in the role trust policy: The federated principal ARN in the trust policy must include the complete ARN and the OIDC provider name. For example, if you are use a GitHub IdP, the principal ARN is in the format arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com.
• Incorrect ARN partitions: The ARN configuration must include the correct partition for the role and the OIDC provider. For example, ARNs for OIDC providers in the AWS GovCloud partition are formatted as arn:aws-us-gov:iam::123456789012:oidc-provider/token.actions.githubusercontent.com.
• Unavailable condition keys: Not all IdPs are compatible with the condition keys available for OIDC federation. Be sure to validate the condition key's compatibility with the OIDC provider. For more information, see Available keys for AWS OIDC federation.
• Missing role path in the IdP configuration: The complete IAM role and ARN path must be configured for your IdP. For example, the IAM role name GitHubRole in the administrator path ARN is configured as arn:aws:iam::123456789012:role/administrator/GitHubRole.

Related information

How can I resolve the AWS STS AssumeRoleWithWebIdentity API call error "InvalidIdentityToken"?

How do I resolve errors related to OIDC IdP federation in IAM?

Configuring OpenID Connect in Amazon Web Services (on the GitHub website)