Skip to main content

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

Medium severityMicrosoft Azure About 20 minutes to fix

Overview

Adding environment: to a deploy job rewrites the OIDC subject GitHub sends to Azure, so the branch-based federated credential stops matching. Add the environment credential first.

At a glance

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…
Likely cause
The subject GitHub sends depends on the job, not on the repository, and Entra compares it character for character.
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.
Verification signal
Validation succeeds when the environment job logs in to Azure and nothing else on the app has changed.
Safe correction
Add a credential for the environment subject and leave the branch credential alone.
Rollback or recovery
Rollback is a workflow revert, because the original branch credential was never touched.

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.

3

Apply the safer control

Before you change production

Confirm the affected scope, export the current configuration, and test the replacement control in a non-production environment first.

Fix commands and configuration

sub
repo:ORG/REPO:ref:refs/heads/BRANCH
environment: production
4

When to escalate

Validation and rollback are covered in the sections above.

Escalate

Escalate when the blast radius is uncertain, the control cannot be tested safely, or remediation requires an outage or security exception.

The KBY Brief

Fixed? Get the next one before it hits you: The KBY Brief

Practical fixes for the systems you run, by email about twice a week. Unsubscribe at any time.

About this page

Credited to

Dates

Published

Corrections

No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.

Was this useful?

Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.

After remediation

Further reading stays below the corrective workflow and is selected by platform, category and shared technical keywords.

Discover more

Connected KBY resources