Authentication Troubleshooting

Architecture

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

Common Issues

Issue	Cause	Fix
401 on /api/*	Token missing scope	Verify Chat.ReadWrite scope in token
ManagedIdentityCredential error locally	Wrong environment	Set ASPNETCORE_ENVIRONMENT=Development
Token popup blocked	Browser settings	Allow popups for localhost
Silent token fails	No cached token	Fallback to popup (handled by useAuth)

Backend: JWT Validation

Accepts both audience formats:

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

Backend: Credential Strategy

TokenCredential 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

// 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):

VITE_ENTRA_SPA_CLIENT_ID=...
VITE_ENTRA_TENANT_ID=...

Backend (.env):

AzureAd__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