---
name: aws-cloudformation-iam
description: Provides AWS CloudFormation patterns for IAM roles, policies, managed policies, permission boundaries, and trust relationships. Use when modeling least-privilege access, cross-account assumptions, service roles, or reusable IAM stacks that other CloudFormation templates consume.
allowed-tools: Read, Write, Bash
---

# AWS CloudFormation IAM Security

## Overview

Use this skill to model IAM with CloudFormation in a way that stays secure, auditable, and maintainable.

The most important design concerns are:
- separating trust policies from permission policies
- preferring roles over long-lived users wherever possible
- keeping least-privilege boundaries readable and reusable

Do not treat `SKILL.md` as a full IAM encyclopedia. Use the bundled references for larger policy examples and service-specific variants.

## When to Use

- Creating IAM roles for Lambda, ECS, EC2, Step Functions, or other AWS services
- Defining inline policies, managed policies, and permission boundaries in CloudFormation
- Modeling cross-account assume-role access with constrained trust policies
- Exporting IAM role ARNs or managed policy ARNs to downstream stacks
- Reviewing wildcard permissions, boundary drift, or role replacement risk
- Creating reusable IAM stacks for platform or application teams

## Instructions

### 1. Define the trust boundary first

Identify who or what assumes the role (service principal, cross-account principal, or federated identity), then write the trust policy with explicit principals and conditions before adding permissions.

### 2. Grant the minimum permission set

Use inline policies for role-specific access; use managed policies for shared patterns across principals. Scope actions and resources tightly, and use conditions where possible.

### 3. Apply permission boundaries for delegated role creation

Use permission boundaries when teams create or extend roles in their own stacks, when guardrails are needed around privileged services (IAM, KMS, Organizations), or to separate maximum allowed permissions from application-specific policies.

Name roles and policies consistently so stack outputs and audits remain easy to trace.

### 4. Model cross-account access

For cross-account roles: trust only the exact source account or principal, add `sts:ExternalId` conditions when appropriate, keep permission and trust policies separate, and export only the ARNs that consuming accounts need.

### 5. Validate the template and policy behavior

Before rollout, use these commands to verify the template and IAM behavior:

```bash
# Validate CloudFormation template syntax
aws cloudformation validate-template --template-body file://template.yaml

# Preview changes before applying
aws cloudformation create-change-set \
  --stack-name <stack-name> \
  --template-body file://template.yaml \
  --change-set-type CREATE

# Simulate whether a principal can perform specific actions
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:role/LambdaExecutionRole \
  --action-names dynamodb:GetItem dynamodb:PutItem

# Check for wildcards in IAM policies within the template
aws cloudformation list-stack-resources --stack-name <stack-name>
```

After deployment, confirm policy attachments and stack outputs match the intended security model.

## Examples

### Example 1: Service role for Lambda with tightly scoped permissions

```yaml
Resources:
  LambdaExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: DynamoDbWritePolicy
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - dynamodb:GetItem
                  - dynamodb:PutItem
                Resource: !GetAtt OrdersTable.Arn
```

### Example 2: Cross-account role with an external ID condition

```yaml
Resources:
  PartnerReadRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: arn:aws:iam::123456789012:role/partner-reader
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: partner-contract-001
```

Keep the trust relationship narrow and pair it with a separate read-only permission policy.

## Best Practices

- Prefer IAM roles over long-lived IAM users for application and automation access.
- Separate trust policies from permission policies when reviewing or refactoring templates.
- Use permission boundaries when delegating role creation to other teams.
- Scope resources, actions, and conditions as tightly as the workload allows.
- Export stable ARNs and names only when another stack truly consumes them.
- Keep expanded policy libraries and edge cases in `references/` instead of bloating the root skill.

## Constraints and Warnings

- Overly broad wildcards in IAM are easy to deploy and hard to notice later.
- Named IAM resources can be hard to replace safely once other systems depend on them.
- IAM changes may appear successful in CloudFormation before eventual consistency settles across AWS services.
- Some Identity Center or organization-wide access patterns need complementary tooling outside a single CloudFormation stack.
- Misconfigured trust policies are often a bigger risk than missing permissions.

## References

- `references/examples.md`
- `references/reference.md`

## Related Skills

- `aws-cloudformation-security`
- `aws-cloudformation-ec2`
- `aws-cloudformation-ecs`
- `aws-cloudformation-lambda`