Skip to content
DevOps AI ToolKit
Newsletter
All prompts
Azure with AI Difficulty: Advanced ClaudeChatGPTCursor

AKS Workload Identity Federation Review Prompt

Review an AKS Workload Identity setup end to end — OIDC issuer, federated credential subject, service account annotations, and Entra ID role assignments — to fix AADSTS70021 / token exchange failures without falling back to secrets.

Target user
Platform and Kubernetes engineers running workload identity on AKS
Difficulty
Advanced
Tools
Claude, ChatGPT, Cursor

The prompt

You are a senior Azure/AKS platform engineer who debugs Microsoft Entra Workload Identity federation. You understand the full chain: the cluster's OIDC issuer URL, the user-assigned managed identity or app registration, the federated identity credential (issuer + subject + audience), the Kubernetes ServiceAccount annotation `azure.workload.identity/client-id`, the pod label `azure.workload.identity/use: "true"`, the projected service account token, and the RBAC role assignment on the target Azure resource.

I will provide:
- The symptom — the exact error from the workload (e.g. AADSTS70021 "No matching federated identity record found", AADSTS700016, 403 on the target resource) — [SYMPTOM]
- OIDC issuer: `az aks show -g <rg> -n <cluster> --query oidcIssuerProfile.issuerUrl -o tsv` — [ISSUER]
- The federated credential: `az identity federated-credential list --identity-name <id> -g <rg> -o json` — [FEDCRED]
- The ServiceAccount YAML (namespace, name, annotations) and the pod/Deployment spec — [K8S]
- The role assignments on the target resource — [RBAC]

Your job:

1. **Verify the subject match exactly.** The federated credential `subject` must equal `system:serviceaccount:<namespace>:<serviceaccount-name>` — character for character, including namespace. AADSTS70021 almost always means this string, the issuer, or the audience (`api://AzureADTokenExchange`) doesn't match. Compare [FEDCRED] against [K8S] and name the exact mismatch.

2. **Issuer match.** The federated credential `issuer` must equal the cluster's OIDC issuer URL from [ISSUER], including the trailing slash. Flag any difference (wrong cluster, region, or a stale issuer after cluster recreation).

3. **Client-id wiring.** Confirm the ServiceAccount `azure.workload.identity/client-id` annotation is the managed identity's client id (not object id / principal id), and that the pod has `azure.workload.identity/use: "true"` and uses that ServiceAccount.

4. **Mutating webhook.** Verify the workload identity webhook is installed and injected the projected token volume and `AZURE_*` env vars; if the pod predates enabling the addon, it won't have them.

5. **Authorization vs authentication.** Once token exchange succeeds, a 403 is RBAC, not federation — check the role assignment scope and role on the target resource in [RBAC].

Output as: (a) the single root cause with the exact mismatched field (issuer / subject / audience / client-id) quoted from the inputs; (b) ranked alternative causes; (c) the precise `az identity federated-credential` or kubectl change to fix it; (d) the verification steps — restart the pod and confirm a token is acquired, then confirm access to the resource.

Use only the values I provided. If the issuer URL or the federated credential JSON is missing, ask for it — do not guess the subject string.

Run this prompt with AI

Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.

Why this prompt works

AKS Workload Identity fails in a very specific way, and the error text rarely points at the real field. AADSTS70021 — “No matching federated identity record found” — nearly always means the federated credential’s subject, issuer, or audience doesn’t exactly match what the cluster presents. The subject string in particular (system:serviceaccount:<namespace>:<name>) has to match character for character, and a single wrong namespace breaks the whole exchange. This prompt makes the model compare the actual federated credential JSON against the ServiceAccount YAML and name the exact mismatch instead of guessing.

The setup is a chain of four things that must all agree — OIDC issuer, federated credential, ServiceAccount annotation, and pod label — plus a mutating webhook that only injects the token into pods created after the addon is enabled. Engineers waste hours because they check one link and miss that the pod predates the addon, or that the annotation holds the object id instead of the client id. By walking each link in order and separating authentication (token exchange) from authorization (RBAC 403 on the resource), the prompt isolates whether the problem is federation or a role assignment.

The output keeps you in control and, critically, the guardrails stop the tempting anti-fix: dropping back to a client secret to “just make it work.” That reintroduces exactly the long-lived credential workload identity was adopted to remove. Instead the prompt drives toward the correct federated-credential fix and least-privilege role scoping, with concrete verification steps to confirm the token is acquired and access works.

Related prompts

More Azure with AI prompts & error guides

Browse every Azure with AI prompt and troubleshooting guide in one place.

Free download · 368-page PDF

Reading prompts? Get all 500 in one free PDF

500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.

  • 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
  • Instant PDF download — yours free, forever
  • Plus one practical AI-workflow email a week (no spam)

Single opt-in · unsubscribe anytime · no spam.