AWS Integration
Cross-Account IAM Role setup with CloudFormation or Terraform.
AWS Integration
AWS integration uses a Cross-Account IAM Role with an External ID. The Runner assumes this role at runtime to access your AWS account — no access keys are stored. See Security Architecture for the full security model.
Setup Methods
Copy External ID
Alethia generates a unique External ID and displays it. This ID is shared between your IAM role and the platform to prevent confused deputy attacks.
Launch CloudFormation Stack
Click "Launch Stack in AWS" — this opens the AWS Console with a pre-filled CloudFormation template that creates:
AlethiaProvisionerRole— IAM role with permissions for all supported resource types- Trust policy restricting who can assume the role to the platform's AWS account
- External ID condition in the trust policy
Acknowledge and Create
In the AWS Console, acknowledge that CloudFormation will create IAM resources, then click "Create stack."
Copy Role ARN
After the stack completes (~1 minute), go to the Outputs tab and copy the Role ARN.
Paste into Alethia
Paste the Role ARN into the Alethia form and click "Complete."
Copy External ID
Same as CloudFormation — Alethia provides the External ID.
Apply Terraform
Use the provided Terraform snippet to create the IAM role with the External ID in your AWS account.
Copy Role ARN
Copy the role_arn output from Terraform.
Paste into Alethia
Paste into the form and click "Complete."
Verification
After submitting, Alethia queues a CONNECTION_TEST job:
- A Runner assumes the role via
STS AssumeRolewith the External ID - Calls
sts:GetCallerIdentityto verify the assumed identity - Discovers existing resources: VPCs, subnets, hosted zones, IAM users, security groups
- Caches discovered resources in
cloud_identities.credentials
If verification fails, the error message explains what went wrong (e.g., trust policy misconfiguration, missing permissions).
IAM Role Permissions
The role has permissions for all Terraform-managed resource types:
| Service | Permissions |
|---|---|
| EC2 | VPC, subnets, NAT gateways, security groups, Elastic IPs |
| EKS | Clusters, node groups, OIDC providers, access entries |
| RDS | Aurora clusters, instances, subnet groups, parameter groups |
| ElastiCache | Replication groups, subnet groups |
| Route 53 | Hosted zones, record sets |
| Secrets Manager | Secrets, resource policies |
| DynamoDB | Tables, backups |
| SQS / SNS | Queues, topics, subscriptions |
| ECR | Repositories, lifecycle policies |
| S3 | Buckets, policies |
| IAM | Roles (for IRSA), policies, instance profiles |
| ACM | Certificates |
| WAF | Web ACLs, rules |
The role is NOT an admin role. It has exactly the permissions needed for the supported Terraform resources, scoped with conditions where possible.
What's Stored
Only two values are stored in the database:
- Role ARN —
arn:aws:iam::123456789012:role/AlethiaProvisionerRole - External ID — UUID generated by Alethia
No access keys, secret keys, or session tokens are ever persisted.