# IAM role trust policy: examples and how it works

IAM policy examples · Updated 17 November 2026

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

## 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 policy | Permissions policy |
|---|---|---|
| Answers | Who can become this role? | What can the role do once assumed? |
| Has a Principal | Yes, required | No |
| Typical actions | `sts:AssumeRole`, `sts:AssumeRoleWithWebIdentity`, `sts:TagSession` | Service actions such as `s3:GetObject` |
| How many | Exactly one per role | Several managed and inline |
| CLI | `aws iam update-assume-role-policy` | `aws 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](https://cloudconsole.dev/iam/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](https://cloudconsole.dev/iam/github-actions-oidc) and [EKS IRSA](https://cloudconsole.dev/iam/eks-irsa-trust-policy).
- **A third party**: add `sts:ExternalId`; see [cross-account with ExternalId](https://cloudconsole.dev/iam/cross-account-role-external-id).

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

## Sources

- [IAM JSON policy elements: Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)
- [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)

## Related

- [Cross-account assume role with an external ID](https://cloudconsole.dev/iam/cross-account-role-external-id)
- [GitHub Actions OIDC: IAM role trust policy](https://cloudconsole.dev/iam/github-actions-oidc)
- [aws iam create-role](https://cloudconsole.dev/cli/iam-create-role)
- [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 in the AWS console](https://cloudconsole.dev/how-to/switch-role-aws-console)

---

Source: https://cloudconsole.dev/iam/assume-role-trust-policy

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