GitHub Openid Connect
You set up github openid connect by linking your repo to a cloud role. Your build jobs then log in with short-lived tokens instead of stored keys. Many teams start by saving cloud keys inside repo settings. Those static keys stay valid for months and create big risks if leaked. When teams switch to federated login, they often make the trust rule too wide. A broad rule lets any branch or fork assume a powerful cloud role. How github openid connect works in your build jobs The workflow relies o
OpenID Connect (OIDC) + GitHub Actions Security: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up github openid connect by linking your repo to a cloud role. Your build jobs then log in with short-lived tokens instead of stored keys. Many teams start by saving cloud keys inside repo settings. Those static keys stay valid for months and create big risks if leaked. When teams switch to federated login, they often make the trust rule too wide. A broad rule lets any branch or fork assume a powerful cloud role.
How github openid connect works in your build jobs
The workflow relies on a direct trust link between two systems. Your cloud provider trusts the GitHub token service as an identity provider. When a build job starts, the runner asks this service for a signed token. That token holds facts about the job, called claims. The claims list the repo name, the branch, the workflow, and the actor.
The build runner sends this signed token to your cloud provider. The cloud provider checks the digital signature against public keys from the token service. Next, the cloud provider reads the claims inside the token. It compares those claims against the trust policy on the target role. If the repo and branch match the rule, the cloud issues a temporary credential. The build job uses this temporary key to run tasks, and it expires soon after.
How to scope trust rules for cloud roles
A safe setup needs strict conditions on the cloud role trust rule. You must check the subject claim on every login request. The subject string tells the cloud which repo and branch started the job. If you only check the repo name, any pull request can take the role. A bad actor could open a pull request and run harmful commands.
You can lock the subject claim to your main branch or a release tag. You can also require a specific job target, like production, inside the claim. Always check the audience claim so tokens meant for one service fail elsewhere. Give the cloud role only the exact permissions needed for that single job. Split build roles and deploy roles so a test run cannot change live servers.
OpenID Connect (OIDC) + GitHub Actions Security: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What federated login solves and what it misses
Federated login removes static cloud keys from your repo secret store. Your team no longer needs to rotate long-lived keys by hand every quarter. If a token leaks during a build, it stops working when the timer ends. It also ties every cloud login back to a specific workflow run.
Still, this setup only checks identity at the start of the job. Once the job gets the cloud role, it holds full role permissions. The login check does not inspect the actual commands or queries sent in flight. If a build script has a bug, it can still drop a live table. If a third-party action is compromised, it can read private data like emails or card numbers. Static role rules cannot block one bad command while allowing safe ones. Teams still need a way to inspect every action and mask fields like phone numbers or national IDs in results.
Add runtime guardrails and masking beside your databases and APIs
Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits beside the service as an open-source proxy, a sidecar for your database or API.
Before a query runs, hoop.dev guardrails check the statement against your rules. An AI Analyzer you configure can score intent or hold risky calls for human review. Next, hoop.dev data masking rewrites sensitive fields in responses, and each verdict is logged per listener. Explore the MIT-licensed project on GitHub.
Frequently asked questions
Why did my workflow fail the cloud role trust check?
The subject claim in the token did not match the condition on your cloud role. Check the exact repo name, branch name, or tag in the job run log. Update the role trust rule so it matches the exact string sent by the runner.
Can pull requests from forks use federated login roles?
By default, workflows from public forks get read-only tokens and cannot pass branch checks for protected roles. You should never allow untrusted pull requests to assume roles that write data. Keep deploy roles locked to your main branch after code review is done.
Do I still need to manage cloud role permissions with token login?
Yes, token login only changes how the runner proves its identity to the cloud. Once logged in, the runner can do anything the attached cloud role allows. You must still scope the role policy to the smallest set of actions.