AWS OIDC (federated, zero credentials)

aws_oidc lets Forgecroft assume IAM roles in your AWS account by federating against a JWT we sign per run. No access keys leave your account. You also get phase-scoped permissions by default: the plan phase assumes a read-only role, the apply phase assumes a write role.

How it works

1. You deploy a CloudFormation template that registers Forgecroft as an IAM OIDC provider in your AWS account and creates two roles (plan = read-only, apply = write).
2. At each phase boundary, the runner asks our API for a short-lived JWT scoped to the run + phase.
3. AWS exchanges the JWT for STS credentials via sts:AssumeRoleWithWebIdentity.
4. The trust policy enforces phase separation: a phase=plan JWT can only assume the plan role.

Setup

1. Get your org UUID

In Forgecroft → Settings → Organization. Copy the UUID — the trust policy embeds it so only your org can assume the roles.

2. Deploy the CloudFormation template

Template: forgecroft-runner-oidc.yaml

Required parameters:

Parameter	Value
OrgId	Your Forgecroft org UUID from step 1
AllowedRegions	Comma-separated regions where apply is allowed (e.g. us-east-1,us-west-2)

Defaults are correct for the managed SaaS; leave the rest alone.

3. Create the credential

In Forgecroft → Settings → Credentials → New, choose AWS — OIDC. Paste the PlanRoleArn and ApplyRoleArn from the CloudFormation stack outputs. Save.

4. Attach to a workspace

Same flow as any other credential. Trigger a run — plan executes against the read-only role, apply against the write role.

Manage the OIDC trust in Forgecroft (recommended after bootstrap)

The CloudFormation template above is the bootstrap — you run it once via the AWS Console to establish the trust relationship. After that, you can put the same template under a Forgecroft workspace and manage it like any other infrastructure:

1. Commit forgecroft-runner-oidc.yaml to a repo (or convert it to Terraform aws_iam_openid_connect_provider + aws_iam_role resources).
2. Create a Forgecroft workspace pointing at that repo.
3. Attach the aws_oidc credential you just created.
4. Future changes to the trust policy (adding region restrictions, extending the apply role’s permissions, scoping to specific workspaces) flow through Forgecroft’s plan/apply cycle with audit trails and approvals.

This is the meta-recursive bit: Forgecroft uses its own OIDC integration to manage the AWS resources that grant Forgecroft access. The bootstrap CFN deploy is the only time you touch AWS Console for this account.

Caution

Be careful with one specific change: removing the apply role’s permission to manage IAM resources. If you do that, Forgecroft will be unable to update the role itself going forward, and you’ll have to fix it via CloudFormation Console again.

Trust policy details

The plan role’s trust policy:

{
  "Effect": "Allow",
  "Principal": { "Federated": "<oidc-provider-arn>" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": {
      "api.forgecroft.com:aud": "sts.amazonaws.com",
      "api.forgecroft.com:phase": "plan",
      "api.forgecroft.com:org_id": "<your-org-uuid>"
    }
  }
}

The apply role is identical except phase: "apply". The phase claim is what makes a stolen plan JWT useless for write operations.

Available claims

The JWT carries these claims; you can tighten trust policies by adding more StringEquals conditions:

Claim	Example
org_id	11111111-1111-1111-1111-111111111111
org_slug	acme
workspace_id	22222222-...
workspace_name	prod-vpc
run_id	33333333-...
phase	plan or apply
repo	acme/infra
branch	main
actor	alice@acme.com

For example, to restrict the apply role to a single workspace:

"api.forgecroft.com:workspace_id": "22222222-2222-2222-2222-222222222222"

When NOT to use this

• Existing static credentials work fine for you and you don’t need privilege separation. Stick with aws_static or aws_assume_role.
• You manage many AWS accounts. You’ll deploy the CFN once per account; for >10 accounts, scripting the deploys may be worthwhile.

Troubleshooting

“Could not connect to OIDC provider” during CloudFormation deploy. AWS validates the issuer URL is reachable. Confirm https://api.forgecroft.com/.well-known/openid-configuration returns 200 from your network.

AccessDenied on AssumeRoleWithWebIdentity. Check that OrgId in the CloudFormation stack matches your Forgecroft org UUID exactly. Trust policy claim conditions are case-sensitive.

Plan succeeds but apply fails with permission errors. The apply role’s permissions are * constrained by aws:RequestedRegion. If you added regions in Forgecroft after deploying the CFN, redeploy the stack with the updated AllowedRegions parameter.