CloudConsole

Cross-account assume role with an external ID

Updated 17 November 2026 · How we write and check guides

Short answer

In your account, create a role whose trust policy allows the vendor's AWS account to call sts:AssumeRole only when sts:ExternalId equals the ID the vendor gave you. The vendor's side needs sts:AssumeRole on your role ARN and passes the same external ID on every call.

Policy diagram: 1 statement(s); first Allow sts:AssumeRole on * (all resources)
The policy on this page drawn statement by statement: who it applies to, the actions, the resources and any condition.

The trust policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VendorWithExternalId",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "a1b2c3d4-unique-per-customer"
        }
      }
    }
  ]
}

111122223333 is the vendor's account, and the external ID is the value shown in their onboarding screen. Attach only the permissions the vendor needs to this role, for example a CloudWatch read-only policy for a monitoring product.

Why the external ID exists

The vendor's software assumes roles in hundreds of customer accounts using one set of credentials. Without an external ID, another customer could type your role ARN into the vendor's product and the vendor would happily read your account on their behalf. This is the confused-deputy problem.

The external ID closes it: the vendor generates a value unique to each of its customers, stores it with that customer's configuration, and always sends it. Someone else's configuration has a different ID, so the condition fails. It is not a secret; its job is uniqueness, not secrecy.

The caller's side

In the vendor's (or your other) account, the principal that assumes the role needs:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AssumeCustomerRole",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::123456789012:role/vendor-monitoring"
    }
  ]
}
aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/vendor-monitoring \
  --role-session-name vendor-check \
  --external-id a1b2c3d4-unique-per-customer

Tighter and broader variations

  • Trust one role, not the whole account: replace :root with arn:aws:iam::111122223333:role/VendorScanner if the vendor publishes it. The role must exist when you save the policy.
  • Your own accounts (no third party): an external ID adds little. Use aws:PrincipalOrgID or a specific role ARN instead, and consider requiring MFA for human use.
  • Several external IDs (the vendor rotated it): list both values in the StringEquals array during the changeover.
  • Session tagging: if the vendor passes session tags, the trust policy also needs sts:TagSession in the Action list.

Verify the setup

Ask the vendor to run their connection test, then confirm the call in your CloudTrail. The AssumeRole event shows the vendor's principal, the session name they used and whether the request succeeded. Repeat the call without --external-id; it must fail. If it doesn't, the condition is missing or misspelt.

aws iam get-role --role-name vendor-monitoring \
  --query Role.AssumeRolePolicyDocument.Statement[0].Condition

Common mistakes

  • Inventing the external ID yourself. The vendor must generate it, or the uniqueness guarantee is lost.
  • Using StringLike with a wildcard on sts:ExternalId. That defeats the point.
  • Error is a plain AccessDenied on AssumeRole when the external ID is missing or wrong, identical to a trust-policy mismatch. See not authorized to perform sts:AssumeRole.
  • Granting the vendor ReadOnlyAccess by default. It includes reading data such as S3 objects; ask what the product actually calls.

Questions

What is an external ID in AWS?

A value passed in AssumeRole and checked by the sts:ExternalId condition in a role's trust policy. It lets a third party prove which customer configuration a request belongs to.

Is the external ID a secret?

No. It prevents the confused-deputy problem through uniqueness. Treat it as an identifier, not a password.

When this happens away from your desk

Third-party roles are worth reviewing now and then. A phone app with IAM read access can list roles trusted by outside accounts in a minute, wherever you are.

About the app → · Download on the App Store

Sources