AWS Integration

Zenfra integrates with Amazon Web Services using IAM role assumption (STS AssumeRole). This means no long-lived AWS credentials are stored in Zenfra — instead, short-lived session tokens are generated for each run.

How it works

1. You create an IAM role in your AWS account with a trust policy that allows Zenfra to assume it.
2. You register the role in Zenfra as an AWS integration.
3. When a run executes, Zenfra assumes the role and injects temporary AWS credentials into the run environment.
4. Terraform/OpenTofu uses these credentials to manage your infrastructure.

Creating an AWS integration

1. Navigate to Integrations in the sidebar.
2. Under Cloud Providers, click Amazon Web Services.
3. Click New Integration.
4. Fill in the configuration:

Field	Description
Name	A descriptive name (e.g., production-aws, staging-account)
Role ARN	The full ARN of the IAM role to assume (e.g., arn:aws:iam::123456789012:role/ZenfraTerraformRole)
Region	The default AWS region for API calls
Session Duration	How long the temporary credentials are valid (default: 3600 seconds)
Generate on Worker	Whether to generate credentials on the worker rather than the control plane

Integration detail page

Each AWS integration has three tabs:

Overview

Shows the configuration details:

• Provider — AWS
• Space — the space this integration belongs to
• Role ARN — the IAM role being assumed
• Region — default AWS region
• Session Duration — credential lifetime in seconds
• Generate on Worker — whether credential generation happens on the worker
• Last Verified — when the integration was last successfully verified

Attachments

Lists which stacks are using this integration and their read/write permissions.

Trust Policy

Provides the IAM trust policy JSON that must be applied to your AWS role. The trust policy includes:

• Principal — the Zenfra broker role ARN that will assume your role
• Condition — an ExternalId constraint for security
• TagSession — allows Zenfra to tag the assumed session for audit purposes

Example trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::407389197287:role/zenfra-broker-staging-role"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": [
            "zenfra@<org_id>@<stack_slug>@write"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::407389197287:role/zenfra-broker-staging-role"
      },
      "Action": "sts:TagSession"
    }
  ]
}

The External IDs section below the policy shows all active external IDs used in the trust policy condition.

Attaching to stacks

AWS integrations are attached to stacks during stack creation or by editing the stack configuration. Each attachment specifies whether the integration provides Read, Write, or Read & Write access.

Attached integrations are visible on the stack's Configuration tab under Cloud Integrations.

Verifying an integration

Click the Verify button on the integration detail page to test that Zenfra can successfully assume the configured role. This confirms that:

• The IAM role exists
• The trust policy is correctly configured
• The ExternalId condition matches

Managing integrations

From the AWS Integrations list, you can:

• Click an integration name to view its details
• Click Edit to modify the configuration
• Use the Actions menu for additional operations

Security

Zenfra's approach to AWS access follows security best practices:

• No long-lived credentials — only temporary session tokens are used
• ExternalId protection — prevents confused deputy attacks
• Scoped access — each stack gets its own ExternalId, limiting the blast radius
• Session tagging — AWS sessions are tagged for CloudTrail auditability