Add troubleshooting message link to credential exceptions (Azure#23979)

* Add troubleshooting message link to credential exceptions

Author: christothes

sdk/identity/Azure.Identity/src/AzureCliCredential.cs

@@ -25,6 +25,7 @@ public class AzureCliCredential : TokenCredential
         internal const string WinAzureCLIError = "'az' is not recognized";
         internal const string AzureCliTimeoutError = "Azure CLI authentication timed out.";
         internal const string AzureCliFailedError = "Azure CLI authentication failed due to an unknown error.";
+        internal const string Troubleshoot = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/azclicredential/troubleshoot";
         internal const string InteractiveLoginRequired = "Azure CLI could not login. Interactive login is required.";
         internal const string CLIInternalError = "CLIInternalError: The command failed with an unexpected error. Here is the traceback:";
         private const int CliProcessTimeoutMs = 13000;
@@ -156,7 +157,7 @@ private async ValueTask<AccessToken> RequestCliAccessTokenAsync(bool async, Toke
                     throw new CredentialUnavailableException(InteractiveLoginRequired);
                 }
 
-                throw new AuthenticationFailedException($"{AzureCliFailedError} {exception.Message}");
+                throw new AuthenticationFailedException($"{AzureCliFailedError} {Troubleshoot} {exception.Message}");
             }
 
             return DeserializeOutput(output);

sdk/identity/Azure.Identity/src/AzurePowerShellCredential.cs

@@ -27,7 +27,8 @@ public class AzurePowerShellCredential : TokenCredential
         private const int PowerShellProcessTimeoutMs = 10000;
         internal bool UseLegacyPowerShell { get; set; }
 
-        private const string AzurePowerShellFailedError = "Azure PowerShell authentication failed due to an unknown error.";
+        private const string Troubleshooting = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/powershellcredential/troubleshoot";
+        private const string AzurePowerShellFailedError = "Azure PowerShell authentication failed due to an unknown error. " + Troubleshooting;
         private const string AzurePowerShellTimeoutError = "Azure PowerShell authentication timed out.";
         internal const string AzurePowerShellNotLogInError = "Please run 'Connect-AzAccount' to set up account.";
         internal const string AzurePowerShellModuleNotInstalledError = "Az.Account module >= 2.2.0 is not installed.";

sdk/identity/Azure.Identity/src/CredentialDiagnosticScope.cs

@@ -36,9 +36,9 @@ public AccessToken Succeeded(AccessToken token)
             return token;
         }
 
-        public Exception FailWrapAndThrow(Exception ex)
+        public Exception FailWrapAndThrow(Exception ex, string additionalMessage = null)
         {
-            var wrapped = TryWrapException(ref ex);
+            var wrapped = TryWrapException(ref ex, additionalMessage);
             RegisterFailed(ex);
 
             if (!wrapped)
@@ -55,7 +55,7 @@ private void RegisterFailed(Exception ex)
             _scopeHandler.Fail(_name, _scope, ex);
         }
 
-        private bool TryWrapException(ref Exception exception)
+        private bool TryWrapException(ref Exception exception, string additionalMessageText = null)
         {
             if (exception is OperationCanceledException || exception is AuthenticationFailedException)
             {
@@ -71,8 +71,12 @@ private bool TryWrapException(ref Exception exception)
                     return true;
                 }
             }
-
-            exception = new AuthenticationFailedException($"{_name.Substring(0, _name.IndexOf('.'))} authentication failed: {exception.Message}", exception);
+            string exceptionMessage = $"{_name.Substring(0, _name.IndexOf('.'))} authentication failed: {exception.Message}";
+            if (additionalMessageText != null)
+            {
+                exceptionMessage = exceptionMessage + $"\n{additionalMessageText}";
+            }
+            exception = new AuthenticationFailedException(exceptionMessage, exception);
             return true;
         }
 

sdk/identity/Azure.Identity/src/DefaultAzureCredential.cs

