assumeRole and trust policy: why IAM users aren't enough

2025/11/05
awsiam

You attach policies to IAM (Identity and Access Management) users. Policies define what actions are allowed on which resources. Simple.

Then assumeRole and trust policy show up, and the docs explain how to set them up before explaining why they exist.

A role is an IAM identity that holds permissions but has no password or permanent keys of its own. sts:AssumeRole is an API action in STS (Security Token Service). A service or user calls it to get temporary credentials for a role. Trust policy is the policy attached to that role that controls who is allowed to call sts:AssumeRole on it.

The examples in this article build these resources:

NameTypePurpose
s3-reader-roleIAM Rolethe role ECS tasks and Lambda assume
trust policyPolicy on the roleallows ecs-tasks.amazonaws.com and lambda.amazonaws.com to call sts:AssumeRole
s3-reader-policy.jsonPermission policy attached to the rolegrants s3:GetObject and s3:ListBucket on my-app-assets

why not just use IAM users

An IAM user has permanent credentials. Access key, secret key. They work forever until someone manually revokes them.

This breaks in three ways:

  • A key leaks in a git commit. It stays valid until someone notices.
  • A partner team in another AWS account needs access. Now you're managing someone else's permanent identity.
  • An AWS service needs permissions, such as ECS (Elastic Container Service, which runs containers) or Lambda. Services don't log in. The only way to give them a permanent key is to paste it into their config, where it can leak like the first case.

All three cases need access that expires and covers only specific resources.

assumeRole returns temporary credentials that expire on their own. No cleanup.

the simple path: AWS services

An ECS task needs to read from S3. Two steps.

step 1: create the role and set who can assume it

Go to IAM > Roles > Create role.

First thing AWS asks: "Who will use this role?" Select AWS service, pick Elastic Container Service, then the Elastic Container Service Task use case.

This creates the trust policy. It's not a separate thing. It's baked into the role at creation. You can see it later under the Trust relationships tab. The console writes only ecs-tasks.amazonaws.com. To let Lambda use the same role, add it there with Edit trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": ["ecs-tasks.amazonaws.com", "lambda.amazonaws.com"]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

One role, one trust policy. The Principal field, which names who may assume the role, accepts multiple services in an array. No need to create separate trust policies.

Name the role s3-reader-role.

step 2: attach permissions to the role

Next screen. Attach a permission policy that defines what this role can do. Save the following as s3-reader-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::my-app-assets",
        "arn:aws:s3:::my-app-assets/*"
      ]
    }
  ]
}

Attach this to s3-reader-role:

CLI:

aws iam create-policy \
  --policy-name s3-reader-policy \
  --policy-document file://s3-reader-policy.json
 
aws iam attach-role-policy \
  --role-name s3-reader-role \
  --policy-arn arn:aws:iam::ACCOUNT-ID:policy/s3-reader-policy

Console: IAM > Roles > s3-reader-role > Permissions > Add permissions > Attach policies > select s3-reader-policy.

Done. Go to the ECS task definition, set the Task Role to s3-reader-role.

At runtime: ECS task starts → ECS calls sts:AssumeRole → STS checks the trust policy, finds ecs-tasks.amazonaws.com listed → ECS hands temporary credentials to the task → task uses those credentials to access S3.

No third step. AWS services handle the assume call internally. Whoever sets the Task Role does need iam:PassRole on s3-reader-role, which is what lets them hand the role to ECS; admins already have it.

what if there's no assumeRole

On Fargate, where AWS manages the servers and you don't run your own, a task without a role has no AWS credentials at all. Its request to S3 arrives unsigned, as an anonymous request, and the bucket rejects it.

Granting access to ecs.amazonaws.com in the bucket policy (the policy attached to the S3 bucket itself) still leaves the task unable to read the bucket, because the task's requests are not signed as that identity.

ecs.amazonaws.com and ecs-tasks.amazonaws.com differ by a few letters, but they are two different identities, written in the trust policies of different roles:

  • ecs-tasks.amazonaws.com goes in the trust policy of the task role (here, s3-reader-role). ECS uses this identity to get s3-reader-role credentials for the task and hand them to the code inside it.
  • ecs.amazonaws.com goes in the trust policy of AWSServiceRoleForECS. AWS creates this role automatically the first time you create an ECS cluster or service. The ECS documentation says ECS uses it to manage the cluster, for example to create ENIs (elastic network interfaces) for tasks and register tasks with a load balancer.

Only ECS uses either identity; the code inside the task uses neither. When that code sends a request to S3, it signs with the s3-reader-role credentials ECS handed it. So S3 sees s3-reader-role, not the ecs.amazonaws.com written in the bucket policy, and that statement never applies to the task.

Naming one specific task through a service principal doesn't work either. The AWS Principal documentation defines a service principal as "an identifier for a service", in the form service-name.amazonaws.com. It stops at the service; there is no field for a task.

To grant a task access in the bucket policy, put its task role ARN in the Principal:

"Principal": { "AWS": "arn:aws:iam::ACCOUNT-ID:role/s3-reader-role" }

With that in place, every task started from a task definition that uses s3-reader-role matches this Principal and can read the bucket. To give different tasks different permissions, give their task definitions different roles.

With no role at all, what's left is the IAM user route. Create a user for each consumer, generate an access key, and paste it into the task's environment variables. Ten services reading S3 means ten permanent keys stored in ten configs. If any one of them leaks, it keeps working until someone revokes it.

With assumeRole, nothing permanent is stored anywhere. The role carries the permissions, and ECS fetches fresh credentials for the task. Add a new service to the trust policy, it gets the same S3 access. In the same account, the bucket policy stays untouched: the role's permission policy is enough.

the full path: IAM users and cross-account

A developer in another AWS account needs to read your S3 bucket. Three steps.

step 1 and 2: same as above

Create the role, set the trust policy to trust the other account:

{
  "Principal": {
    "AWS": "arn:aws:iam::OTHER-ACCOUNT-ID:root"
  }
}

:root here means the whole account, not its root user. The other account's admin then decides which of its users get to use the role.

Attach S3 read permissions. Same as before.

step 3: the other side also needs permission

In the other account, go to IAM > Users > [the user] > Permissions, add a policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::YOUR-ACCOUNT-ID:role/s3-reader-role"
    }
  ]
}

This is the extra step that AWS services don't need. A human (or their scripts) has to prove they're allowed to ask.

Both sides must allow it. The role's trust policy has to list the other account, and the user's own policy has to allow sts:AssumeRole on this role. If either one doesn't, access denied.

Within one account the rule is looser. If the trust policy names the user's ARN (Amazon Resource Name, the full ID of an AWS resource) directly, the user needs no policy of their own. If it names the account (:root), the user still needs the step 3 policy.

Same runtime flow as above: the user calls sts:AssumeRole, STS checks both sides, and returns temporary credentials (default: one hour).

the mental model

An IAM user with permanent keys is a house key. Works forever until the locks change.

assumeRole is a hotel key card. Opens one room, for one night, stops working at checkout.

Trust policy = the hotel's guest list (who can check in) User policy = the reservation (proof the guest is allowed to ask for a room) Temporary credentials = the key card (works for a limited time, then dies)