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.

Trust Policy Configuration

Principal Type

Principal Value

Effect

Generated Trust Policy

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

About This Tool

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.

When to Use This Tool

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

Frequently Asked 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.

Related Learning Guides

AWS IAM Best Practices25 min read

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.