Dev.to Security 🔐 Cybersecurity 👁 0 📖 7 min read

Adding an Environment to a GitHub Actions Job Changes the OIDC Subject and Breaks Azure Federated Login

Originally published on KBY Technologies. When a GitHub Actions job references an environment, GitHub changes the subject (sub) claim in the job’s OIDC token. A job without an environment, triggered by a push, sends rep

Originally published on KBY Technologies.

When a GitHub Actions job references an environment, GitHub changes the subject (sub) claim in the job’s OIDC token. A job without an environment, triggered by a push, sends repo:ORG/REPO:ref:refs/heads/BRANCH. Add environment: production to the same job and it sends repo:ORG/REPO:environment:production instead, on every branch. Microsoft Entra ID only exchanges the token when its issuer and subject exactly match a federated identity credential on the app registration or user-assigned managed identity, so a credential written for the branch stops matching and the azure/login step fails. The fix is to add a second credential with the exact environment subject, let it propagate, and only then merge the workflow change. A standard federated credential takes no wildcards or branch patterns, so it cannot cover both subjects at once.

Symptom

A deployment that has authenticated to Azure for months starts failing at the Azure Login step on the first run after someone adds an environment to the deploy job, usually to gain required reviewers or environment secrets. Nothing changed in Azure: the app registration, its role assignments and the client, tenant and subscription IDs stored in GitHub are all the same. The token exchange is refused because no federated identity credential matches the presented token. Microsoft documents the message AADSTS70021: No matching federated identity record found for presented assertion for a request that no credential matches yet, so look for it in the Azure Login output. Jobs in the same workflow that do not reference the environment keep working, which makes the failure look intermittent or job-specific.

False Assumption

The natural assumption is that the federated credential trusts “the main branch of this repository”, so any job running from main is covered. It does not. The credential stores one literal subject string, and GitHub builds that string from the job’s context. GitHub documents that the branch name appears in the subject only if the job does not reference an environment and the workflow is not triggered by a pull request. Once an environment is referenced, the branch is no longer in the subject at all.

Root Cause

The subject GitHub sends depends on the job, not on the repository, and Entra compares it character for character. GitHub assembles the default subject in this order of precedence:

  • Job references an environment: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME.
  • No environment, pull request event: repo:ORG-NAME/REPO-NAME:pull_request.
  • No environment, branch or tag: repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME or :ref:refs/tags/TAG-NAME.

On the Entra side, the issuer and subject of the credential must match the iss and sub claims of the incoming token, the issuer and subject pair must be unique on the app, and wildcard characters are not supported in any property of a standard credential. Microsoft also notes that a credential with the wrong subject is created successfully, with no error, so the mismatch only surfaces when a workflow tries to exchange a token.

Impact

Every run of the changed job loses access to Azure until a matching credential exists, which in practice means a blocked production deployment rather than a security exposure. The pressure that follows is the larger risk: the quickest-looking workarounds are removing the environment again, which also removes its approval gate, or creating client secrets on the app, which brings back the long-lived credential federation was meant to remove. Getting the environment credential right is also the safer end state, because a branch-scoped subject lets every workflow on that branch exchange a token, whereas an environment subject can sit behind required reviewers.

Diagnosis

Compare the subject GitHub sends with the subjects Entra holds. Both checks are read-only.

  1. List the credentials on the app registration and save the output as your backup. The --id parameter takes the app’s object ID, application (client) ID or identifier URI: az ad app federated-credential list --id <app-id> > fic-backup.json. The deploy credential will show a subject such as repo:contoso/web-app:ref:refs/heads/main.
  2. Read the subject the job actually sends. GitHub’s github/actions-oidc-debugger action prints the claims in the job’s token; run it in a job with the same environment: value and id-token: write permission. Expect sub to read repo:contoso/web-app:environment:production.
  3. Check the repository’s subject format. Repositories created after 15 July 2026, and older ones that opted in or were renamed or transferred after that date, use GitHub’s immutable format, repo:OWNER@OWNER-ID/REPO@REPO-ID:.... Also check whether the organisation or repository has a customised subject template, which replaces the default format entirely.
  4. Rule out the other parts of the match. The issuer should be https://token.actions.githubusercontent.com and the audience api://AzureADTokenExchange, which is the azure/login default for public clouds; an audience mismatch blocks the exchange in the same quiet way.

