Entra workload federation: when a GitHub environment hides the branch boundary

Identify what the environment subject actually trusts

GitHub issues an OIDC token describing a workflow job; Microsoft Entra evaluates that token before issuing an access token. The important boundary is that GitHub’s default environment-based subject does not also contain the branch. A federated credential trusting that environment therefore does not, through its subject match alone, distinguish intended deployment branches from unintended ones. A separate ref claim can describe the branch, but its presence is not evidence that the configured Entra trust enforces it.

For a hypothetical repository using the previous subject format, repo:example-org/payments:environment:production identifies the repository and environment, not main. Do not copy that format without checking the repository’s actual claims. GitHub documents an immutable default subject containing owner and repository IDs for repositories created after July 15, 2026; that format is unavailable on GitHub Enterprise Server. The review recommendation is to establish the active subject format first, then identify where branch restrictions are enforced rather than assuming the subject provides them.

Evidence: Workload Identity Federation Cheat Sheet¶, Workload identity federation concepts, OpenID Connect

Verify Entra’s exact matching contract

Microsoft Learn documents case-sensitive matching between the federated identity credential’s issuer, subject and audience and the corresponding values in the external token. Review all three against the actual deployment job: the issuer must identify GitHub’s OIDC provider, the subject must represent the intended workload context, and the audience must match the value supplied for exchange. Configure trust on the intended app registration or user-assigned managed identity. Successful exchange authenticates that workload; resource access still depends on its assigned permissions.

As a review recommendation, compare claims without printing or retaining the complete token, and use the supported federation integration rather than building a pipeline token validator. Microsoft’s documented exclusions also matter: Microsoft Entra-issued tokens cannot be used as the external tokens in this federated identity flow. Microsoft identity platform stores only the first 100 signing keys downloaded from an external issuer’s OIDC endpoint; issuers exposing more may encounter federation errors. Neither limitation supplies a missing branch restriction.

Evidence: Workload Identity Federation Cheat Sheet¶, Workload identity federation concepts, OpenID Connect

Put the branch boundary on the trusted environment

Next, configure deployment branch and tag restrictions on the GitHub environment named by the trusted subject. The practical recommendation is to permit only the refs intended for that deployment context, reviewing tags as well as branches. For a hypothetical production deployment intended only for main, configure the environment accordingly rather than treating its production name as protection. Review who can use the environment and require review of trusted workflow changes. These controls complement Entra matching; they do not change its documented comparison rules.

Then review the deployment job itself. Keep untrusted pull request code out of jobs able to obtain production access, and grant id-token: write at job level only where cloud authentication is required. That permission enables OIDC token requests; it does not grant Azure permissions. Separately restrict the cloud identity’s resources and operations, and use distinct production and non-production identities. Keep federation and permission administration outside ordinary deployment roles. Federation removes reusable pipeline credentials, but does not make compromised authorized code trustworthy.

Evidence: Workload Identity Federation Cheat Sheet¶, OpenID Connect

Test the gate, the exchange and the resulting access

Before production use, run a controlled positive test from an allowed ref and confirm both token exchange and the required deployment operation. Then attempt the same environment deployment from an unauthorized branch and tag. Verify that environment restrictions stop the deployment job before its authentication step; do not describe this as Entra independently rejecting the branch. Also test unauthorized repositories and job contexts against the trust configuration. An unintended ref reaching exchange with matching issuer, subject and audience exposes the missing boundary.

Finally, confirm that the authorized identity cannot access resources outside its assigned permissions, and repeat the checks after changes to workflows, subject formats or trust configuration. Keep test evidence and correlate cloud audit events with workflow runs without recording tokens; complete workflow attribution is not automatic. After migration verification, revoke replaced static credentials so they cannot bypass federation restrictions. Prepare incident controls for both new issuance and existing credentials: removing trust alone does not guarantee that already-issued access immediately stops.

Evidence: Workload Identity Federation Cheat Sheet¶, Workload identity federation concepts, OpenID Connect