Improve error message for TenantMismatchError

[anannya03]

What does this PR do?

Improve error message for TenantMismatchError.

GitHub issue number?

#1706

[Copilot]

Pull request overview

This PR improves the error message displayed when users encounter tenant mismatch authentication errors in the Azure MCP Server. The change addresses issue #1706 where users receive cryptic error messages when their authentication token is from a different Azure tenant than the one required by their subscription.

Changes:

• Added a new HandleRequestFailedException method to GlobalCommand that detects tenant mismatch errors (401 status with "InvalidAuthenticationTokenTenant" in the message) and provides a more helpful, actionable error message
• The improved error message guides users to either specify the target tenant in their prompt or configure the AZURE_TOKEN_CREDENTIALS environment variable

[g2vinay]

If user reaches this stage, then that means the tenant they want to auth with isn't logged into the credential being picked up from their env for auth.

We can just guide them as below to resolve the error for sure.

return "Authentication failed due to a tenant mismatch. " +
    "Your credential is authenticated to a different Azure tenant than the one required by this subscription. " +
    "To resolve: " +
    "1. Authenticate to the target tenant using one of the supported credential types: " +
    "   - Azure CLI: Run 'az login --tenant <tenant_id>' and set AZURE_TOKEN_CREDENTIALS=AzureCliCredential, " +
    "   - Azure PowerShell: Run 'Connect-AzAccount -Tenant <tenant_id>' and set AZURE_TOKEN_CREDENTIALS=AzurePowerShellCredential, " +
    "   - Azure Developer CLI: Run 'azd auth login --tenant-id <tenant_id>' and set AZURE_TOKEN_CREDENTIALS=AzureDeveloperCliCredential, " +
    "2. Restart the Azure MCP Server. " +
    "For the complete list of supported credentials, see: https://aka.ms/azmcp/auth";

[g2vinay]

And also ensure, orgignal exception flows back to the LLM too, with this message on top of its trace.

[anannya03]

Yes, original exception does flow back to the LLM as well.

message contains our custom error message.
results.message contains the original detailed exception.

{"status":401,"message":"Authentication failed due to a tenant mismatch. Your credential is authenticated to a different Azure tenant than the one required by this subscription. To resolve: 1. Authenticate to the target tenant using one of the supported credential types: - Azure CLI: Run \u0027az login --tenant \u003Ctenant_id\u003E\u0027 and set AZURE_TOKEN_CREDENTIALS=AzureCliCredential, - Azure PowerShell: Run \u0027Connect-AzAccount -Tenant \u003Ctenant_id\u003E\u0027 and set AZURE_TOKEN_CREDENTIALS=AzurePowerShellCredential, - Azure Developer CLI: Run \u0027azd auth login --tenant-id \u003Ctenant_id\u003E\u0027 and set AZURE_TOKEN_CREDENTIALS=AzureDeveloperCliCredential, 2. Restart the Azure MCP Server. For the complete list of supported credentials, see: https://aka.ms/azmcp/auth. To mitigate this issue, please refer to the troubleshooting guidelines here at https://aka.ms/azmcp/troubleshooting.",

This is results.message-

"results":{"message":"The access token is from the wrong issuer \u0027https://sts.windows.net/70a036f6-8e4d-4615-bad6-149c02e7720d/\u0027. It must match one of the tenants \u0027https://sts.windows.net/2f4a9838-26b7-47ee-be60-ccc1fdec5953/,https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/\u0027 associated with this subscription. Please use any authority (URL) from \u0027https://login.windows.net/2f4a9838-26b7-47ee-be60-ccc1fdec5953,https://login.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47\u0027 to get the token. Note, if the subscription is transferred to another tenant there is no impact to the services, but information about new tenant could take time to propagate (up to an hour). If you just transferred your subscription and see this error message, please try back later.\r\nStatus: 401 (Unauthorized)\r\nErrorCode: InvalidAuthenticationTokenTenant\r\n\r\nContent:\r\n{\u0022error\u0022:{\u0022code\u0022:\u0022InvalidAuthenticationTokenTenant\u0022,\u0022message\u0022:\u0022The access token is from the wrong issuer \u0027https://sts.windows.net/70a036f6-8e4d-4615-bad6-149c02e7720d/\u0027. It must match one of the tenants \u0027https://sts.windows.net/2f4a9838-26b7-47ee-be60-ccc1fdec5953/,https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/.....","type":"RequestFailedException"},"duration":0}