@@ -47,7 +47,8 @@ namespace Azure.Identity
     /// </example>
     public class DefaultAzureCredential : TokenCredential
     {
-        private const string DefaultExceptionMessage = "DefaultAzureCredential failed to retrieve a token from the included credentials.";
+        private const string Troubleshooting = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/defaultazurecredential/troubleshoot";
+        private const string DefaultExceptionMessage = "DefaultAzureCredential failed to retrieve a token from the included credentials. " + Troubleshooting;
         private const string UnhandledExceptionMessage = "DefaultAzureCredential authentication failed due to an unhandled exception: ";
         private static readonly TokenCredential[] s_defaultCredentialChain = GetDefaultAzureCredentialChain(new DefaultAzureCredentialFactory(null), new DefaultAzureCredentialOptions());
 

sdk/identity/Azure.Identity/src/EnvironmentCredential.cs

@@ -28,7 +28,7 @@ namespace Azure.Identity
     /// </summary>
     public class EnvironmentCredential : TokenCredential
     {
-        private const string UnavailableErrorMessage = "EnvironmentCredential authentication unavailable. Environment variables are not fully configured.";
+        private const string UnavailableErrorMessage = "EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot";
         private readonly CredentialPipeline _pipeline;
         private readonly TokenCredentialOptions _options;
 

sdk/identity/Azure.Identity/src/ManagedIdentityCredential.cs

@@ -24,6 +24,7 @@ public class ManagedIdentityCredential : TokenCredential
 
         private readonly CredentialPipeline _pipeline;
         private readonly ManagedIdentityClient _client;
+        private const string Troubleshooting = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/managedidentitycredential/troubleshoot";
 
         /// <summary>
         /// Protected constructor for mocking.
@@ -90,7 +91,7 @@ private async ValueTask<AccessToken> GetTokenImplAsync(bool async, TokenRequestC
             }
             catch (Exception e)
             {
-               throw scope.FailWrapAndThrow(e);
+               throw scope.FailWrapAndThrow(e, Troubleshooting);
             }
         }
     }

sdk/identity/Azure.Identity/src/UsernamePasswordCredential.cs

@@ -19,6 +19,7 @@ namespace Azure.Identity
     public class UsernamePasswordCredential : TokenCredential
     {
         private const string NoDefaultScopeMessage = "Authenticating in this environment requires specifying a TokenRequestContext.";
+        private const string Troubleshooting = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/usernamepasswordcredential/troubleshoot";
 
         private readonly string _clientId;
         private readonly CredentialPipeline _pipeline;
@@ -185,7 +186,7 @@ private async Task<AuthenticationResult> AuthenticateImplAsync(bool async, Token
             }
             catch (Exception e)
             {
-                throw scope.FailWrapAndThrow(e);
+                throw scope.FailWrapAndThrow(e, Troubleshooting);
             }
         }
 
@@ -215,7 +216,7 @@ private async Task<AccessToken> GetTokenImplAsync(bool async, TokenRequestContex
             }
             catch (Exception e)
             {
-                throw scope.FailWrapAndThrow(e);
+                throw scope.FailWrapAndThrow(e, Troubleshooting);
             }
         }
     }

sdk/identity/Azure.Identity/src/VisualStudioCodeCredential.cs

@@ -26,6 +26,7 @@ public class VisualStudioCodeCredential : TokenCredential
         private readonly CredentialPipeline _pipeline;
         private readonly string _tenantId;
         private const string _commonTenant = "common";
+        private const string Troubleshooting = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/vscodecredential/troubleshoot";
         internal MsalPublicClient Client { get; }
 
         /// <summary>
@@ -83,12 +84,12 @@ private async ValueTask<AccessToken> GetTokenImplAsync(TokenRequestContext reque
             {
                 throw scope.FailWrapAndThrow(
                     new CredentialUnavailableException(
-                        $"{nameof(VisualStudioCodeCredential)} authentication unavailable. Token acquisition failed. Ensure that you have authenticated in VSCode Azure Account.",
+                        $"{nameof(VisualStudioCodeCredential)} authentication unavailable. Token acquisition failed. Ensure that you have authenticated in VSCode Azure Account. " + Troubleshooting,
                         e));
             }
             catch (Exception e)
             {
-                throw scope.FailWrapAndThrow(e);
+                throw scope.FailWrapAndThrow(e, Troubleshooting);
             }
         }
 
@@ -106,7 +107,7 @@ private string GetStoredCredentials(string environmentName)
             }
             catch (Exception ex) when (!(ex is OperationCanceledException || ex is CredentialUnavailableException))
             {
-                throw new CredentialUnavailableException("Stored credentials not found. Need to authenticate user in VSCode Azure Account.", ex);
+                throw new CredentialUnavailableException("Stored credentials not found. Need to authenticate user in VSCode Azure Account. " + Troubleshooting, ex);
             }
         }
 

sdk/identity/Azure.Identity/tests/AzureCliCredentialTests.cs

@@ -80,7 +80,7 @@ public static IEnumerable<object[]> AzureCliExceptionScenarios()
             yield return new object[] { AzureCliCredential.AzNotLogIn, AzureCliCredential.AzNotLogIn, typeof(CredentialUnavailableException) };
             yield return new object[] { RefreshTokenExpiredError, AzureCliCredential.InteractiveLoginRequired, typeof(CredentialUnavailableException) };
             yield return new object[] { AzureCliCredential.CLIInternalError, AzureCliCredential.InteractiveLoginRequired, typeof(CredentialUnavailableException) };
-            yield return new object[] { "random unknown exception", AzureCliCredential.AzureCliFailedError + " random unknown exception", typeof(AuthenticationFailedException) };
+            yield return new object[] { "random unknown exception", AzureCliCredential.AzureCliFailedError + " " + AzureCliCredential.Troubleshoot + " random unknown exception", typeof(AuthenticationFailedException) };
         }
 
         [Test]