name: deploy
on: { push: { branches: [main] } }

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-prod-deploy
          aws-region: eu-west-1
      - run: aws sts get-caller-identity

AWS: IAM Identity Provider plus Role Trust Policy

On AWS, the relying-party setup is a one-time IAM resource pair: an OIDC identity provider for GitHub, and a role with a trust policy that conditions on the GitHub OIDC token claims.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": "repo:opsio/platform:environment:production"
      }
    }
  }]
}

The sub claim is the security boundary. The format is repo:OWNER/REPO:ENVIRONMENT|ref:REF|pull_request. Pinning to environment:production means only workflows running with environment: production in the job spec can assume this role — and that environment carries required-reviewer protection at the GitHub side. This is the strongest default subject claim for production roles.

Azure: Workload Identity Federation on Entra ID

On Azure, the relying-party setup is a federated identity credential on an Entra ID app registration or managed identity.

az ad app federated-credential create \
  --id $APP_ID \
  --parameters '{
    "name": "github-prod",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:opsio/platform:environment:production",
    "audiences": ["api://AzureADTokenExchange"]
  }'

The Azure subject claim format is identical to AWS. The audience is fixed at api://AzureADTokenExchange. The Action handles the rest:

- uses: azure/login@v2
  with:
    client-id: ${{ vars.AZURE_CLIENT_ID }}
    tenant-id: ${{ vars.AZURE_TENANT_ID }}
    subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

GCP: Workload Identity Pools and Providers

On GCP, the relying-party setup is a Workload Identity Pool containing a Workload Identity Provider (the GitHub OIDC issuer) plus a service-account binding that allows the federated identity to impersonate a GCP service account.

gcloud iam workload-identity-pools providers create-oidc github \
  --location=global \
  --workload-identity-pool=gh-pool \
  --issuer-uri=https://token.actions.githubusercontent.com \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
  --attribute-condition="attribute.repository=='opsio/platform'"

gcloud iam service-accounts add-iam-policy-binding gha-deploy@my-proj.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/gh-pool/attribute.repository/opsio/platform"

The attribute-condition is the GCP equivalent of AWS's StringEquals on sub. Conditioning on assertion.repository alone is the loosest production policy you should accept; tighter policies condition on assertion.environment or assertion.ref as well.

The Five Misconfigurations That Defeat OIDC

OIDC federation is only as strong as its trust policy. The five mistakes that turn a "secure" setup into a wide-open trust relationship:

1. Wildcard subject claims — repo:opsio/* or repo:opsio/platform:* grants any workflow in any repo (or in the platform repo from any branch) full access. Always pin to a specific ref, environment, or job_workflow_ref
2. Missing audience check — the audience claim defaults to a generic value if not configured. AWS, Azure, and GCP each use a specific audience; configure it explicitly and verify it on the relying-party side
3. Trusting any branch — StringLike on sub with :ref:refs/heads/* gives every feature-branch workflow production access. Production roles should pin to environment:production only
4. Pull-request subject reuse — pull_request workflows from forks have sub values like repo:owner/repo:pull_request. Trusting that pattern lets any external contributor's PR assume your role on any pull-request workflow run
5. One role for everything — using a single high-privilege role for staging and production deploys, dependency updates, and ad-hoc workflows defeats the per-environment isolation OIDC enables. Use one role per logical scope

Migration: How to Move Off Static Secrets

For an existing estate of workflows using long-lived AWS_ACCESS_KEY_ID/AZURE_CREDENTIALS/GCP_SA_KEY secrets, the migration follows a predictable pattern:

1. Inventory every workflow secret with cloud-provider credentials. The GitHub REST API at /repos/:owner/:repo/actions/secrets lists them; you cannot read values, but the names and last-modified dates are enough
2. Categorise by environment and minimum scope. Most static-secret estates use one or two over-privileged roles; the OIDC migration is a chance to split them
3. Provision the OIDC identity provider and per-environment roles in each cloud account
4. Migrate workflows one job at a time, replacing the static-secret env: block with the cloud-provider Action and id-token: write
5. Rotate (then delete) the original IAM access keys, service principal secrets, or service-account JSON keys

For a typical mid-market estate (50-200 workflows), this migration is 2-4 weeks of focused work, much of which is testing rather than configuration. The upside is that after migration, the cloud-side audit trail (CloudTrail, Azure Activity Log, Cloud Audit Logs) carries the GitHub workflow context per call — every API action is traceable to the exact workflow run that made it.

How Opsio Helps

Opsio's security practice runs OIDC migrations as part of broader CI/CD security engagements. We typically deliver the federation setup, trust-policy hardening, and secrets sweep in 4-8 weeks alongside our wider Opsio's cloud security work. For organisations operating Opsio's managed detection, the migrated estate's audit-trail richness becomes a meaningful uplift in detection quality. Customers who want the workflow design and federation work bundled into a single managed offering use our end-to-end github actions, which includes OIDC federation by default in every engagement.