AWS IAM Roles Module

PSA-compliant IAM roles module with mandatory permissions boundaries, MFA requirements, and least-privilege templates.
Explore the docs »

View Demo · Report Bug · Request Feature

Documentation

Full auto-generated documentation of inputs, outputs, and resources: TERRAFORM-DOCS.md

Table of Contents

1. About The Project
2. Getting Started
3. Usage
4. Security Features
5. PSA Compliance Features
6. Outputs
7. Troubleshooting
8. License

About The Project

This module centralizes the creation of commonly used IAM roles (EC2, Lambda, RDS Monitoring, Cross-Account) following the principle of least privilege. It integrates security guardrails like permissions boundaries and MFA-enforced cross-account access.

Features

• Standardized Roles: Pre-defined templates for EC2, Lambda, and RDS.
• Permissions Boundaries: Mandatory support for global guardrails.
• Cross-Account Security: MFA and External ID enforcement for trust relationships.
• Scoped Policies: S3 and CloudWatch policies are restricted to specific resources by default.
• Tag-Based Access: PSA-Compliant tags included for attribute-based access control (ABAC).

(back to top)

Usage

Basic Usage (EC2 Role with S3 Access)

module "iam_roles" {
  source = "./terraform-aws-iam-roles"

  project_name = "myapp"
  environment  = "prod"
  name_prefix  = "myapp-prod"

  create_ec2_role      = true
  create_s3_app_policy = true
  s3_bucket_arn        = "arn:aws:s3:::myapp-data"
  s3_app_prefix        = "uploads"
}

Advanced Usage (Cross-Account Role)

module "cross_account" {
  source = "./terraform-aws-iam-roles"

  project_name = "audit"
  environment  = "prod"
  name_prefix  = "auditor"

  create_cross_account_role = true
  trusted_account_arns      = ["arn:aws:iam::123456789012:root"]
  external_id               = "Company-Audit-2024"

  permissions_boundary = "arn:aws:iam::account:policy/GlobalGuardrail"
}

(back to top)

Security Features

• No Wildcards: CloudWatch and S3 policies avoid * resources wherever possible.
• SSL Enforcement: IAM policies for S3 access include a Deny statement for non-SSL requests.
• Confused Deputy Protection: Cross-account roles require an ExternalId.
• MFA Enforcement: Assumption of cross-account roles requires a valid MFA session.
• Boundary Support: Every role supports a permissions_boundary to ensure it cannot escalate privileges.

(back to top)

PSA Compliance Features

This module implements the following PSA compliance features (referencing 01-Strukturierte_PSA_Anforderungen_Allgemein.pdf):

Security Controls

• Req 3.69-01 (Identity Lifecycle): Standardized naming and tagging for all roles.
• Req 3.69-03 (Separation of Roles): Distinct roles for execution (compute) and monitoring.
• Req 3.01-06 (Strong Auth): MFA enforcement for sensitive cross-account operations.
• Req 3.66-05 (Logging): CloudWatch logging policies are scoped to prevent broad log access.

(back to top)

Troubleshooting

AccessDenied during Role Assumption

• Verify that the external_id matches exactly.
• Ensure the caller is using MFA if create_cross_account_role is used.
• Check that the Permissions Boundary is not overly restrictive.

IAM Policy Size Limit

• If attaching many custom policies, consider consolidating them or using IAM Groups if applicable.

(back to top)

Requirements

Name	Version
terraform	>=1.3

Providers

Name	Version
aws	n/a

Modules

No modules.

Resources

Name	Type
aws_iam_instance_profile.ec2_instance_profile	resource
aws_iam_policy.cloudwatch_logs_policy	resource
aws_iam_policy.s3_app_data_policy	resource
aws_iam_role.alb_logs_role	resource
aws_iam_role.cross_account_role	resource
aws_iam_role.ec2_instance_role	resource
aws_iam_role.lambda_execution_role	resource
aws_iam_role.rds_monitoring_role	resource
aws_iam_role_policy_attachment.ec2_cloudwatch_logs	resource
aws_iam_role_policy_attachment.ec2_s3_app_data	resource
aws_iam_role_policy_attachment.lambda_basic_execution	resource
aws_iam_role_policy_attachment.lambda_vpc_execution	resource
aws_iam_role_policy_attachment.rds_monitoring	resource
aws_caller_identity.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
create_alb_logs_role	Create IAM role for ALB access logs	bool	false	no
create_cross_account_role	Create cross-account access role	bool	false	no
create_ec2_role	Create IAM role for EC2 instances	bool	true	no
create_lambda_role	Create IAM role for Lambda functions	bool	false	no
create_rds_monitoring_role	Create IAM role for RDS enhanced monitoring	bool	false	no
create_s3_app_policy	Create S3 policy for application data access	bool	false	no
environment	Environment (e.g., prod, dev, test)	string	n/a	yes
external_id	External ID for cross-account role assumption (mandatory for PSA compliance)	string	""	no
iam_path	IAM path to apply to created roles, policies, and instance profiles	string	"/"	no
lambda_vpc_access	Grant Lambda VPC access permissions	bool	false	no
name_prefix	Prefix for resource names (if not provided, will use project-environment pattern)	string	""	no
permissions_boundary	ARN of the policy that is used to set the permissions boundary for the roles	string	null	no
project_name	Name of the project	string	n/a	yes
s3_app_prefix	S3 prefix for application data	string	"app-data"	no
s3_bucket_arn	ARN of the S3 bucket for application data	string	""	no
tags	Additional tags for all resources	map(string)	{}	no
trusted_account_arns	List of trusted AWS account ARNs for cross-account access	list(string)	[]	no

Outputs

Name	Description
alb_logs_role_arn	The ARN of the ALB logs role
cloudwatch_logs_policy_arn	The ARN of the scoped CloudWatch Logs policy
cross_account_role_arn	The ARN of the cross-account role
ec2_instance_profile_arn	The ARN of the EC2 instance profile
ec2_instance_profile_name	The name of the EC2 instance profile
ec2_instance_role_arn	The ARN of the EC2 instance role
ec2_instance_role_name	The name of the EC2 instance role
lambda_basic_execution_policy_arn	The ARN of the AWS managed Lambda basic execution policy
lambda_execution_role_arn	The ARN of the Lambda execution role
lambda_vpc_execution_policy_arn	The ARN of the AWS managed Lambda VPC execution policy
rds_monitoring_policy_arn	The ARN of the AWS managed RDS monitoring policy
rds_monitoring_role_arn	The ARN of the RDS monitoring role
s3_app_data_policy_arn	The ARN of the scoped S3 application data policy