Microsoft Entra ID skill for Codex

Done well means: each app uses the OAuth flow that matches its type, APIs validate issuer, audience, tenant and scope or role on every request, workloads in Azure use managed identities and CI uses federated credentials so no client secret exists to leak, and every permission requested is the least one that works.

Vocabulary that causes most bugs

Term	Meaning
App registration (application object)	The global definition: client ID, redirect URIs, exposed scopes, roles
Enterprise application (service principal)	The per-tenant instance; holds consent, role assignments, sign-in logs
Client ID / Application ID	GUID of the app registration; the aud of v2 access tokens for your API
Tenant ID	Directory GUID; appears as tid in tokens
Delegated permission (scope)	App acts for a signed-in user; appears in scp
Application permission (app role)	App acts as itself; appears in roles; always needs admin consent

Inspect first

1. Read AGENTS.md and the auth configuration in code (msal config, appsettings.json AzureAd section, env vars). Never print client secrets or certificates.
2. Inspect the registration (needs network and az login with directory read access):

az ad app show --id "$CLIENT_ID" \
  --query "{name:displayName, audience:signInAudience, spa:spa.redirectUris, web:web.redirectUris, tokenVersion:api.requestedAccessTokenVersion, scopes:api.oauth2PermissionScopes[].value, roles:appRoles[].value}"
az ad app credential list --id "$CLIENT_ID" --query "[].{name:displayName, end:endDateTime}"
az ad app federated-credential list --id "$CLIENT_ID"
az ad sp show --id "$CLIENT_ID" --query "{appRoleAssignmentRequired:appRoleAssignmentRequired}"

Pick the flow

App type	Flow	Library	Credential
SPA (React, Angular, Vue)	Authorization code + PKCE	@azure/msal-browser / msal-react	None (public client)
Server-rendered web app	Authorization code	Microsoft.Identity.Web, msal-node, msal (Python)	Certificate or federated credential
Web API called by your apps	Validate bearer tokens	Microsoft.Identity.Web, jose/JWKS, msal not needed	None
API calling another API for the user	On-behalf-of	MSAL confidential client	Certificate
Daemon, job, service-to-service	Client credentials with .default	MSAL or Azure Identity	Managed identity, then federated credential, then certificate
CLI or device without a browser	Device code	MSAL public client	None
Workload running in Azure calling Azure services	Managed identity	Azure Identity DefaultAzureCredential	None

Never use the implicit flow or resource owner password credentials for new work.

Register an API and a client

# API
az ad app create --display-name "orders-api" --sign-in-audience AzureADMyOrg
API_ID=$(az ad app list --display-name orders-api --query "[0].appId" -o tsv)
az ad app update --id "$API_ID" --identifier-uris "api://$API_ID"
az ad sp create --id "$API_ID"

Set in the API manifest (portal Manifest blade or az rest against Microsoft Graph):

• api.requestedAccessTokenVersion: 2 so tokens use the v2 issuer and aud = client ID.
• A delegated scope such as Orders.Read and app roles such as Orders.Process with allowedMemberTypes: ["Application"] for daemons.
• On the enterprise app, appRoleAssignmentRequired: true if only assigned users/apps may get tokens.

Client SPA request: scope api://<API_ID>/Orders.Read. Daemon request: api://<API_ID>/.default, which returns whatever app roles were admin-consented.

Granting admin consent (az ad app permission admin-consent --id <client>) affects the whole tenant. Ask the user before running it.

SPA sign-in (msal-browser)

import { PublicClientApplication, InteractionRequiredAuthError } from "@azure/msal-browser";

export const msal = new PublicClientApplication({
  auth: {
    clientId: import.meta.env.VITE_ENTRA_CLIENT_ID,
    authority: `https://login.microsoftonline.com/${import.meta.env.VITE_ENTRA_TENANT_ID}`,
    redirectUri: "/auth/callback",
  },
  cache: { cacheLocation: "sessionStorage" },
});
await msal.initialize();
await msal.handleRedirectPromise();

