Roles and trust

A role has two halves. The trust policy (its resource-based policy, also called the assume-role policy) says who may assume it. The permissions policies (managed and inline) say what the session may do. A permissions boundary, if attached, caps the second half. Getting either half wrong produces a different error: trust failures are refusals of sts:AssumeRole; permission failures are refusals of the action itself.

Kinds of role

Kind	Who assumes it	Trust policy principal	Who controls the permissions
Service role	An AWS service acting for you (Lambda, ECS, CloudFormation, EC2)	"Service": "<service>.amazonaws.com"	You
Service-linked role	One specific AWS service	Fixed by the service	The service; you can view but not edit
Cross-account role	Principals in another AWS account	"AWS": "<account or role ARN>"	You (the role's account)
Federated role	Users or workloads authenticated by a SAML or OIDC provider	"Federated": "<provider ARN or name>"	You

Service roles

Created with aws iam create-role --role-name <name> --assume-role-policy-document file://trust.json, then attach-role-policy (managed) or put-role-policy (inline). The console's "AWS service" trusted-entity option writes the trust policy for you; the CLI and API do not. Service principal names are case-sensitive and vary by service: copy them from the service's documentation.

EC2 needs an instance profile. An instance gets a role only through an instance profile, which holds exactly one role (fixed limit). The console creates one with the role's name; the CLI does not:

aws iam create-instance-profile --instance-profile-name <name>
aws iam add-role-to-instance-profile --instance-profile-name <name> --role-name <role>

Service-linked roles

• Live under the path /aws-service-role/ and their ARN contains the service principal.
• Usually created by the service when you first create a resource that needs one; otherwise aws iam create-service-linked-role --aws-service-name <service>.amazonaws.com, which needs iam:CreateServiceLinkedRole.
• Count toward the roles-per-account quota but can still be created after the quota is reached.
• Cannot be renamed, and cannot be tagged at creation. Deleting one requires deleting the resources that use it first, plus iam:DeleteServiceLinkedRole and iam:GetServiceLinkedRoleDeletionStatus.
• Not restricted by SCPs or RCPs.

iam:PassRole

Whenever a call configures a resource with a role ARN (create a Lambda function, launch an instance, create a stack with a service role), the caller needs iam:PassRole on that role. Facts that matter:

• It is a permission, not an API action: there is no PassRole event in CloudTrail. The role that was passed shows up in the event for the call that used it (for example CreateFunction).
• It is checked when the resource is configured, not each time the service later assumes the role.
• Scope Resource to the role ARNs the caller may pass, and restrict the receiving service with the iam:PassedToService condition key.
• Do not try to control it with role tags and ResourceTag conditions; AWS says that approach is unreliable.
• A role cannot be passed across accounts directly: the service and the role must be in the same account.
• Passing a service-linked role is required only when you name it explicitly.
• A caller that can pass a role can make the service act with that role's permissions. Grant PassRole only for roles whose permissions the caller is itself allowed to exercise.

The machine-readable service reference lists the value of iam:PassedToService for operations that pass a role, which helps scope it precisely.

Confused-deputy conditions

When a resource-based policy grants access to a service principal (a bucket letting CloudTrail write logs, for example), anyone who can configure that service could point it at your resource. Restrict the grant to the work you meant, narrowest first:

Key	Matches requests the service makes on behalf of
aws:SourceArn	one specific resource (a trail, a fleet, a topic); compare with ArnEquals/ArnLike
aws:SourceAccount	one account; present only when the call is made directly by a service principal
aws:SourceOrgID	any account in your organization
aws:SourceOrgPaths	accounts under specific OUs

For a cross-account role assumed by a third party, the equivalent protection is sts:ExternalId in the role's trust policy: see patterns/iam/trust-policies.md.

Settings on the role itself

• Maximum session duration: 1–12 hours, set per role; DurationSeconds on AssumeRole cannot exceed it. Role chaining caps any session at one hour regardless.
• Names are up to 64 characters and unique per account ignoring case; a role used with console Switch Role must keep path plus name within 64.
• Unique ID: trust and resource policies that name a role by ARN store its unique ID (beginning AROA). Deleting and recreating the role breaks them; see patterns/iam/trust-policies.md.
• Managed policies per role and other counts are quotas: read them live (reference/iam/limits.md).

Roles created or assigned for you (2026)

• Role manager (generally available August 2026). In supported service consoles (six at launch, including Lambda and EventBridge), the console creates a default service role from an AWS-managed template, or reuses an existing role with the needed permissions. It is on by default for accounts created in the new AWS experience and can be turned off. Roles it creates are ordinary roles you control, marked as created by it. Only console behavior is described; whether it affects API or IaC calls was not stated. If a human reports a role appeared that the instructions did not mention, this is the likely cause: record it and do not create a duplicate.
• Account access manager (August 2026). Assigns existing IAM roles in your organization's accounts to IAM Identity Center users and groups, keeping full role features (custom trust policies, tags, paths). Usable from the IAM console, SDK and CloudFormation/CDK, alongside or instead of permission sets: see reference/identity-center/permission-sets-and-access.md.