AWS IAM Roles Explained: Trust Policy, Permissions & Examples

Simple explanation

An IAM role is a set of permissions that is not tied to a specific person or permanent password. Instead of giving your application a username and password that never change, you give it a role. When the application needs access, AWS checks the role, issues a short-lived pass, and the pass expires on its own.

This matters because permanent credentials can leak. If an access key ends up in a Git repository, anyone who finds it has access until someone manually revokes it. With a role, the credentials expire in minutes to hours. Even if they leak, the window of exposure is small.

Why IAM roles matter

Permanent credentials are one of the most common sources of AWS security incidents. Long-lived access keys get committed to repositories, pasted into chat, or left in decommissioned servers. Roles eliminate this category of risk.

• No long-lived credentials in code. Applications never store permanent keys. The AWS SDK retrieves temporary credentials from the instance metadata service or the Lambda runtime automatically.
• Automatic rotation. AWS refreshes the temporary credentials before they expire. You do not need to build credential rotation logic.
• Reduced blast radius. If temporary credentials leak, they expire within minutes to hours. An attacker cannot use them indefinitely.
• Clean delegation. Roles let you grant access across AWS accounts or to external identity providers without sharing passwords or keys. Each side manages its own policies independently.

How IAM roles work

Every IAM role has two policy documents that work together: a trust policy and one or more permissions policies. The trust policy controls who can use the role. The permissions policies control what the role can do.

Trust policy

The trust policy is a JSON document attached to the role that lists which principals are allowed to call sts:AssumeRole. A principal can be an AWS service, an IAM user, another AWS account, or an external identity provider.

Here is a trust policy that allows EC2 instances to assume the role:

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

Common principal values:

• “Service”: “ec2.amazonaws.com” for EC2 instances
• ”Service”: “lambda.amazonaws.com” for Lambda functions
• ”AWS”: “arn:aws:iam::123456789012:root” for all principals in another AWS account
• ”Federated”: “token.actions.githubusercontent.com” for GitHub Actions via OIDC

You can add conditions to a trust policy to restrict assumption further. For example, you can require that a GitHub Actions workflow runs on a specific repository branch before it can assume the role.

Permissions policy

The permissions policy works the same way as a policy on an IAM user. It lists the AWS actions and resources the role holder can access. Here is a policy granting read access to a specific S3 bucket:

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

You can attach AWS managed policies, customer managed policies, or write inline policies directly on the role. For guidance on choosing between these, see managed vs customer managed policies. For the JSON anatomy of a policy document, see IAM policy structure.

Temporary credentials and role assumption

When a principal assumes a role, AWS Security Token Service (STS) returns three values: a temporary access key ID, a secret access key, and a session token. These credentials expire after a configurable period (typically one hour, up to 12 hours via the role’s MaxSessionDuration setting).

The assumption flow works like this:

1. A trusted principal (EC2, Lambda, a user, or an external identity) requests to assume the role.
2. AWS checks the role’s trust policy to confirm the principal is allowed.
3. STS issues temporary credentials scoped to the role’s permissions policies.
4. The principal uses those credentials to make AWS API calls.
5. The credentials expire automatically. No cleanup is needed.

For a deeper walkthrough of the AssumeRole API and cross-account patterns, see role assumption in AWS.

Instance profile vs role

EC2 instances cannot reference an IAM role directly. Instead, you create an instance profile, which is a container that holds exactly one role. You attach the instance profile to the EC2 instance at launch, and the instance metadata service (IMDS) vends temporary credentials for the role automatically.

When you create a role in the AWS Console and select “EC2” as the trusted entity, the console creates the instance profile for you. When using the CLI or Terraform, you must create the instance profile separately.

Common use cases

EC2 instance profile

An EC2 instance assumes a role through its instance profile. Any application running on the instance can call AWS APIs without storing credentials. The AWS SDK reads temporary credentials from IMDS automatically.

Lambda execution role

Every Lambda function requires an execution role. The role grants the function permission to write logs to CloudWatch, read from DynamoDB, publish to SNS, or whatever the function needs. Lambda assumes the role on every invocation.

Cross-account access

A role in Account B can trust principals in Account A. Users or services in Account A call sts:AssumeRole to get temporary credentials for Account B. This avoids sharing IAM users or access keys between accounts. It is the standard pattern in multi-account setups.

GitHub Actions and OIDC federation

GitHub Actions can assume a role using OpenID Connect (OIDC) federation instead of storing long-lived access keys as repository secrets. The trust policy validates the OIDC token from GitHub and grants temporary credentials for the deployment workflow.

EKS with IAM Roles for Service Accounts (IRSA)

Pods running in EKS can assume IAM roles through IRSA. Each Kubernetes service account maps to an IAM role, so individual pods get only the permissions they need instead of sharing a single node-level role.

IAM roles vs IAM users vs access keys

This table helps you decide which identity type fits your situation. The short version: use roles for workloads, users for humans, and avoid access keys unless you have no alternative.

For a side-by-side walkthrough, see IAM users vs roles. For details on how access keys work and why they carry risk, see access keys explained.

Real example: EC2 reading from S3

This walkthrough creates a role that allows an EC2 instance to read objects from S3, then launches an instance with that role attached via an instance profile. All commands use the AWS CLI.

Step 1: Create the role with a trust policy

# Save the trust policy to a file
cat > trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "ec2.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF

# Create the role
aws iam create-role \
  --role-name MyEC2S3ReadRole \
  --assume-role-policy-document file://trust-policy.json

Step 2: Attach a permissions policy

This attaches the AWS managed AmazonS3ReadOnlyAccess policy. In production, create a least-privilege custom policy that scopes access to specific buckets.

aws iam attach-role-policy \
  --role-name MyEC2S3ReadRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

Step 3: Create an instance profile and add the role

# Create the instance profile (required for EC2)
aws iam create-instance-profile \
  --instance-profile-name MyEC2S3ReadProfile

# Add the role to the instance profile
aws iam add-role-to-instance-profile \
  --instance-profile-name MyEC2S3ReadProfile \
  --role-name MyEC2S3ReadRole

Step 4: Launch an EC2 instance with the profile

Replace ami-0abcdef1234567890 with a valid AMI ID for your region.

aws ec2 run-instances \
  --image-id ami-0abcdef1234567890 \
  --instance-type t3.micro \
  --iam-instance-profile Name=MyEC2S3ReadProfile \
  --count 1

Once the instance is running, any code on it can call S3 APIs without any access keys. The AWS SDK reads credentials from the instance metadata service automatically. The credentials refresh before they expire, so the application never needs to handle rotation.

When to use a role

• Workloads running in AWS. EC2, Lambda, ECS, EKS, CodeBuild, Step Functions. Always use a role. Never embed access keys.
• Cross-account access. Create a role in the target account and let the source account assume it.
• CI/CD pipelines. Use OIDC federation with GitHub Actions, GitLab, or other providers instead of storing access keys as secrets.
• Third-party access. Grant vendors a role with scoped permissions and an external ID condition, rather than creating IAM users for them.
• Temporary privilege escalation. A developer assumes a role with elevated permissions for a specific task, then the session expires.

Only fall back to access keys when no role-based option exists, such as on-premises scripts that cannot use OIDC federation.