Cross-account assume role with an external ID
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 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-customerTighter and broader variations
- Trust one role, not the whole account: replace
:rootwitharn:aws:iam::111122223333:role/VendorScannerif 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:PrincipalOrgIDor a specific role ARN instead, and consider requiring MFA for human use. - Several external IDs (the vendor rotated it): list both values in the
StringEqualsarray during the changeover. - Session tagging: if the vendor passes session tags, the trust policy also needs
sts:TagSessionin 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].ConditionCommon mistakes
- Inventing the external ID yourself. The vendor must generate it, or the uniqueness guarantee is lost.
- Using
StringLikewith a wildcard onsts: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
ReadOnlyAccessby 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.
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