export async function apiToken(): Promise<string> {
  const account = msal.getAllAccounts()[0];
  const request = { scopes: ["api://<API_ID>/Orders.Read"], account };
  try {
    return (await msal.acquireTokenSilent(request)).accessToken;
  } catch (e) {
    if (e instanceof InteractionRequiredAuthError) await msal.acquireTokenRedirect(request);
    throw e;
  }
}

Register SPA redirect URIs under the spa platform, not web; the wrong platform causes AADSTS9002326 (cross-origin token redemption) errors.

Protecting an API

Validate every request. Required checks: signature against tenant JWKS, iss, aud, exp/nbf, tid (multi-tenant allow-list), and scp or roles for the operation. For implementation details, library choices per language and the multi-tenant issuer rules, read references/token-validation.md when writing or reviewing API auth code.

Hard rules:

• An ID token proves sign-in to the client; it is never accepted by an API.
• Tokens for Microsoft Graph (aud = 00000003-0000-0000-c000-000000000000) are not for your API and cannot be validated by you; reject them.
• Authorise on oid (+ tid) as the stable user key, not email, upn or preferred_username, which are mutable and sometimes user-controlled.

Managed identity and Azure SDKs

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

cred = DefaultAzureCredential()   # managed identity in Azure, az login / VS Code locally
blobs = BlobServiceClient("https://shopst.blob.core.windows.net", credential=cred)

• Use a user-assigned identity when several resources share access or the identity must survive resource recreation; set AZURE_CLIENT_ID so the SDK picks the right one.
• Managed identities need data-plane roles (Storage Blob Data Reader, Key Vault Secrets User).
• In production, consider ManagedIdentityCredential directly; DefaultAzureCredential probes several sources and can pick up an unexpected developer credential.

GitHub Actions without secrets

az ad app federated-credential create --id "$DEPLOY_APP_ID" --parameters '{
  "name": "gh-main",
  "issuer": "https://token.actions.githubusercontent.com",
  "subject": "repo:my-org/shop:environment:production",
  "audiences": ["api://AzureADTokenExchange"]
}'

The subject must match exactly (repo:ORG/REPO:ref:refs/heads/main, ...:environment:NAME, or ...:pull_request). Wildcards are not supported in standard federated credentials. Then use azure/login@v2 with client-id, tenant-id, subscription-id and permissions: id-token: write.

Secret hygiene

• Prefer certificates over client secrets, and federated credentials or managed identities over both.
• az ad app credential reset replaces existing credentials unless --append is set; running it on a production app breaks every deployed instance. Confirm first.
• Track expiry dates; expired secrets are a top cause of sudden AADSTS7000222 outages.

Common AADSTS errors

Code	Meaning	Fix
AADSTS50011	Redirect URI mismatch	Register the exact URI, including path and trailing slash
AADSTS65001	Consent missing	User or admin consent for the scope
AADSTS700016	App not found in tenant	Wrong tenant/authority, or single-tenant app used cross-tenant
AADSTS7000215	Invalid client secret	Using secret ID instead of value, or expired
AADSTS70011	Invalid scope	Daemon must use /.default; scope string typo
AADSTS50105	User not assigned	Assignment required on the enterprise app

Verification

• Decode a test access token (locally, never on third-party sites for production tokens) and confirm aud, iss (v2 form), tid, and scp/roles.
• Call the API with: a valid token (200), no token (401), a token for another audience (401), a token missing the scope/role (403).
• az ad app credential list shows no secrets for apps moved to federated credentials.

Report template

**Apps:** orders-api (single tenant, v2 tokens, scope Orders.Read, role Orders.Process), orders-spa (spa platform)
**Flows:** SPA auth code + PKCE; nightly job client credentials via managed identity
**API checks:** iss, aud, tid, exp, scp/roles enforced; 4 negative tests pass
**Secrets:** 0 client secrets; CI uses federated credential repo:my-org/shop:environment:production
**Consent:** admin consent for Orders.Process granted by user on 2026-11-04