Agent skill

Troubleshooting Authentication

by microsoft-foundry in microsoft-foundry/foundry-agent-webapp

Provides authentication troubleshooting for MSAL, JWT, and Entra ID.

Install Troubleshooting Authentication

skills CLI

$ npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install microsoft-foundry/foundry-agent-webapp troubleshooting-authentication --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/troubleshooting-authentication .claude/skills/troubleshooting-authentication && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "troubleshooting-authentication" agent skill from https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication into .claude/skills/troubleshooting-authentication/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "troubleshooting-authentication", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install microsoft-foundry/foundry-agent-webapp troubleshooting-authentication --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.github/skills/troubleshooting-authentication .agents/skills/troubleshooting-authentication && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "troubleshooting-authentication" agent skill from https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication into .agents/skills/troubleshooting-authentication/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "troubleshooting-authentication", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install microsoft-foundry/foundry-agent-webapp troubleshooting-authentication --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.github/skills/troubleshooting-authentication .cursor/skills/troubleshooting-authentication && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "troubleshooting-authentication" agent skill from https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication into .cursor/skills/troubleshooting-authentication/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "troubleshooting-authentication", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/microsoft-foundry/foundry-agent-webapp.git --path .github/skills/troubleshooting-authentication

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install microsoft-foundry/foundry-agent-webapp troubleshooting-authentication --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.github/skills/troubleshooting-authentication .gemini/skills/troubleshooting-authentication && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "troubleshooting-authentication" agent skill from https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication into .gemini/skills/troubleshooting-authentication/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "troubleshooting-authentication", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install microsoft-foundry/foundry-agent-webapp troubleshooting-authentication

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .github/skills && cp -r skills-src/.github/skills/troubleshooting-authentication .github/skills/troubleshooting-authentication && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "troubleshooting-authentication" agent skill from https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication into .github/skills/troubleshooting-authentication/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "troubleshooting-authentication", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install microsoft-foundry/foundry-agent-webapp troubleshooting-authentication --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft-foundry/foundry-agent-webapp.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.github/skills/troubleshooting-authentication .opencode/skills/troubleshooting-authentication && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "troubleshooting-authentication" agent skill from https://github.com/microsoft-foundry/foundry-agent-webapp/tree/main/.github/skills/troubleshooting-authentication into .opencode/skills/troubleshooting-authentication/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "troubleshooting-authentication", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: troubleshooting-authentication
GitHub stars: 127
Token cost: ~682 tokens
SKILL.md length: 178 words
Files: 1
Skills in repo: 19
Repo updated: Apr 21, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Provides authentication troubleshooting for MSAL, JWT, and Entra ID.

Works in 3 steps: Browser → MSAL.js (PKCE flow) → JWT with… → Frontend → Backend (JWT Bearer token) → Backend → Foundry Agent Service…
Debugging 401 errors
SKILL.md covers Architecture, Common Issues, Backend: JWT Validation and Backend: Credential Strategy, plus 4 more sections
Calls az

What it does

Troubleshooting Authentication is an agent skill from microsoft-foundry/foundry-agent-webapp. 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.

Its SKILL.md is about 680 tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Authentication. It works with Microsoft Entra ID and Microsoft Azure. The repository describes itself as: GitHub Copilot enabled repo for building and deploying a web application with Entra ID authentication and integrated with Azure AI Foundry Agents. The licence is MIT.

When your agent uses it

Debugging 401 errors
MSAL configuration problems
Credential failures in this repository

Example prompts

“Use the troubleshooting-authentication skill to provide authentication troubleshooting for MSAL, JWT, and Entra ID”
“/troubleshooting-authentication”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit f6cb362. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- az
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- jwt.ms
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Troubleshooting Authentication loads about 682 tokens when it runs. Until then it costs about 54 tokens; SKILL.md has 178 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~54
When it runs · the whole SKILL.md, loaded when a task matches: ~682

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

NoteMentions a .env fileSKILL.md:75
```
**Frontend** (`.env.local`):
```
NoteMentions a .env fileSKILL.md:81
```
**Backend** (`.env`):
```

NoteMentions a .env fileSKILL.md:87

Run `azd up` to recreate Entra app and `.env` files.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from microsoft-foundry/foundry-agent-webapp at commit f6cb362, republished under its MIT licence (© microsoft-foundry). 178 words, ~682 tokens.

