What is the confused deputy problem and how does ExternalId prevent it?

The confused deputy problem occurs when a third-party service (the 'deputy') that you grant cross-account access to is tricked into acting on behalf of a different customer using your role. By requiring an ExternalId condition in the trust policy, only callers who know the secret ExternalId value can assume the role. This ensures the third party can only use the role in the context of your specific relationship, not when acting on behalf of someone else.

When should I use AssumeRoleWithWebIdentity vs AssumeRole?

Use sts:AssumeRoleWithWebIdentity when the caller authenticates through an OIDC identity provider like Google, GitHub, or Amazon Cognito. The trust policy specifies the OIDC provider ARN and conditions on the token claims (like the repository name for GitHub Actions). Use sts:AssumeRole when the caller is an IAM user, role, or AWS account that authenticates directly with AWS credentials. The builder handles both patterns and generates the appropriate Condition block for each.

IAM Trust Policy Builder

IAM & SecurityAWS

Build IAM trust (assume-role) policies with a guided form.

Last verified: April 2026

Trust Policy Configuration

Principal Type

Principal Value

Effect

Generated Trust Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": ""
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

See It in Action

Your team is migrating CI/CD from long-lived IAM access keys to GitHub Actions OIDC federation. You need trust policies for 8 different roles — deployment, read-only, terraform-plan, and others — each scoped to specific repositories and branches. Using the builder, you generate each trust policy with the correct OIDC provider ARN, audience condition, and subject claim filter in minutes. Without the builder, the first attempt had a typo in the OIDC provider ARN that would have locked out all deployments.

What This Tool Does

Trust policies (AssumeRolePolicyDocument) define which principals — AWS accounts, services, SAML providers, or OIDC federations — can assume an IAM role. Unlike permission policies, trust policies are attached directly to the role and control the authentication side of access. Getting trust policies wrong either locks out legitimate access or, worse, allows unauthorized principals to assume privileged roles. This builder provides a guided form for specifying principals, actions (sts:AssumeRole, sts:AssumeRoleWithSAML, sts:AssumeRoleWithWebIdentity), and conditions like ExternalId or token audience restrictions.

Technical Details

The builder constructs an AssumeRolePolicyDocument JSON object by combining the selected principal type (AWS account, service, SAML provider, or OIDC provider) with the appropriate action (sts:AssumeRole, AssumeRoleWithSAML, or AssumeRoleWithWebIdentity) and generates the correct Condition block structure. For OIDC principals, it adds audience and subject claim conditions based on the provider template (GitHub Actions, GitLab CI, etc.).

Common Use Cases

1Configuring cross-account role assumption with ExternalId conditions to prevent the confused deputy problem
2Setting up OIDC federation trust policies for GitHub Actions, GitLab CI, or Kubernetes service accounts
3Building trust policies for AWS service roles (Lambda, ECS, EC2) with the correct service principal format
4Creating SAML federation trust policies for enterprise SSO integration with Active Directory or Okta

Common Questions

What is the confused deputy problem and how does ExternalId prevent it?: The confused deputy problem occurs when a third-party service (the 'deputy') that you grant cross-account access to is tricked into acting on behalf of a different customer using your role. By requiring an ExternalId condition in the trust policy, only callers who know the secret ExternalId value can assume the role. This ensures the third party can only use the role in the context of your specific relationship, not when acting on behalf of someone else.
When should I use AssumeRoleWithWebIdentity vs AssumeRole?: Use sts:AssumeRoleWithWebIdentity when the caller authenticates through an OIDC identity provider like Google, GitHub, or Amazon Cognito. The trust policy specifies the OIDC provider ARN and conditions on the token claims (like the repository name for GitHub Actions). Use sts:AssumeRole when the caller is an IAM user, role, or AWS account that authenticates directly with AWS credentials. The builder handles both patterns and generates the appropriate Condition block for each.

Expert Tips

TIP

Always include an ExternalId condition for third-party cross-account roles, even if the vendor says it's optional. Without ExternalId, any customer of that vendor who knows your account ID can trick the vendor into assuming your role (the confused deputy attack). The ExternalId should be unique per customer relationship, not a shared secret.

TIP

For GitHub Actions OIDC federation, lock down the trust policy's Condition to the specific repository AND branch. Using just 'repo:org/repo:*' as the subject claim means any branch or PR in that repo can assume the role. Use 'repo:org/repo:ref:refs/heads/main' to restrict to the main branch only.

TIP

A common mistake is forgetting that trust policies and permission policies are evaluated independently. The trust policy controls WHO can assume the role, and the permission policy controls WHAT they can do after assuming it. Both must explicitly allow access — there's no inheritance between them.

Featured In

Related Learning Guides

AWS IAM Best Practices25 min read

Was this tool helpful?

Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.