How do I install the Troubleshooting Authentication skill?

Run npx skillmds@latest add microsoft-foundry/troubleshooting-authentication in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Troubleshooting Authentication safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Troubleshooting Authentication?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Troubleshooting Authentication free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Troubleshooting Authentication?

microsoft-foundry (@microsoft-foundry) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Troubleshooting Authentication by microsoft-foundry

Name: Troubleshooting Authentication
Rating: 4.5 (4 reviews)
Author: microsoft-foundry

Troubleshooting Authentication

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.

File contents

Authentication Troubleshooting

Architecture

Browser → MSAL.js (PKCE flow) → JWT with Chat.ReadWrite scope
Frontend → Backend (JWT Bearer token)
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

Check token contents: https://jwt.ms
Verify scope: Token should have Chat.ReadWrite
Check audience: Should match client ID or api://{clientId}
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

---name: troubleshooting-authenticationdescription: 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## Architecture1. Browser → MSAL.js (PKCE flow) → JWT with `Chat.ReadWrite` scope2. 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 ValidationAccepts both audience formats:```csharpoptions.TokenValidationParameters.ValidAudiences = new[]{ builder.Configuration["AzureAd:ClientId"], $"api://{builder.Configuration["AzureAd:ClientId"]}"};```## Backend: Credential Strategy```csharpTokenCredential 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```typescript// Always try silent firsttry { const { accessToken } = await instance.acquireTokenSilent({ ...tokenRequest, account: accounts[0] }); return accessToken;} catch { // Fallback to popup const { accessToken } = await instance.acquireTokenPopup(tokenRequest); return accessToken;}```## Debugging Steps1. **Check token contents**: https://jwt.ms2. **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`):```iniVITE_ENTRA_SPA_CLIENT_ID=...VITE_ENTRA_TENANT_ID=...```**Backend** (`.env`):```iniAzureAd__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

Frequently asked questions