CloudConsole

IAM role trust policy: examples and how it works

Updated 17 November 2026 · How we write and check guides

Short answer

A trust policy is the resource-based policy on an IAM role that says who may assume it: it has a Principal and allows sts:AssumeRole (or AssumeRoleWithWebIdentity / AssumeRoleWithSAML). It grants no permissions itself; what the role can do comes from its separate permissions policies.

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.

A trust policy for people in another account

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OpsRoleWithMfa",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ops-engineer"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "Bool": {
          "aws:MultiFactorAuthPresent": "true"
        }
      }
    }
  ]
}

Only the ops-engineer role in account 111122223333 can assume this role, and only from a session that used MFA. That role also needs sts:AssumeRole on this role's ARN in its own permissions.

Trust policy vs permissions policy

Trust policyPermissions policy
AnswersWho can become this role?What can the role do once assumed?
Has a PrincipalYes, requiredNo
Typical actionssts:AssumeRole, sts:AssumeRoleWithWebIdentity, sts:TagSessionService actions such as s3:GetObject
How manyExactly one per roleSeveral managed and inline
CLIaws iam update-assume-role-policyaws iam put-role-policy / attach-role-policy

The CLI and API still call the trust policy the "assume role policy document", which is why both names appear in search results.

Other common principals

  • An AWS service: "Principal": {"Service": "lambda.amazonaws.com"} (or ec2, ecs-tasks, codebuild). See Lambda execution role.
  • Any principal in an account: "Principal": {"AWS": "arn:aws:iam::111122223333:root"}. This trusts the account, which then decides in its own IAM policies who may assume the role. It does not mean only the root user.
  • A web identity provider: "Principal": {"Federated": "arn:aws:iam::123456789012:oidc-provider/…"} with sts:AssumeRoleWithWebIdentity; see GitHub Actions OIDC and EKS IRSA.
  • A third party: add sts:ExternalId; see cross-account with ExternalId.

Update a trust policy

aws iam update-assume-role-policy --role-name prod-admin \
  --policy-document file://trust.json

aws iam get-role --role-name prod-admin \
  --query Role.AssumeRolePolicyDocument

In the console: IAM → Roles → the role → Trust relationships → Edit trust policy.

How to see who can assume a role

Before changing a trust policy, read the current one and check which principals actually use the role. CloudTrail records every AssumeRole call in the account that owns the role, including the caller's ARN.

aws iam get-role --role-name prod-admin \
  --query 'Role.{Trust:AssumeRolePolicyDocument,MaxSession:MaxSessionDuration}'

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRole \
  --max-results 20 --query 'Events[].CloudTrailEvent' 

IAM Access Analyzer also flags roles that can be assumed from outside your account or organisation, which is a quick way to audit trust policies in bulk.

Common mistakes

  • Recreated principal. When you name a specific role or user, IAM stores its unique ID. If that role is deleted and recreated with the same name, the trust policy shows an ID like AROA… instead of the ARN and no longer matches. Edit the policy and save the ARN again.
  • Wildcard principal ("AWS": "*") without a strong condition: anyone in any account can assume the role.
  • Adding Resource to a trust policy: it isn't allowed there and the save fails.
  • Only one side configured. Cross-account access needs this trust policy and an allow on the caller's side.
  • Role chaining limits the session to one hour regardless of the role's maximum session duration.

Questions

What is the difference between an assume role policy and a trust policy?

Nothing; they are the same document. The API calls it AssumeRolePolicyDocument and the console calls it the trust policy.

Does a trust policy grant permissions?

No. It only controls who can assume the role. The role's permissions policies decide what the session can do.

What does arn:aws:iam::111122223333:root mean in a trust policy?

The whole account 111122223333. Any user or role there that has sts:AssumeRole on this role in its own policies can assume it.

When this happens away from your desk

Assuming a role from a phone works the same as from the CLI: base credentials, then sts:AssumeRole into the target. CloudConsole is being built to keep the assumed role visible on every screen, so you always know which account you are acting in.

About the app → · Download on the App Store

Sources