What is OIDC Authentication and why do I want it.

Github supports OpenID Connect which allows GitHub to act as an identity provider.

By setting up a trust relationship in Azure/AWS to Github, you can get github to assume temporary credentials within your cloud provider to do your deployments for you. This trust relationship gives you fine-grained control of which repositories and branches can assume the role/access token.

GitHub Actions workflow
  └─ requests OIDC token from GitHub
       └─ presents token to AWS STS / Azure AD
            └─ cloud validates token against GitHub's JWKS endpoint
                 └─ returns short-lived credential (IAM role / access token)

Repository link

Prerequisites

• Terraform cloud configured (terraform login)
  • It’s expected that the user has Org level permissions to be able to create a new project + workspaces in that project.
• AWS CLI configured (aws login)
• Azure CLI configured (az login)

Remote state (Terraform Enterprise / Terraform Cloud)

The workspace is auto-created on first terraform init if it does not already exist.

Edit the cloud block in aws/providers.tf / azure/providers.tf to match your organization and project:

cloud {
  hostname     = "app.terraform.io"
  organization = "my-org"
  workspaces {
    project = "oidc_base"            # auto-created on init (need org level token)
    name    = "github-oidc-aws"      # auto-created on init
  }
}

AWS module

How it works

What it creates

Inline policies (aws/policies/)

Every *.json in aws/policies/ is loaded in and attached to the role. Policy files are terraform template files that inject account_id for more secure control of resources.

At time of writing there is one policy: docker-deploy which is used to deploy resources for a post that I’m writing.

Usage

cd aws
terraform init
terraform apply

Variables

Outputs

Tests

I haven’t included tests, the thing that I’d want to check is that SrzStephen is always in the repo but it’s a bit hard to do when you’re loading in template files the way I wanted to.

Azure module

How it works

What it creates

Usage

[!Warning] If you’re using terraform enterprise a remote executor, you may run into some problems here, set your workspace executor to local by default.

cd azure
terraform init
terraform apply

Variables

Outputs

Tests

cd azure
terraform test

The test suite (azure/tests/oidc_trust.tftest.hcl) verifies that:

• Every federated credential subject is scoped to the correct GitHub organisation.
• All subjects are restricted to the main branch (ref:refs/heads/main).
• The number of credentials matches the number of configured repositories.

GitHub Actions workflows

See .github/workflows/ for the CI workflows:

• terraform.yml — runs on every push and PR: format check (terraform fmt -check -recursive), then terraform validate for both modules (no backend, no credentials required).
• verify-oidc.yml — triggered on push to main, PRs, and workflow_dispatch: assumes the AWS role and logs in to Azure to confirm that OIDC authentication works end-to-end.

Required secrets