--- cuppy_hub: aws cuppy_path: reference/iam/roles-and-trust.md cuppy_section: docs cuppy_doc: 0MSE-GAKQ cuppy_doc_uuid: 1ff6da92-bfa6-491f-9daf-2ea279273e86 cuppy_permalink: https://cuppy.io/aws/d/0MSE-GAKQ cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/iam/roles-and-trust cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 4411bcc661cf626dc29f884842270e16be6829bce000ea9d52f34e4d9346ba46 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # 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": ".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": ""` | You (the role's account) | | **Federated role** | Users or workloads authenticated by a SAML or OIDC provider | `"Federated": ""` | You | ### Service roles Created with `aws iam create-role --role-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 aws iam add-role-to-instance-profile --instance-profile-name --role-name ``` ### 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 .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`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.