azure-oidc-federation

Diagnose and fix GitHub Actions to Azure OIDC federated credential subject mismatches.

Updated Apr 16, 2025
One-click install
npx skills add https://github.com/damoke012/eks_code --skill azure-oidc-federation-damoke012
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: azure-oidc-federation
Source: https://github.com/damoke012/eks_code/tree/main/.claude/skills/azure-oidc-federation
Command: npx skills add https://github.com/damoke012/eks_code --skill azure-oidc-federation-damoke012

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? GitHub Actions workflows fail to authenticate to Azure with the cryptic error "AADSTS700213: No matching federated identity record found for presented assertion subject", which looks like a permissions problem but is actually an exact-string mismatch between the OIDC token's subject claim and the federated identity credentials registered on the Azure app registration. ## Core Features & Use Cases - Triage workflow: Three commands (gh api, az ad app list, az ad app federated-credential list) to compare the subject presented in the failing run against the credentials actually registered. - Temporary unblock: Add a single per-branch federated credential so a blocked developer can re-run immediately without merging a PR. - Permanent fix: Create a flexible federated credential using claimsMatchingExpression to match any branch, then declare the app registration and credentials in Terraform with the azuread provider. - Use Case: A developer's manual workflow_dispatch from a feature branch fails azure/login even though pull_request runs succeed; this Skill identifies that the trigger type changes the subject claim and fixes the credential accordingly. ## Quick Start Ask the assistant to diagnose why my GitHub Actions azure/login step is failing with AADSTS700213 and fix the federated credential on the app registration.

Frequently Asked Questions about azure-oidc-federation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix AADSTS700213 no matching federated identity record found?▼

AADSTS700213 means the OIDC token's subject claim does not exactly match any federated identity credential on the app registration. Read the subject printed in the failing run's log, list registered credentials with az ad app federated-credential list, and add a credential matching that exact subject string.

Why does azure/login fail on manual dispatch but work on pull requests?▼

The OIDC subject depends on the trigger type, not just the branch. A pull_request event presents repo:org/repo:pull_request, while workflow_dispatch on a branch presents repo:org/repo:ref:refs/heads/branch, so a credential registered for one trigger will not match the other.

Can I use a wildcard subject for Azure federated credentials?▼

Yes, flexible federated credentials support claimsMatchingExpression, for example matching repo:org/repo:ref:refs/heads/* to cover every branch with one credential. Create it with az rest against the Microsoft Graph API, since the az ad CLI wrapper lags on this feature.

How many federated credentials can an Azure app registration have?▼

Azure caps federated identity credentials at 20 per app registration. Adding one credential per developer per branch hits this ceiling quickly, so a single wildcard or environment-scoped credential is the sustainable approach.

Does the Terraform azuread provider support federated identity credentials?▼

Yes, the azuread_application_federated_identity_credential resource manages federated credentials in Terraform. However, it may not yet expose claimsMatchingExpression, so flexible wildcard credentials may need an ignore_changes lifecycle or environment-scoped subjects instead.