What it is: OpenID Connect, commonly abbreviated OIDC, is an identity-verification standard that lets one system prove “who I am” to another system in a secure, verifiable way, using short-lived, cryptographically signed tokens rather than a shared, long-lived secret like a password. In the context of GitHub Actions, OIDC lets a running workflow request a fresh, temporary token proving its identity, which a cloud provider can then verify and use to grant temporary access, all without GitHub and the cloud provider ever needing to share a permanent, stored secret in advance.

Why it exists: Before OIDC support, a workflow needing to access a cloud provider — to deploy an application, for instance — typically needed a long-lived access key or password stored as a secret directly in GitHub, covered in a related guide on GitHub Actions. This approach works, but it creates a permanent, valuable target: if that stored secret is ever leaked, stolen, or simply forgotten about and left active long after it’s needed, it remains a genuine, standing risk indefinitely. OIDC exists specifically to remove this permanent secret from the equation entirely.

Where it’s used: OIDC-based cloud authentication is used wherever a GitHub Actions workflow needs to interact with a cloud provider’s resources — deploying infrastructure, uploading build artifacts to cloud storage, or managing cloud services — replacing what would otherwise require a stored, long-lived credential.

Practical example: A workflow needs to deploy a new version of an application to a cloud provider’s infrastructure. Instead of that workflow retrieving a stored, long-lived cloud access key from GitHub’s secrets, it requests a short-lived OIDC token, presents that token to the cloud provider, and the cloud provider — having been configured in advance to trust tokens issued by GitHub for this specific repository — grants temporary access valid only for the duration of that one deployment.

A long-lived cloud access key stored as a GitHub secret has several inherent, structural weaknesses, regardless of how carefully it’s managed. It exists continuously, whether or not a workflow happens to be running at any given moment — meaning it’s a permanent target for theft, twenty-four hours a day, not just during the brief windows when it’s actually needed. If it’s ever accidentally logged, exposed in an error message, or leaked through any other means, it typically remains valid and usable until someone notices and manually revokes it — a window of vulnerability that could last anywhere from minutes to, in unfortunate cases, months. And managing many such credentials across many repositories creates real, ongoing operational burden: rotating them periodically, tracking which ones are still genuinely needed, and ensuring old, unused ones are properly retired.

OIDC addresses all of these weaknesses at once by removing the permanent credential from the picture entirely. Instead of a secret that exists continuously, a token is requested and issued only at the exact moment it’s needed, and it expires automatically, on its own, shortly afterward — there’s no persistent secret sitting around to leak, and no manual rotation process required, since there’s fundamentally nothing long-lived to rotate.

The core problem OIDC solves: how do you let a GitHub Actions workflow securely access cloud resources, without needing to store a permanent, standing secret that represents an ongoing, continuous security risk regardless of how carefully it’s managed?

This three-party structure is the foundation of trust the entire system relies on: the cloud provider never needs to directly, permanently trust every individual repository or workflow with a stored secret — it only needs to trust GitHub, as the identity provider, once, and then verify each specific token’s claims against that established trust relationship every time a token is presented.

flowchart LR
    A["Workflow requests an OIDC token from GitHub"] --> B["GitHub issues a signed token describing this specific run"]
    B --> C["Workflow presents the token to the cloud provider"]
    C --> D["Cloud provider verifies GitHub's signature"]
    D --> E{"Does the token's claims match a configured trust rule?"}
    E -->|Yes| F["Short-lived cloud credentials are issued to the workflow"]
    E -->|No| G["Access is denied"]
    

Step by step, in plain language: first, a running workflow, configured with the necessary permission to do so, requests an OIDC token from GitHub’s own identity provider service. Second, GitHub issues a token — a cryptographically signed piece of data — that includes specific, verifiable claims about this exact run: which repository it belongs to, which branch or event triggered it, and other identifying details. Third, the workflow presents this token directly to the cloud provider, as part of an authentication request. Fourth, the cloud provider independently verifies the token’s cryptographic signature, confirming it was genuinely issued by GitHub and hasn’t been tampered with. Fifth, the cloud provider checks whether the token’s specific claims match a trust rule it was previously configured with — for instance, “only trust tokens from this exact repository’s main branch.” If the claims match, the cloud provider issues its own short-lived cloud credentials, valid only for a brief period, which the workflow then uses for the remainder of its task. If the claims don’t match any configured trust rule, access is denied entirely.

Notice that steps 3 through 6 — the actual, individual deployment — require no ongoing, manual secret management at all, since the entire authentication process is freshly, automatically re-established every single time, based on the one-time trust configuration established in step 1.

A trust rule on the cloud provider’s side defines exactly which OIDC token claims will be accepted as sufficient proof of identity. A poorly scoped rule — for instance, trusting any token issued for any workflow in an entire, large organization, regardless of repository or branch — grants far more access than most individual deployments genuinely need, undermining much of OIDC’s intended benefit. A well-scoped rule, by contrast, trusts tokens only from a specific repository, and often only from a specific branch or a specific, particular type of triggering event, such as only tokens generated from the main branch’s deployment workflow specifically.

