# Cross-account assume role with an external ID

IAM policy examples · Updated 17 November 2026

**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.

## 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](https://cloudconsole.dev/iam/cloudwatch-read-only) 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](https://cloudconsole.dev/errors/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 CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html)
- [The confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)

## Related

- [IAM role trust policy: examples and how it works](https://cloudconsole.dev/iam/assume-role-trust-policy)
- [aws sts assume-role](https://cloudconsole.dev/cli/sts-assume-role)
- [AccessDenied: User is not authorized to perform: sts:AssumeRole](https://cloudconsole.dev/errors/not-authorized-to-perform-sts-assumerole)
- [How to switch role with the AWS CLI](https://cloudconsole.dev/how-to/switch-role-aws-cli)
- [IAM policy: CloudWatch read-only for a monitoring tool](https://cloudconsole.dev/iam/cloudwatch-read-only)
- [ABAC: tag-based access control policy example](https://cloudconsole.dev/iam/abac-tags)

---

Source: https://cloudconsole.dev/iam/cross-account-role-external-id

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
