docs: Add troubleshooting for Service Principal 403 in VS Code context

[bsgustavo]

Summary

Adds a new troubleshooting section to TROUBLESHOOTING.md documenting a scenario where Service Principal authentication via Azure CLI returns 403 Forbidden on OneLake DFS operations when running inside VS Code.

Problem

When using a Service Principal authenticated via az login --service-principal inside VS Code, OneLake DFS operations (directory_create, upload_file, etc.) fail with 403 Forbidden, even though the Service Principal has the correct permissions (e.g., Workspace Admin in Microsoft Fabric).

The same Service Principal works correctly when called from Python scripts or other tools outside VS Code.

Root Cause

The CustomChainedCredential in the Azure MCP Server detects the VSCODE_PID environment variable (automatically set by VS Code for all child processes) and reorders the credential chain to prioritize VisualStudioCodeCredential over AzureCliCredential. This causes the MCP Server to authenticate using the VS Code user's account instead of the Service Principal, resulting in 403 errors when that account lacks the required data plane permissions.

Credential chain when VSCODE_PID is detected:

VisualStudioCodeCredential → EnvironmentCredential → VisualStudioCredential → AzureCliCredential → ...

Solution

Set AZURE_TOKEN_CREDENTIALS=AzureCliCredential as an environment variable and fully restart VS Code (not just reload the window).

Changes

• Added TOC entry for the new section
• Added new section "Service Principal Returns 403 for OneLake Operations in VS Code" under Authentication, documenting:
  • Symptoms (blob works but DFS fails)
  • Root cause (VSCODE_PID credential reordering)
  • Resolution (AZURE_TOKEN_CREDENTIALS=AzureCliCredential + full VS Code restart)
  • Important note about Window Reload vs full restart

[github-actions]

Thank you for your contribution @bsgustavo! We will review the pull request and get back to you soon.

[Copilot]

Pull request overview

This PR adds troubleshooting documentation for a specific authentication issue that occurs when using Service Principal authentication via Azure CLI inside VS Code. The issue arises because VS Code sets the VSCODE_PID environment variable, which causes the Azure MCP Server's credential chain to prioritize VisualStudioCodeCredential over AzureCliCredential, resulting in 403 Forbidden errors for OneLake DFS operations.

Changes:

• Added a new troubleshooting section documenting the Service Principal 403 issue in VS Code context
• Updated the Table of Contents with a link to the new section
• Provided detailed symptoms, root cause explanation, and resolution steps with platform-specific examples

[bsgustavo]

@bsgustavoPor favor, leia o seguinte Contrato de Licença de Colaborador (CLA). Se concordar com o CLA, responda com as seguintes informações.

@microsoft-github-policy-service agree [company="{your company}"]

Opções:

• (padrão - nenhuma empresa especificada) Detenho a propriedade exclusiva dos direitos de propriedade intelectual das minhas Submissões e não estou fazendo Submissões no âmbito do meu trabalho para o meu empregador.

@microsoft-github-policy-service agree

• (Quando fornecido pela empresa) Estou enviando Conteúdos no âmbito do meu trabalho para meu empregador (ou meu empregador detém os direitos de propriedade intelectual sobre meus Conteúdos por contrato ou legislação aplicável). Tenho permissão do meu empregador para enviar Conteúdos e celebrar este Acordo em nome dele. Ao assinar abaixo, o termo definido "Você" inclui a mim e ao meu empregador.

@microsoft-github-policy-service agree company="Microsoft"

Contrato de Licença de Colaborador

@microsoft-github-policy-service agree