---

name: troubleshooting-authentication description: Provides authentication troubleshooting for MSAL, JWT, and Entra ID. Use when debugging 401 errors, token issues, MSAL configuration problems, or credential failures in this repository.

Authentication Troubleshooting

Architecture

1. Browser → MSAL.js (PKCE flow) → JWT with Chat.ReadWrite scope
2. Frontend → Backend (JWT Bearer token)
3. Backend → Azure AI Foundry (ManagedIdentityCredential)

Common Issues

Backend: JWT Validation

Accepts both audience formats:

Copyoptions.TokenValidationParameters.ValidAudiences = new[]
{
    builder.Configuration["AzureAd:ClientId"],
    $"api://{builder.Configuration["AzureAd:ClientId"]}"
};

Backend: Credential Strategy

CopyTokenCredential credential = env.IsDevelopment()
    ? new ChainedTokenCredential(
        new AzureCliCredential(),
        new AzureDeveloperCliCredential())  // Supports 'azd auth login'
    : new ManagedIdentityCredential();

Local development: Requires az login or azd auth login to work.

Why ChainedTokenCredential: Avoids DefaultAzureCredential's unpredictable "fail fast" mode. Provides explicit, debuggable credential chain.

Frontend: MSAL Pattern

Copy// Always try silent first
try {
  const { accessToken } = await instance.acquireTokenSilent({
    ...tokenRequest,
    account: accounts[0]
  });
  return accessToken;
} catch {
  // Fallback to popup
  const { accessToken } = await instance.acquireTokenPopup(tokenRequest);
  return accessToken;
}

Debugging Steps

1. Check token contents: https://jwt.ms
2. Verify scope: Token should have Chat.ReadWrite
3. Check audience: Should match client ID or api://{clientId}
4. Verify Entra app: Check redirect URIs in Azure Portal

Environment Variables

Frontend (.env.local):

CopyVITE_ENTRA_SPA_CLIENT_ID=...
VITE_ENTRA_TENANT_ID=...

Backend (.env):

CopyAzureAd__ClientId=...
AzureAd__TenantId=...

Regenerate: Run azd up to recreate Entra app and .env files.

Related Skills

• writing-csharp-code - Backend JWT validation and credential patterns
• writing-typescript-code - Frontend MSAL integration and useAuth hook
• deploying-to-azure - Entra app provisioning and RBAC configuration