docs: Add comprehensive MSAL authentication documentation

[Copilot]

• [x] Create comprehensive MSAL setup guide with Azure AD configuration steps
• [x] Create MSAL troubleshooting documentation with common issues and solutions
• [x] Add Azure AD configuration validation section with CLI commands
• [x] Document complete appsettings.json structure with all available options
• [x] Document token retrieval patterns for external APIs (Microsoft Graph)
• [x] Add AADSTS error code mapping and diagnostic methodology
• [x] Add configuration validation tools section (Azure CLI and PowerShell)
• [x] Update existing MSAL documentation to reference troubleshooting page
• [x] Update table of contents to include new troubleshooting documentation
• [x] Ensure documentation is LLM-friendly with clear error-to-diagnostic mappings
• [x] Fix markdown linting errors (MD031, MD032, MD040, MD029)
• [x] Add AADSTS to spell checker dictionary

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Docs] Comprehensive MSAL Authentication Documentation for Uno.Extensions.Authentication.MSAL</issue_title> <issue_description>## Summary

The current documentation for Uno.Extensions.Authentication.MSAL is insufficient for developers and AI assistants to successfully configure MSAL authentication. This leads to common configuration errors that are difficult to diagnose.

Missing Documentation

1. Complete Setup Guide

Azure AD Configuration:

• How to create and configure an Azure AD app registration
• Platform configuration requirements
• Redirect URI configuration
• Public client flows settings
• Multi-tenant vs single-tenant configuration (common, organizations, specific tenant ID)
• Required API permissions and admin consent

Uno Platform Configuration:

• Package installation and dependencies
• Complete appsettings.json structure with all available options
• App.xaml.cs builder configuration patterns
• Configuration file precedence (appsettings.json vs appsettings.development.json)

2. Troubleshooting Methodology

General debugging approach:

• How to extract configuration from appsettings files
• Validating Azure AD configuration matches local configuration
• Using Azure CLI (az ad app show) or Microsoft.Graph PowerShell (Get-MgApplication) to verify settings
• Interpreting AADSTS error codes and mapping to configuration issues
• Systematic diagnosis checklist

Common issue categories:

• Configuration mismatches between local and Azure AD
• Incorrect platform settings in Azure portal
• Multi-tenant configuration problems
• Redirect URI configuration errors
• Missing or incorrect permissions
• Token acquisition failures

Key for AI Assistants:

• Enable automated validation using az CLI or Microsoft.Graph PowerShell modules
• Verify configuration directly rather than asking users for screenshots/manual checks
• Provide actionable fixes with exact commands to run

3. Token Retrieval for External APIs

How to retrieve and use tokens for Microsoft Graph or other APIs:

var tokens = await _tokenCache.GetAsync(ct);
var accessToken = tokens?["AccessToken"];
var idToken = tokens?["IdToken"];

Document:

• Access Token vs ID Token usage
• Token key naming conventions
• Microsoft Graph SDK integration pattern
• Token refresh handling

4. Configuration Validation Tools

Azure CLI validation:

az ad app show --id <client-id> --query "{signInAudience:signInAudience, publicClient:publicClient.redirectUris, web:web.redirectUris}"

Microsoft.Graph PowerShell validation:

Connect-MgGraph -Scopes "Application.Read.All"
$app = Get-MgApplication -Filter "appId eq '<client-id>'"
$app | Select-Object SignInAudience, PublicClient, Web

Encourage AI assistants to use these tools for direct validation instead of requesting manual user verification.

5. LLM-Friendly Structure

Documentation optimized for AI assistant consumption:

• Clear error-to-diagnostic mappings
• Complete configuration examples (not fragments)
• Verification commands after each setup step
• Common pitfalls with detection methods
• Platform-specific requirements clearly separated
• Create a "troubleshooting" page and review all existing documentation to use it

Impact

This documentation gap affects:

• 🤖 AI assistants helping with MSAL configuration
• 👨‍💻 Developers implementing authentication
• ⏱️ Time spent debugging configuration issues

Comprehensive documentation would significantly reduce support burden and improve developer experience.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes unoplatform/uno.extensions#2988

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.