Skip to main content

AWS IAM Identity Center — Paved-Road Setup (Min-ClickOps / Max-IaC)

Audience: HITL/infrastructure operator
Read time: < 5 minutes
Purpose: Enable IAM Identity Center once; Terraform handles all other provisioning.

Principle: Maximum IaC, minimum ClickOps. Manually enable the service. Everything else is Terraform-declared in infra/terraform-aws/identity/config/.

Safety Rules​

Tenant Isolation: Each AWS Organization gets its own Identity Store directory (d-xxxxxxxxxx). Do NOT reuse directory IDs from prior tenants; Terraform will create and manage a new one.

Automation Profile: The <YOUR_ORG>-ReadOnly profile is the automation team's autonomous-safety layer. All READONLY queries (describe-*, list-*, get-*) run without HITL confirmation. All mutations (create-*, delete-*, modify-*) require HITL execution (Principle I).

Irreducible ClickOps (HITL Only)​

Step 1 — Enable IAM Identity Center (One-Time)​

  1. Log into management account → AWS Console
  2. Navigate to IAM Identity Center (search bar)
  3. Click Enable IAM Identity Center
  4. Note the AWS access portal URL (format: https://<INSTANCE_ID>.awsapps.com/start)

Why not Terraform? No Terraform resource exists to CREATE Identity Center itself; only data.aws_ssoadmin_instances reads it. This is a precondition.

AWS docs: https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-enable-identity-center.html

Step 2 — First Login (One-Time)​

aws sso login --profile <YOUR_ORG>-operations
# Browser opens → MFA → log in with work email → verify email link (if prompted)

Step 3 — Verify Identity (Critical)​

aws sts get-caller-identity --profile <YOUR_ORG>-operations

Expected output: Your organization's workload account ID. If it shows a different account, STOP — you may be authenticated to the wrong tenant.

Everything Else Is Terraform​

All permission sets, users, groups, and account assignments are declared in infra/terraform-aws/identity/ and driven from YAML config.

Do NOT create these manually in the console.

Deploy Flow​

# 1. Set environment (once per session)
set -a; source .env; set +a

# 2. Edit config (specify your users, groups, permission sets)
# Location: infra/terraform-aws/identity/config/
# Files: permission_sets.yaml, account_assignments.yaml
# Details: see infra/terraform-aws/identity/README.md

# 3. Terraform plan (automation can do this)
cd infra/terraform-aws/identity
terraform init \
  -backend-config="bucket=<YOUR_ACCOUNT_ID>-tfstate-<AWS_REGION>" \
  -backend-config="region=<AWS_REGION>"
terraform plan

# 4. Terraform apply (HITL executes — Principle I)
terraform apply

After apply, all permission sets, users, groups, and account assignments are live and managed by code.

Config Pointers (Do NOT Duplicate Below)​

  • Consumer README (this deployment): infra/terraform-aws/identity/README.md
    • Region override, prerequisites, YAML structure
  • Module README (reusable component): terraform-aws/modules/sso/README.md
    • Syntax, examples, advanced features (applications, external IdP, permissions boundaries)

CLI Profile Setup (One-Time)​

After Terraform apply, configure your shell to use the profiles:

# Edit ~/.zshrc, ~/.bashrc, or .env (gitignored — never commit credentials)
export AWS_MANAGEMENT_PROFILE=<YOUR_ORG>-management
export AWS_OPERATIONS_PROFILE=<YOUR_ORG>-operations
export AWS_READONLY_PROFILE=<YOUR_ORG>-ReadOnly
export AWS_BILLING_PROFILE=<YOUR_ORG>-billing
export AWS_PROFILE=$AWS_OPERATIONS_PROFILE
export AWS_DEFAULT_REGION=<YOUR_AWS_REGION>

# Reload shell
source ~/.zshrc

Generate ~/.aws/config (IaC-Driven)​

When the new task sso:config command is available (this session builds it), run:

task sso:config
# Output: copyable ~/.aws/config blocks (profiles auto-generated from Terraform)

Until then, manually configure profiles:

aws configure sso --profile <YOUR_ORG>-management
aws configure sso --profile <YOUR_ORG>-operations
aws configure sso --profile <YOUR_ORG>-ReadOnly
aws configure sso --profile <YOUR_ORG>-billing

Manual vs IaC Boundary​

TaskOwnerMethod
Enable Identity Center instanceHITLAWS Console (one-time, no TF resource)
First login + MFA + email verifyHITLaws sso login + browser
Verify identity is correctHITLaws sts get-caller-identity
Create permission setsTerraformconfig/permission_sets.yaml
Create users/groupsTerraformconfig/ YAML + sso_users, sso_groups
Assign users to accountsTerraformconfig/account_assignments.yaml
Configure CLI profilesHITLaws configure sso or task sso:config
Run READONLY queriesAutomationaws describe-*, aws list-* with $AWS_READONLY_PROFILE
Run mutations (create/delete)HITLaws create-*, terraform apply

Troubleshooting​

SymptomCauseFix
Token has expired and refresh failedSSO session staleaws sso login --profile <YOUR_ORG>-operations
Invalid SSO start URLRegion/instance mismatchCheck IAM Identity Center → Dashboard
aws sts get-caller-identity shows wrong accountAuthenticated to wrong tenantLog out; verify portal URL; re-login
Terraform AccessDeniedExceptionProfile lacks permissionVerify user assigned correct permission set in account_assignments.yaml

References​