GitHub Actions OIDC can let a workflow obtain short-lived cloud credentials without storing a long-lived cloud access key in repository secrets. That is a valuable improvement, but the security outcome depends on the cloud trust policy, workflow permissions, and deployment role. Removing a static key does not automatically remove excessive access.
This guide explains the decisions behind a safer setup for repositories and cloud environments you administer. Provider-specific configuration differs, so use the supported integration for your cloud rather than copying a trust policy from an unrelated platform.
1. Understand the GitHub Actions OIDC trust exchange
OpenID Connect lets GitHub issue a signed identity token containing claims about the workflow execution. A configured cloud service validates the token and its claims, then can issue temporary credentials for an approved role. The workflow uses those credentials to perform the deployment.
The identity token is not itself unlimited permission to your cloud account. It is evidence that the cloud provider evaluates against a trust relationship. The permissions attached to the resulting cloud role are a separate control, and both layers need review.
Document the issuer, intended audience, subject conditions, and target role. This makes the relationship understandable during incident response and helps prevent a future configuration change from silently broadening which workflows can authenticate.
2. Grant token permission only where needed
A job or workflow needs id-token: write to request an OIDC identity token. That permission enables the token request; it does not grant write access to arbitrary repository content or cloud resources. Keep the other GitHub token permissions independently scoped.
Where practical, grant the permission at the deployment job rather than to every job in the workflow. A test or formatting job usually does not need cloud deployment identity. Separating jobs can reduce the number of steps that execute in a privileged context.
A permissions fragment might look like this:
permissions:
contents: read
id-token: writeThis is not a complete deployment configuration. It does not select a role, define cloud trust, or prove that the workflow should receive production access. Check the full workflow and your provider’s authentication action before using it.
3. Restrict cloud trust to approved execution contexts
Use the provider’s supported conditions to restrict which repository and workflow contexts can assume the role. Conditions commonly involve claims such as audience and subject, but supported claim handling varies by cloud service. Avoid accepting every token from an entire organization when only one deployment path needs access.
Branches, tags, pull requests, and environments can affect the token’s subject and other claims. Inspect the expected claim values for the actual workflow. A trust condition designed for a branch-based deployment may not match a job that uses an environment.
Define what should happen for forked contributions and untrusted pull requests. Do not allow attacker-controlled code to run with production deployment identity merely because it is associated with a legitimate repository. Review workflow triggers and the checked-out code together.
4. Keep the cloud role narrowly authorized
The trust policy answers who can assume a role. The role’s access policy answers what that identity can do. Give the deployment only the operations and resources required for its job, and separate staging from production where the architecture permits.
Avoid using an administrator role as a shortcut to make the initial integration work. If a deployment fails, inspect the required operation rather than granting every permission. Infrastructure provisioning, artifact upload, and application rollout may deserve different roles.
Review the temporary credential duration and provider limits. Shorter duration can reduce exposure, but it must support legitimate deployment behavior and recovery. A narrowly scoped temporary credential is useful; a temporary administrator credential can still cause substantial damage during its lifetime.
5. Protect the workflow that receives identity
Treat workflow files and reusable deployment components as security-sensitive code. Use the repository’s review and branch protection practices so unreviewed changes cannot freely alter privileged steps. A cloud trust policy cannot make a malicious authorized workflow safe.
Review third-party actions and pin them according to your team’s supply-chain policy. Minimize the steps that run after cloud authentication. A build script from an untrusted source can read credentials or invoke cloud APIs if it executes in the authenticated job.
Keep reusable workflows’ trust boundaries explicit. Confirm what identity claims the provider sees and what callers are permitted. Our GITHUB_TOKEN permissions guide covers a related but distinct permission boundary inside GitHub.
6. Test both acceptance and rejection
In a controlled environment, verify that the approved deployment context can obtain the intended role and perform only the required action. Then test contexts that should fail: another branch, another repository, an unexpected audience, or a workflow path outside your policy.
Check cloud audit evidence for the resulting assumed identity and operations. A successful authentication message is not proof that resource access is correctly limited. Also verify that the role cannot modify unrelated resources or read secrets outside the deployment’s scope.
Use diagnostics without printing live tokens or credential values into logs. Token claims can be informative, but operational metadata may still be sensitive. Restrict access to debugging output and remove temporary diagnostic steps after the investigation.
7. Retire static keys and maintain the relationship
Once the OIDC flow works and rollback is planned, retire obsolete long-lived deployment credentials through the provider’s supported process. Leaving the old key active preserves an unnecessary access path even when normal deployments have moved to temporary credentials.
Document the repository, role, environment, owners, and review schedule. Recheck the trust relationship when repositories move, branch conventions change, reusable workflows are replaced, or a new environment is introduced. OIDC configuration is not a one-time security finish line.
Keep a recovery path that does not depend on permanently overprivileged credentials. If a deployment identity fails, the team should know how to diagnose claims and policy without immediately reintroducing an unrestricted static key.
A deployment review checklist
- Only relevant jobs can request an identity token.
- Audience and subject conditions match approved contexts.
- Pull-request and fork behavior is explicitly reviewed.
- The cloud role has only required resource permissions.
- Workflow changes require appropriate review.
- Negative authentication and authorization tests pass.
- Old deployment keys are revoked after a controlled migration.
Frequently asked questions
Does id-token: write give a job cloud administrator access?
No. It allows the job to request an OIDC token. Cloud access depends on a provider accepting that token and the permissions attached to the resulting identity.
Is OIDC enough to secure an unsafe workflow?
No. Untrusted code running in a privileged job can still misuse temporary credentials. Protect workflow inputs, dependencies, review requirements, and execution context.
Where should I verify claim behavior?
Consult the GitHub OpenID Connect reference and your cloud provider’s supported integration. Test actual claim values and denial cases instead of assuming every provider handles subjects identically.
