Skip to main content
Latest Documentation
This is the latest documentation for the Cloud Posse Reference Architecture. To determine which version you're currently using, please see Version Identification.
Sponsor @cloudposse
Version: Latest

Deploy IAM Roles

Deploy IAM roles for GitHub Actions and machine users using the iam-role component. These roles are assumed via OIDC for CI/CD automation.

Legacy Approach:

The legacy aws-teams and aws-team-roles components are deprecated. This page documents the new approach using Permission Sets for human users and IAM roles for machine users.

For the legacy approach, see Access Control Evolution.

Overview​

The identity layer provides two authentication paths:

  1. Human Users — Use AWS IAM Identity Center Permission Sets (TerraformApplyAccess, TerraformPlanAccess) via SSO
  2. Machine Users — Use IAM roles assumed via OIDC (GitHub Actions, CI/CD pipelines)

Human users authenticate through Identity Center and never need IAM roles. The iam-role component is specifically for GitHub Actions and other machine users that authenticate via OIDC.

Deploy IAM Roles for GitHub Actions​

1 Vendor Identity Components​

Pull the identity components into your local repository:

Loading workflow...

2 Deploy GitHub OIDC Provider​

Deploy the GitHub OIDC provider in all accounts:

Loading workflow...

This creates the OIDC identity provider in each account, allowing GitHub Actions to assume IAM roles.

3 Deploy IAM Roles​

The reference architecture includes pre-configured iam-role/terraform and iam-role/planner components. Deploy them across all accounts:

Loading workflow...

This deploys:

  1. iam-role/terraform — Role for GitHub Actions apply operations
  2. iam-role/planner — Role for GitHub Actions plan operations
  3. Trust policies — Allow assumption via GitHub OIDC

Human User Access​

Human users do not use IAM roles. Instead, they authenticate via AWS IAM Identity Center:

  1. Permission Sets — Define access levels (TerraformApplyAccess, TerraformPlanAccess, ReadOnlyAccess)
  2. SSO Groups — Map IdP groups to Permission Sets
  3. Atmos Auth — CLI tool that authenticates via Identity Center SSO

See Configure Atmos Auth for human user setup.

Next Steps​

Configure authentication

With IAM roles deployed for machine users and Permission Sets available for human users, configure Atmos Auth profiles to map users to identities. Configure Atmos Auth