For years, the standard way to let GitHub Actions deploy to a cloud provider was to paste a long-lived access key into a repository secret. That key never expired unless someone rotated it, and if it leaked in a public repository, a fork, or a log file, it could grant full access until someone noticed and revoked it. It was convenient, and it was one of the most common sources of cloud breaches.
OpenID Connect federation replaces that model. Instead of storing a credential, the workflow requests a short-lived identity token from GitHub, presents it to the cloud provider, and receives temporary credentials that expire in minutes or hours. There is nothing long-lived to leak, nothing to rotate on a schedule, and the trust relationship can be scoped to a specific repository, branch, or environment. The cloud provider checks who is asking, not just what secret they hold.
This article explains how OIDC federation works in GitHub Actions, how to configure it for AWS, Azure, and Google Cloud, and the pitfalls that turn a good idea into a false sense of security: overly broad trust policies, missing subject conditions, and workflows that request credentials they never need.
#Quick Answer: Let GitHub Prove Identity, Let the Cloud Issue Temporary Credentials
Configure your cloud provider to trust GitHub's OIDC issuer, scope that trust to a specific repository and environment using subject conditions, grant the federated role only the permissions the deployment needs, and request credentials in the workflow with id-token: write permission and no stored secrets. The workflow exchanges a short-lived OIDC token for temporary cloud credentials that expire automatically, so there is no long-lived key to leak, steal, or rotate. That single change removes an entire class of credential exposure, provided the trust policy is narrow: a trust policy that accepts any repository in your organisation is barely better than a shared secret.
The core flow has three steps. GitHub mints a JSON Web Token asserting the workflow's identity, including repository, branch, environment, and actor. The cloud provider validates that token against GitHub's issuer and checks it against the trust conditions you defined. If it matches, the provider issues temporary credentials scoped to the role you specified. Those credentials expire on their own, typically within an hour, and cannot be refreshed without a new workflow run presenting a new token.
#How OIDC Federation Works Under the Hood
OIDC is an identity layer on top of OAuth 2.0. In this context, GitHub acts as the identity provider. When a workflow job runs with id-token: write permission, it can request a token from GitHub's OIDC endpoint. That token is a signed JWT containing claims: the issuer, the subject identifying the workflow, the repository, the branch or tag, the environment if one is specified, the actor who triggered the run, and an audience value that defaults to a cloud-specific identifier.
The cloud provider does not trust the token because it looks plausible. It fetches GitHub's public signing keys, verifies the signature, checks issuer and audience, then evaluates your trust policy. The subject claim is the critical field for scoping. A subject for a branch deployment looks like repo:octo-org/octo-repo:ref:refs/heads/main, and for an environment deployment like repo:octo-org/octo-repo:environment:production. The difference matters: environment subjects let you tie trust to GitHub's environment protection rules, including required reviewers, so a deployment to production requires approval before credentials are even issued.
Temporary credentials are the payoff. AWS issues them via AssumeRoleWithWebIdentity, Azure via federated credentials on a service principal or managed identity, and Google Cloud via workload identity federation. In every case, the credentials carry an expiry, typically 15 minutes to one hour for a deployment job, and they inherit exactly the permissions of the role they assume, no more. If a token or temporary credential leaks in a log, its usefulness decays within the hour, and it cannot be used to mint new long-lived access. Contrast that with a static key, which remains valid until a human notices and revokes it, often weeks later.
One subtlety is worth stating plainly: OIDC does not make a compromised workflow safe. An attacker who can run arbitrary code in a workflow trusted to deploy to production can request the same temporary credentials the legitimate workflow would get. Federation removes the stored secret as a target; it does not remove workflow security as a concern. Pinning actions by SHA, restricting production approvers, and reviewing workflow changes remain essential.
#Configuring AWS with OIDC
AWS is the most common target, and its configuration illustrates the pattern clearly. First, create an OIDC identity provider in IAM pointing at GitHub's issuer, https://token.actions.githubusercontent.com, with the audience sts.amazonaws.com. Then create a role with a trust policy that allows sts:AssumeRoleWithWebIdentity only when the subject matches your repository and branch or environment. A narrow trust policy looks like this:
{
"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:my-org/my-app:ref:refs/heads/main"
}
}
}]
}The workflow side is deliberately small. The job needs id-token: write and contents: read, and the official AWS action exchanges the token for credentials:
jobs:
deploy:
permissions:
id-token: write
contents: read
steps:
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-deploy
aws-region: eu-west-1
- run: aws s3 sync ./dist s3://my-app-bucket/Two mistakes recur here. The first is using a wildcard subject such as repo:my-org/*, which trusts every repository in the organisation, including future ones an attacker might create or compromise. The second is granting the role broad permissions, such as AdministratorAccess, because it is easier than working out the minimal set. Both defeat the purpose. Scope the subject to the exact repository and ref or environment, and scope the role to the resources the deployment touches, using IAM policy conditions where possible. For production, prefer an environment subject combined with GitHub environment protection rules, so a human approval gates credential issuance, not just deployment.
#Azure and Google Cloud Patterns
Azure's pattern is conceptually identical but uses federated credentials on an app registration or managed identity. You create a federated credential that trusts GitHub's issuer, with a subject matching your repository and environment, and an audience of api://AzureADTokenExchange. The workflow uses the Azure login action with client-id, tenant-id, and subscription-id, and no client secret:
- uses: azure/login@v2
with:
client-id: ${{ vars.AZURE_CLIENT_ID }}
tenant-id: ${{ vars.AZURE_TENANT_ID }}
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}Client IDs and tenant IDs are identifiers, not secrets, so storing them in variables rather than secrets is appropriate. The security lives in the federated credential's subject condition, not in hiding the client ID. As with AWS, the common failure is a subject that is too broad, or a service principal granted Contributor across the whole subscription when the deployment only touches one resource group. Scope the role assignment to the resource group, and use environment subjects for production so approvals gate access.
Google Cloud uses workload identity federation, which maps an external identity to a Google service account. You create a workload identity pool, a provider for GitHub, and an IAM binding that allows the federated identity to impersonate a service account, with an attribute condition restricting it to a specific repository. The workflow authenticates with the Google auth action, again with no stored key:
- uses: google-github-actions/auth@v2
with:
workload_identity_provider: projects/123/locations/global/workloadIdentityPools/github/providers/github
service_account: [email protected]The attribute condition is where Google's scoping lives, and it deserves the same care as an AWS trust policy or Azure federated credential. A mapping that accepts any repository in the pool is a broad trust grant dressed up as federation. Restrict by repository and, where the workflow supports it, by environment or branch, and grant the service account only the roles the deployment needs, such as Storage Object Admin on a single bucket rather than project-wide Editor.
Across all three clouds, the operational benefit is the same: no secret rotation calendar, no rotation runbook, and no emergency revocation when a repository is made public or a log shared. Temporary credentials expire on their own. The work shifts from managing secrets to managing trust policies, which are versioned, reviewable, and visible in the cloud console, while stored secrets are invisible until they leak.
#Pitfalls, Scoping, and Migration
Migration from stored secrets should be staged, not big-bang. Start with a low-risk workflow, such as deploying a staging environment, and run it with OIDC while the old secret remains available but unused. Verify that deployments succeed, that the role's permissions are sufficient, and that the trust policy rejects a run from an untrusted branch. That negative test matters: trigger a workflow from a feature branch or a fork and confirm it cannot assume the production role. If it can, your subject condition is too broad.
Pay attention to reusable workflows and pull request triggers. A workflow triggered by pull_request from a fork runs in a restricted context, but a workflow triggered by pull_request_target runs with repository context and can be dangerous if it requests OIDC credentials. Do not request id-token: write in workflows that execute untrusted code, and never pass OIDC-derived credentials into a step that runs code from a pull request. The same caution applies to third-party actions: an action that exfiltrates the OIDC token can exchange it for cloud credentials within its lifetime, so pin actions by commit SHA and audit actions that run in jobs holding deployment credentials.
Session duration is a tuning knob, not a detail. Shorter is safer, but a deployment that legitimately takes 45 minutes will fail if credentials expire after 15. Set duration to cover the job with modest headroom, and split long-running deployments into separate jobs that each request their own credentials rather than stretching one session. Also note that OIDC tokens themselves are short-lived and single-use in practice; they are not a substitute for the temporary cloud credentials, and they should never be logged or echoed. GitHub masks secrets in logs, but an OIDC token printed deliberately can still be copied within its window, so treat it as sensitive during the run.
Finally, keep old secrets out after migration. Deleting a secret from GitHub does not delete copies in forks, logs, or old runs, so rotate any long-lived key you replaced, even if you believe it was never exposed. Rotation after migration is the point at which risk actually drops. Until then, the old key remains a parallel path into your cloud account.
For teams hardening the whole pipeline, OIDC pairs naturally with signed artifacts and admission control. Once deployments no longer need stored cloud credentials, the next credential to eliminate is often the registry push secret. The direction is consistent: replace long-lived secrets with short-lived, identity-bound credentials at every stage.
#Frequently Asked Questions
Does OIDC eliminate the need for secrets in GitHub Actions entirely?
No, it eliminates stored cloud credentials, which are the highest-risk secrets. You may still need secrets for third-party services that do not support OIDC, such as some SaaS APIs. The goal is to remove the secrets that grant broad cloud access and replace them with federation, then reduce the remainder to the smallest set possible, each scoped to one purpose.
What happens if an OIDC token leaks in a workflow log?
The token is short-lived, typically valid for minutes, and can only be exchanged for the role defined in the trust policy. Its usefulness decays quickly, and it cannot mint a long-lived credential. That is a major improvement over a leaked static key, but it is not a reason to be careless: treat tokens as sensitive during the run, avoid printing them, and scope the role so a leaked token grants as little as possible.
Should I use a branch subject or an environment subject in the trust policy?
Prefer an environment subject for production, because it ties credential issuance to GitHub environment protection rules, including required reviewers. Branch subjects are simpler and adequate for staging or non-sensitive deployments, but they do not add an approval gate. A branch subject also trusts any workflow run on that branch, including runs triggered by contributors with push access.
Can a forked repository use my OIDC trust policy?
Only if your trust policy allows it, and it should not. A fork has a different repository identity, so a subject condition scoped to your exact repository will reject it. Be careful with wildcard subjects and with pull_request_target workflows, which run in your repository context and can be exploited if they execute untrusted code while holding deployment credentials.
How do I migrate existing workflows without breaking deployments?
Migrate one workflow at a time, starting with staging. Configure the OIDC trust policy, update the workflow to request credentials via OIDC, verify deployments and test that untrusted branches are rejected, then rotate and delete the old stored secret. Rotating the old key is essential; until you do, it remains a parallel path into your cloud account.
#Sources and Further Reading
- GitHub documentation, configuring OIDC in cloud providers: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers
- GitHub documentation, security hardening for GitHub Actions: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/security-hardening-for-github-actions
- AWS documentation, creating a role for OIDC federation: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html
- Microsoft documentation, federated credentials for Azure service principals: https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation
- Google Cloud documentation, workload identity federation: https://cloud.google.com/iam/docs/workload-identity-federation
- OpenID Connect Core specification: https://openid.net/specs/openid-connect-core-1_0.html