GitHub Actions to Azure: Fix Federated Credential Mismatches
Technical review: 26 October 2026. Product names, licensing references and procedures reflect this review; check the linked documentation for your release.
An Azure deployment can pass its build tests and still fail before it receives an Azure token. With OpenID Connect federation, the most useful question is often whether the workflow’s actual identity matches the trust configured in Entra. Updating a runner image does not repair a mismatched subject claim.
Identify which stage failed
Separate runner availability, build/test execution, OIDC token issuance, Azure token exchange and resource authorization. If the workflow cannot start because its runner labels are unavailable, solve that scheduling problem first. If Azure sign-in succeeds but deployment returns an authorization error, inspect Azure RBAC rather than repeatedly editing federation.
Preserve the error, workflow run URL, job/environment name and relevant non-secret identifiers. Do not paste the complete OIDC token or access token into an issue. The claims needed for diagnosis can be compared without publishing reusable credentials.
Compare the three trust fields
For an exact-match federated credential, the issuer, subject and audience must match the incoming token with the required case sensitivity. Confirm the configured identity’s client ID and tenant, and check whether the federated credential is on an app registration or user-assigned managed identity.
The workflow context matters. A repository branch and a protected GitHub environment usually produce different subject shapes. An illustrative comparison is:
repo:example-org/example-repo:ref:refs/heads/main
repo:example-org/example-repo:environment:productionThese are alternatives, not values to install together blindly. Subject customization and enterprise issuer configurations can also change the expected claim. Compare the actual supported issuer and claim configuration for your GitHub platform instead of copying a public-cloud example into a different enterprise environment.
Find the correct Entra object
An Enterprise Application is a service principal, not the app registration itself. Use its application client ID to identify the associated application object in the owning tenant where appropriate. Do not substitute the service principal’s object ID for the app registration’s object ID when following a portal or API instruction.
Also check that the workflow can request an OIDC token, typically through an appropriate id-token: write permission. The Azure login step must target the intended identity and subscription. These are separate checks from the permissions that identity receives once authentication succeeds.
Repair narrowly and retest
Have the workflow owner confirm the intended repository, branch or environment before changing trust. Save the previous credential configuration and adjust only the fields that should legitimately change. Broad wildcard trust is not a substitute for agreeing on the deployment boundary.
Rerun the intended workflow and verify token exchange, resource deployment and a negative case from an unapproved context. Record the final trust relationship and runner requirements in the handoff. For the next authorization layer, see scoped managed-identity access. A useful fix explains which claim differed; it does not merely report that a rerun happened to pass.
References
- Microsoft: workload identity federation and claim matching
- Microsoft: create a federated trust relationship
- GitHub: configure OIDC in Azure