The general security principle here mirrors least-privilege access, covered in a related guide on scaling Git for large teams: scope every trust rule as narrowly as the genuine task actually requires, rather than broadly, out of convenience or to avoid configuring several more specific rules.

An OIDC token issued by GitHub contains a set of specific, verifiable claims — structured pieces of information about the specific workflow run requesting it. These typically include which repository and organization the workflow belongs to, which specific branch or tag triggered the run, what kind of event triggered it (a push, a pull request, a manually initiated run), and often a specific, configured deployment environment name if one was used. Every one of these claims is cryptographically bound to the token’s signature — meaning none of them can be forged or altered without invalidating the entire token’s verification.

It’s worth understanding that these claims describe the workflow run’s context, not any individual human’s identity — OIDC in this setting authenticates “this specific, automated workflow run,” not “this specific person,” which is an important distinction from other, more familiar uses of OIDC for human user sign-in that some readers may already be familiar with from unrelated contexts.

You may likeWhat Is Concurrency Control in Workflows in GitHub?→

GitHub allows workflows to target a specifically configured environment — a named deployment target, like “production,” that can have its own protection rules, such as requiring a specific person’s manual approval before a workflow targeting it is allowed to proceed. Because an OIDC token’s claims can include which environment a run was associated with, a cloud provider’s trust rule can be scoped specifically to “only trust tokens associated with the production environment” — meaning cloud access is only ever granted to runs that have already passed through whatever manual approval gate that environment requires.

A stored, shared secret used across many workflow runs makes it genuinely difficult to distinguish, after the fact, exactly which specific run performed a given cloud action — the credential itself carries no inherent record of which run used it. An OIDC-based approach, by contrast, means every single cloud authentication event can be traced back to the specific, exact claims of the token that authorized it — which repository, which branch, which run, which environment — providing a genuinely detailed, trustworthy audit trail without any additional manual logging effort required on the workflow’s part.

The core trade-off to internalize: OIDC trades a modest, one-time investment in correct, careful trust-rule configuration for a substantial, ongoing reduction in standing security risk and manual credential-management burden — a trade that becomes more valuable, not less, the more workflows and cloud interactions an organization has.

Because OIDC removes the need to individually provision, store, and rotate a long-lived secret for every single repository or workflow that needs cloud access, it scales considerably more gracefully than the stored-secret approach as an organization’s number of repositories and workflows grows. Rather than an ever-growing list of individually managed secrets, each requiring its own tracking and periodic rotation, an organization typically maintains a much smaller number of trust-rule configurations on the cloud provider’s side, each scoped to cover an appropriate, well-defined set of repositories or workflows.

This scaling benefit compounds precisely because it directly addresses one of the genuine operational pain points covered in a related guide on scaling Git for large teams — managing security and access consistently across a rapidly growing number of contributors and repositories — removing an entire category of manual, error-prone credential management that would otherwise grow linearly, and painfully, with organizational size.

As covered in a related guide on GitHub Actions, workflows triggered by pull requests from outside, untrusted contributors receive additional restrictions by default — this same caution applies directly to OIDC token requests, since a workflow modified by an untrusted contributor’s pull request should never be automatically granted the same trust as a change made and reviewed entirely within the organization itself.

It’s also worth remembering that while the token itself is short-lived, the cloud credentials it’s exchanged for still grant real, genuine access for their own validity period — appropriately scoping what those cloud credentials are actually permitted to do, following the same least-privilege principle covered in a related guide, remains just as important as it would be with any other form of cloud access, regardless of how that access was originally obtained.

The Narrow-Scope-by-Default Pattern configures trust rules as specifically as possible from the very start — scoped to exact repositories, branches, and environments — rather than starting broad and intending to narrow the scope “later,” a step that’s easy to postpone indefinitely once things are already working.

You may likeWhat Is SAML/SSO Integration?→

The Environment-Gated Production Pattern combines OIDC trust rules with protected deployment environments requiring manual approval, as covered in Chapter 9, specifically for the most sensitive, production-level cloud access.

Common anti-patterns to avoid: the Broad-for-Now pattern described above; the Unscoped-Cloud-Permissions anti-pattern (correctly narrowing the OIDC trust rule itself, but then granting the resulting cloud credentials far broader permissions than the actual task requires, undermining much of the careful trust-rule work); and the Ignore-Untrusted-Contributor-Risk pattern (failing to apply the same caution to OIDC token requests from pull-request-triggered workflows that GitHub Actions itself already applies to secrets more broadly, as covered in Chapter 13).

Common mistakes beginners make: configuring an overly broad trust rule to get things working quickly, without returning to properly narrow its scope; assuming OIDC alone makes a workflow secure without also scoping the resulting cloud credentials appropriately; and forgetting that untrusted, pull-request-triggered workflow runs deserve the same caution around OIDC token requests that they already receive around ordinary stored secrets.