If the debugger shows an environment subject and the list shows only a ref subject, you have found the trap.

Correction

Add a credential for the environment subject and leave the branch credential alone. Creating, updating or deleting a federated identity credential needs ownership of the app or the Application Administrator, Cloud Application Administrator, Global Administrator or Hybrid Identity Administrator role.

  1. Precondition: confirm the app holds fewer than 20 federated identity credentials, the documented maximum per application or user-assigned managed identity, and that fic-backup.json from the diagnosis step exists.

  2. Write credential.json with a URL-friendly name, the GitHub issuer, the exact subject from the debugger output and the default audience:

    {
      "name": "github-web-app-production",
      "issuer": "https://token.actions.githubusercontent.com",
      "subject": "repo:contoso/web-app:environment:production",
      "audiences": ["api://AzureADTokenExchange"]
    }
    
  3. Create it: az ad app federated-credential create --id <app-id> --parameters credential.json.

  4. Wait several minutes before testing. Microsoft documents that a new credential takes time to propagate and that requests made too early can fail with AADSTS70021.

  5. Merge the workflow change that adds environment: production to the job.

In the Entra admin center the same credential is added under the app’s Certificates & secrets, Federated credentials tab, choosing the GitHub actions deploying Azure resources scenario and an Entity type of Environment. The portal fills in the subject; compare it with the debugger output before saving, particularly for repositories on the immutable ID format.

Validation

Validation succeeds when the environment job logs in to Azure and nothing else on the app has changed.

  • az ad app federated-credential show --id <app-id> --federated-credential-id github-web-app-production returns the subject exactly as the debugger printed it, including case.
  • The next run of the job passes the Azure Login step, and an az account show step prints the expected subscription.
  • A fresh az ad app federated-credential list differs from fic-backup.json only by the new credential.

Rollback

Rollback is a workflow revert, because the original branch credential was never touched. Revert the commit that added environment: to the job; it then sends the ref subject again and the existing credential matches. If the new credential is wrong or unwanted, remove only that one with az ad app federated-credential delete --id <app-id> --federated-credential-id github-web-app-production and compare a fresh list with fic-backup.json. Do not delete the branch credential as part of this change; once every job that needs it has moved to environments, removing it is a separate, reviewed decision.

Prevention: Create the Azure Credential Before the Environment Reaches the Workflow

Treat any change to a job’s trigger or environment: key as a change to its Azure identity, and review it alongside the federated credentials:

  • Add the matching credential first, wait for propagation, then merge the workflow change; GitHub gives the same advice for subject customisation templates.
  • Prefer one environment credential per deployment target over one credential per branch. Microsoft recommends specifying an environment when an on-push workflow runs against many branches or tags, and it keeps you well inside the 20-credential limit.
  • Watch for names that change the subject: environment names with a colon are encoded as %3A, and a repository rename or transfer can move it to the immutable ID format.
  • Do not reach for a pattern to close the gap. Standard credentials match exactly; flexible federated identity credentials, still in preview, accept a matches expression on sub but must also pin repository_id or repository_owner_id, and wildcard federated credentials widen the blast radius of the identity they protect.

Before closing the change, confirm the deploy job’s subject, the credential list and the role assignments on the app all describe the same environment, so the next safe decision, retiring the branch credential, can be made from evidence rather than guesswork.

This is one of KBY Technologies' Config Traps: settings that look right and quietly break something. Read the original, with its fix commands, on kbytechnologies.com.

📰 Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.