Download SKILL.mdSave it as .claude/skills/troubleshooting-authentication/SKILL.md (or your agent's skills folder).

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

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:

csharp

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

Backend: Credential Strategy

csharp

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

typescript

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

ini

VITE_ENTRA_SPA_CLIENT_ID=...
VITE_ENTRA_TENANT_ID=...

Backend (.env):

ini

AzureAd__ClientId=...
AzureAd__TenantId=...

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

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

Files

Just SKILL.md in .github/skills/troubleshooting-authentication of microsoft-foundry/foundry-agent-webapp.

Open the folder on GitHubat commit f6cb362

Compare with similar skills

Troubleshooting Authentication next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Troubleshooting Authentication compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Troubleshooting Authentication this skillmicrosoft-foundry/foundry-agent-webapp	127	—	~682	Automated safety check: Notes	MIT	5 mo ago
Microsoft Azure Webjobs Extensions Authentication Events Dotnetmicrosoft/skills	3.1k	5 repos	~3.8k	Automated safety check: Pass	MIT	today
Entra App Registrationmicrosoft/GitHub-Copilot-for-Azure	255	2 repos	~2.1k	Automated safety check: Pass	MIT	today
Iam Auditbriiirussell/cybersecurity-skills	412	—	~3.1k	Automated safety check: Notes	MIT	4 mo ago
Auditing Azure Active Directory Configurationmukul975/Anthropic-Cybersecurity-Skills	34k	—	~3k	Automated safety check: Pass	Apache-2.0	1 mo ago
Azure Identity Pymicrosoft/skills	3.1k	—	~4.4k	Automated safety check: Pass	MIT	today

Similar skills

Microsoft Azure Webjobs Extensions Authentication Events Dotnet
microsoft/skills
Official
Microsoft Entra Authentication Events SDK for .NET. An agent skill from microsoft/skills.
3.1k GitHub starsUsed in 5 repos~3.8k tokens
Backend & APIsAuto-check passed
Entra App Registration
microsoft/GitHub-Copilot-for-Azure
Official
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration.
255 GitHub starsUsed in 2 repos~2.1k tokens
Backend & APIsAuto-check passed
Iam Audit
briiirussell/cybersecurity-skills
Audit, design, and migrate Identity and Access Management — cloud provider IAM (AWS, GCP, Azure), identity providers (Okta, Entra ID / Azure AD, Auth0, Google Workspace), application authorization…
412 GitHub stars~3.1k tokensUpdated 4 mo ago
Backend & APIsAuto-check: notes
Auditing Azure Active Directory Configuration
mukul975/Anthropic-Cybersecurity-Skills
Auditing Microsoft Entra ID (Azure Active Directory) configuration to identify risky authentication policies, overly permissive role assignments, stale accounts, conditional access gaps, and guest…
34k GitHub stars~3k tokensUpdated 1 mo ago
Backend & APIsAuto-check passed
Azure Identity Py
microsoft/skills
Official
Azure Identity SDK for Python authentication with Microsoft Entra ID.
3.1k GitHub stars~4.4k tokensUpdated today
Backend & APIsAuto-check passed
Apex Entra App Registration
jonathan-vella/apex
WORKFLOW SKILL — Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration.
217 GitHub stars~1.3k tokensUpdated today
Backend & APIsAuto-check passed

Questions about Troubleshooting Authentication

What does Troubleshooting Authentication do?

Provides authentication troubleshooting for MSAL, JWT, and Entra ID. Troubleshooting Authentication is an agent skill from microsoft-foundry/foundry-agent-webapp. Provides authentication troubleshooting for MSAL, JWT, and Entra ID.

When should I use Troubleshooting Authentication?

Troubleshooting Authentication fits situations like: debugging 401 errors; MSAL configuration problems; credential failures in this repository.

How do I install Troubleshooting Authentication in Claude Code?

Run `npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a claude-code`. Or copy the skill folder (.github/skills/troubleshooting-authentication in microsoft-foundry/foundry-agent-webapp) into .claude/skills/troubleshooting-authentication in your project. Claude Code loads it when a task matches its description.

How do I install Troubleshooting Authentication in Codex?

Run `npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a codex`. Or copy the skill folder (.github/skills/troubleshooting-authentication in microsoft-foundry/foundry-agent-webapp) into .agents/skills/troubleshooting-authentication in your project. Codex loads it when a task matches its description.

Can I use Troubleshooting Authentication in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add microsoft-foundry/foundry-agent-webapp --skill troubleshooting-authentication -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/troubleshooting-authentication, .gemini/skills/troubleshooting-authentication, .github/skills/troubleshooting-authentication and .opencode/skills/troubleshooting-authentication in your project.

What does Troubleshooting Authentication need to run?

Going by SKILL.md and its folder, Troubleshooting Authentication needs the command-line tools its instructions call (az).

Does Troubleshooting Authentication access the network?

SKILL.md names 1 domain. As links in the text: jwt.ms. This is read from the text; nothing was executed.

Is Troubleshooting Authentication safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Troubleshooting Authentication use?

Troubleshooting Authentication is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Troubleshooting Authentication use?

About 682 tokens (SKILL.md is roughly 2.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Troubleshooting Authentication?

Skills that share tags, products or a category with Troubleshooting Authentication: Microsoft Azure Webjobs Extensions Authentication Events Dotnet (microsoft/skills, 3.1k stars), Entra App Registration (microsoft/GitHub-Copilot-for-Azure, 255 stars), Iam Audit (briiirussell/cybersecurity-skills, 412 stars) and Auditing Azure Active Directory Configuration (mukul975/Anthropic-Cybersecurity-Skills, 34k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Troubleshooting Authentication?

microsoft-foundry (a GitHub organization) maintains it in microsoft-foundry/foundry-agent-webapp, which has 127 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on April 21, 2026.

Source: microsoft-foundry/foundry-agent-webapp on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Troubleshooting Authentication

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Authentication Troubleshooting

Architecture

Common Issues

Backend: JWT Validation

Backend: Credential Strategy

Frontend: MSAL Pattern

Debugging Steps

Environment Variables

Related Skills

Files

Compare with similar skills

Similar skills

More from microsoft-foundry/foundry-agent-webapp

Related

Questions about Troubleshooting Authentication