Azure Workload Identity Federation: diagnose CI authentication before bringing back a secret

An Azure authentication failure in a CI pipeline usually appears at the worst moment: a release must go out, the job cannot obtain a token, and someone suggests putting back a temporary client secret to unblock deployment. That reaction is understandable, but risky. When OIDC authentication fails, the cause can be the subject, audience, issuer, a renamed branch, a GitHub environment, the wrong identity target or a missing Azure role.

The use case is a deployment pipeline that uses workload identity federation instead of an application secret. After a repository, branch, environment or service principal change, the job fails during authentication. The runbook goal is to decide whether to fix the federated credential, restore a mapping, adjust a role, roll back the CI change or reject a long-lived secret fallback.

Identify the identity actually used

Before fixing Azure, capture the identity the job thinks it is using. Many incidents come from confusion between service principal, app registration, managed identity, CI environment and target subscription.

Flow to qualify
CI platform and repository
Workflow, job and environment
Branch, tag or pull request source
Target Azure tenant
Target subscription or management group
Expected app registration, service principal or managed identity
Expected federated credential
Expected Azure role and exact scope

Diagnosis questions
Does the job fail before obtaining a token?
Is the token obtained but rejected by Azure RBAC?
Does the wrong CI environment produce a different subject?
Did the recent change touch branch, environment, repository, tenant or role?

This step prevents the team from treating every error as a permission problem. An AADSTS700213 error often points to an unrecognized subject or issuer. An AuthorizationFailed error happens after authentication, when Azure authorization is evaluated.

Capture expected OIDC claims

The federated credential compares claims. If the repository was renamed, the primary branch became main, a production environment was added, or the workflow runs from a pull request, the subject may no longer match.

expected_oidc_claims:
issuer: https://token.actions.githubusercontent.com
audience: api://AzureADTokenExchange
subject: repo:company/platform:environment:production
repository: company/platform
ref: refs/heads/main
environment: production

azure_target:
tenant_id: 00000000-0000-0000-0000-000000000000
client_id: 11111111-1111-1111-1111-111111111111
subscription_id: 22222222-2222-2222-2222-222222222222
role_scope: /subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-prod

The right reflex is not to immediately widen the subject to the whole repository. The right reflex is to prove which claim changed and whether that change was intended.

Read the federated credential as a contract

A federated credential that is too broad turns OIDC into implicit access for more jobs than expected. A credential that is too narrow breaks legitimate releases. Read the configuration as a production contract, not as a plumbing line.

APP_ID="11111111-1111-1111-1111-111111111111"

az ad app federated-credential list --id "$APP_ID" --query "[].{name:name,issuer:issuer,subject:subject,audiences:audiences}" --output table

az ad sp show --id "$APP_ID" --query "{appId:appId,displayName:displayName,id:id,servicePrincipalType:servicePrincipalType}" --output table

Look for precise mismatches: missing audience, different issuer, subject still pointing to an old branch, credential attached to the wrong app registration, or identity deleted and recreated.

Separate authentication from authorization

When the token is obtained but deployment still fails, the problem moves to Azure RBAC, Azure Policy, locks or deployment scope. Do not fix the federated credential if the error says the identity exists but cannot perform the action.

CLIENT_ID="11111111-1111-1111-1111-111111111111"
SCOPE="/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-prod"

SP_OBJECT_ID=$(az ad sp show --id "$CLIENT_ID" --query id -o tsv)

az role assignment list --assignee "$SP_OBJECT_ID" --scope "$SCOPE" --include-inherited --output table

az lock list --scope "$SCOPE" --output table
az policy state list --resource-group rg-prod --query "[0:20].{policy:policyDefinitionName,compliance:complianceState}" --output table

The decision changes at this point. Fixing a role assignment can be legitimate when the scope is known and justified. Adding Contributor to the whole subscription to bypass a deployment failure is not.

Correlate errors in logs

Logs should show where the chain breaks: CI provider, Entra ID, Azure Resource Manager or target service. Keep the run ID, timestamp, client ID, tenant and exact error.

let Window = 6h;
let ClientId = "11111111-1111-1111-1111-111111111111";
SigninLogs
| where TimeGenerated > ago(Window)
| where AppId == ClientId or ServicePrincipalId == ClientId
| project TimeGenerated,
        AppDisplayName,
        ServicePrincipalId,
        ResultType,
        ResultDescription,
        ConditionalAccessStatus,
        IPAddress,
        ResourceDisplayName,
        CorrelationId
| order by TimeGenerated desc

If sign-in logs show nothing, the job may never have obtained an Azure token. Go back to CI logs and OIDC claims. If Entra accepts the token but ARM rejects the action, go back to RBAC and scope.

Decide correction, rollback or secret refusal

The expected output is a bounded decision. Bringing back a secret should remain short, documented and revocable, never a silent correction.

Fix the federated credential
The observed subject matches an intended CI change
Issuer and audience are correct
The credential remains limited to the expected branch, environment or workflow
Rollback: restore the previous subject or disable the new credential

Fix RBAC
The token is obtained
Azure denies an action at the expected scope
The missing role is minimal and justified
Rollback: remove the added role assignment

Roll back the CI change
Workflow or environment changed without identity validation
Several critical pipelines fail since the same commit
The previous mapping is known and testable

Reject the long-lived secret fallback
The OIDC cause is not qualified
The secret would grant broader or less traceable access
No expiration or deletion is planned
Action: block the release or use an approved short-lived temporary secret

This matrix protects two things at once: the ability to deploy and the quality of the identity model. A quick fix that widens the subject or the role can become durable security debt.

Validate without losing evidence

After correction, replay the same pipeline with the same environment and keep the evidence. Validation must show that federated identity works, that the role is minimal and that rollback remains possible.

Minimum validation
The job obtains a token without an application secret
OIDC claims match the expected federated credential
The service principal or target identity is the documented one
Deployment succeeds only at the expected scope
Entra and CI logs contain run ID, client ID and correlation ID
No broad temporary role remains active
Any old credential or test role is removed if unnecessary

Clean rollback
Restore the previous CI workflow
Restore the previous federated credential
Remove new role assignments
Delete any temporary secret created during the incident
Add the incident case to the release runbook

If the release passes only because a secret was added, the incident is not resolved. It has moved to a less observable access surface.

Conclusion

Workload identity federation sharply reduces dependency on secrets, but it creates a strict contract between the pipeline, OIDC claims, Entra ID and Azure RBAC. When that contract breaks, diagnosis must separate authentication, authorization and CI change.

A healthy outcome is verifiable: fix the subject when the CI path changed, adjust the role when the identity authenticates but lacks scope, roll back the workflow when the change was not controlled, or reject a durable return to secrets. That keeps the deployment chain operable without losing control of identities.