add troubleshooting guide for identity (Azure#17734)

* add troubleshooting guide for identity
Co-authored-by: Scott Addie <[email protected]>

sdk/identity/identity/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 After multiple beta releases over the past year, we're proud to announce the general availability of version 2 of the `@azure/identity` package. This version includes the best parts of v1, plus several improvements.
 
-This changelog entry showcases the changes that have been made from version 1 of this package. See the [v1-to-v2 migration guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/migration-v1-v2.md) for details on how to upgrade your application to use the version 2 of `@azure/identity`.
+This changelog entry showcases the changes that have been made from version 1 of this package. See the [v1-to-v2 migration guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/migration-v1-v2.md) for details on how to upgrade your application to use the version 2 of `@azure/identity`. For information on troubleshooting the Identity package, see the [troubleshooting guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/Troubleshooting.md).
 
 ### Features Added
 
@@ -68,6 +68,7 @@ A new method `authenticate()` is added to these credentials which is similar to
 - `authenticate()` might succeed and still return `undefined` if we're unable to pick just one account record from the cache. This might happen if the cache is being used by more than one credential, or if multiple users have authenticated using the same Client ID and Tenant ID. To ensure consistency on a program with many users, please keep track of the `AuthenticationRecord` and provide them in the constructors of the credentials on initialization.
 
 Learn more via the below samples
+
 - [Samples around controlling user interaction](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#control-user-interaction).
 - [Samples around persisting user authentication data](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#persist-user-authentication-data).
 

sdk/identity/identity/README.md

@@ -283,7 +283,13 @@ Credentials raise `AuthenticationError` when they fail to authenticate. This cla
 
 ### Logging
 
-Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
+Enabling logging may help uncover useful information about failures. To see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. You can read this environment variable from the *.env* file by explicitly specifying a file path:
+
+```javascript
+require("dotenv").config({ path: ".env" });
+```
+
+Alternatively, logging can be enabled at runtime by calling `setLogLevel` from the `@azure/logger` package:
 
 ```javascript
 import { setLogLevel } from "@azure/logger";

sdk/identity/identity/src/credentials/authorizationCodeCredential.browser.ts

@@ -7,7 +7,7 @@ import { TokenCredentialOptions } from "../client/identityClient";
 import { credentialLogger, formatError } from "../util/logging";
 
 const BrowserNotSupportedError = new Error(
-  "AuthorizationCodeCredential is not supported in the browser.  InteractiveBrowserCredential is more appropriate for this use case."
+  "AuthorizationCodeCredential is not supported in the browser. InteractiveBrowserCredential is more appropriate for this use case."
 );
 const logger = credentialLogger("AuthorizationCodeCredential");
 

sdk/identity/identity/src/credentials/azureApplicationCredential.ts

@@ -60,6 +60,6 @@ export class AzureApplicationCredential extends ChainedTokenCredential {
   constructor(options?: AzureApplicationCredentialOptions) {
     super(...AzureApplicationCredentials.map((ctor) => new ctor(options)));
     this.UnavailableMessage =
-      "ApplicationCredential => failed to retrieve a token from the included credentials";
+      "ApplicationCredential => failed to retrieve a token from the included credentials. To troubleshoot, visit https://aka.ms/azsdk/js/identity/applicationcredential/troubleshoot.";
   }
 }

sdk/identity/identity/src/credentials/azurePowerShellCredential.ts

@@ -63,7 +63,8 @@ export const powerShellErrors = {
 export const powerShellPublicErrorMessages = {
   login:
     "Please run 'Connect-AzAccount' from PowerShell to authenticate before using this credential.",
-  installed: `The 'Az.Account' module >= 2.2.0 is not installed. Install the Azure Az PowerShell module with: "Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force".`
+  installed: `The 'Az.Account' module >= 2.2.0 is not installed. Install the Azure Az PowerShell module with: "Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force".`,
+  troubleshoot: `To troubleshoot, visit https://aka.ms/azsdk/js/identity/powershellcredential/troubleshoot.`
 };
 
 // PowerShell Azure User not logged in error check.
@@ -92,7 +93,7 @@ export class AzurePowerShellCredential implements TokenCredential {
   private tenantId?: string;
 
   /**
-   * Creates an instance of the {@link AzurePowershellCredential}.
+   * Creates an instance of the {@link AzurePowerShellCredential}.
    *
    * To use this credential:
    * - Install the Azure Az PowerShell module with:
@@ -150,7 +151,7 @@ export class AzurePowerShellCredential implements TokenCredential {
       }
     }
 
-    throw new Error(`Unable to execute PowerShell. Ensure that it is installed in your system.`);
+    throw new Error(`Unable to execute PowerShell. Ensure that it is installed in your system`);
   }
 
   /**
@@ -192,7 +193,9 @@ export class AzurePowerShellCredential implements TokenCredential {
           logger.getToken.info(formatError(scope, error));
           throw error;
         }
-        const error = new CredentialUnavailableError(err);
+        const error = new CredentialUnavailableError(
+          `${err}. ${powerShellPublicErrorMessages.troubleshoot}`
+        );
         logger.getToken.info(formatError(scope, error));
         throw error;
       }

sdk/identity/identity/src/credentials/clientCertificateCredential.ts

@@ -97,12 +97,12 @@ export class ClientCertificateCredential implements TokenCredential {
     };
     if (!configuration || !(configuration.certificate || configuration.certificatePath)) {
       throw new Error(
-        `${credentialName}: Provide either a PEM certificate in string form, or the path to that certificate in the filesystem.`
+        `${credentialName}: Provide either a PEM certificate in string form, or the path to that certificate in the filesystem. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.`
       );
     }
     if (configuration.certificate && configuration.certificatePath) {
       throw new Error(
-        `${credentialName}: To avoid unexpected behaviors, providing both the contents of a PEM certificate and the path to a PEM certificate is forbidden.`
+        `${credentialName}: To avoid unexpected behaviors, providing both the contents of a PEM certificate and the path to a PEM certificate is forbidden. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.`
       );
     }
     this.msalFlow = new MsalClientCertificate({

sdk/identity/identity/src/credentials/clientSecretCredential.ts

@@ -40,7 +40,7 @@ export class ClientSecretCredential implements TokenCredential {
   ) {
     if (!tenantId || !clientId || !clientSecret) {
       throw new Error(
-        "ClientSecretCredential: tenantId, clientId, and clientSecret are required parameters."
+        "ClientSecretCredential: tenantId, clientId, and clientSecret are required parameters. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot."
       );
     }
     this.msalFlow = new MsalClientSecret({

sdk/identity/identity/src/credentials/defaultAzureCredential.ts

@@ -94,6 +94,6 @@ export class DefaultAzureCredential extends ChainedTokenCredential {
   constructor(options?: DefaultAzureCredentialOptions) {
     super(...defaultCredentials.map((ctor) => new ctor(options)));
     this.UnavailableMessage =
-      "DefaultAzureCredential => failed to retrieve a token from the included credentials";
+      "DefaultAzureCredential => failed to retrieve a token from the included credentials. To troubleshoot, visit https://aka.ms/azsdk/js/identity/defaultazurecredential/troubleshoot.";
   }
 }

sdk/identity/identity/src/credentials/environmentCredential.ts

@@ -132,7 +132,8 @@ export class EnvironmentCredential implements TokenCredential {
           return result;
         } catch (err) {
           const authenticationError = new AuthenticationError(400, {
-            error: "EnvironmentCredential authentication failed.",
+            error:
+              "EnvironmentCredential authentication failed. To troubleshoot, visit https://aka.ms/azsdk/js/identity/environmentcredential/troubleshoot.",
             error_description: err.message
               .toString()
               .split("More details:")
@@ -143,7 +144,7 @@ export class EnvironmentCredential implements TokenCredential {
         }
       }
       throw new CredentialUnavailableError(
-        "EnvironmentCredential is unavailable. No underlying credential could be used."
+        "EnvironmentCredential is unavailable. No underlying credential could be used. To troubleshoot, visit https://aka.ms/azsdk/js/identity/environmentcredential/troubleshoot."
       );
     });
   }

sdk/identity/identity/src/credentials/usernamePasswordCredential.ts

@@ -40,7 +40,7 @@ export class UsernamePasswordCredential implements TokenCredential {
   ) {
     if (!tenantId || !clientId || !username || !password) {
       throw new Error(
-        "UsernamePasswordCredential: tenantId, clientId, username and password are required parameters."
+        "UsernamePasswordCredential: tenantId, clientId, username and password are required parameters. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot."
       );
     }
     this.msalFlow = new MsalUsernamePassword({

sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts

@@ -232,14 +232,14 @@ export class VisualStudioCodeCredential implements TokenCredential {
         return tokenResponse.accessToken;
       } else {
         const error = new CredentialUnavailableError(
-          "Could not retrieve the token associated with Visual Studio Code. Have you connected using the 'Azure Account' extension recently?"
+          "Could not retrieve the token associated with Visual Studio Code. Have you connected using the 'Azure Account' extension recently? To troubleshoot, visit https://aka.ms/azsdk/js/identity/visualstudiocodecredential/troubleshoot."
         );
         logger.getToken.info(formatError(scopes, error));
         throw error;
       }
     } else {
       const error = new CredentialUnavailableError(
-        "Could not retrieve the token associated with Visual Studio Code. Did you connect using the 'Azure Account' extension?"
+        "Could not retrieve the token associated with Visual Studio Code. Did you connect using the 'Azure Account' extension? To troubleshoot, visit https://aka.ms/azsdk/js/identity/visualstudiocodecredential/troubleshoot."
       );
       logger.getToken.info(formatError(scopes, error));
       throw error;

sdk/identity/identity/test/internal/node/azurePowerShellCredential.spec.ts

@@ -108,7 +108,7 @@ describe("AzurePowerShellCredential", function() {
     assert.equal(error?.name, "CredentialUnavailableError");
     assert.equal(
       error?.message,
-      `Error: Unable to execute PowerShell. Ensure that it is installed in your system.`
+      `Error: Unable to execute PowerShell. Ensure that it is installed in your system. To troubleshoot, visit https://aka.ms/azsdk/js/identity/powershellcredential/troubleshoot.`
     );
 
     sandbox.restore();
@@ -136,7 +136,7 @@ describe("AzurePowerShellCredential", function() {
     assert.equal(error?.name, "CredentialUnavailableError");
     assert.equal(
       error?.message,
-      `Error: Unable to parse the output of PowerShell. Received output: Not valid JSON`
+      `Error: Unable to parse the output of PowerShell. Received output: Not valid JSON. To troubleshoot, visit https://aka.ms/azsdk/js/identity/powershellcredential/troubleshoot.`
     );
 
     sandbox.restore();
@@ -166,7 +166,7 @@ describe("AzurePowerShellCredential", function() {
       assert.equal(error?.name, "CredentialUnavailableError");
       assert.equal(
         error?.message,
-        `Error: Unable to parse the output of PowerShell. Received output: Not valid JSON`
+        `Error: Unable to parse the output of PowerShell. Received output: Not valid JSON. To troubleshoot, visit https://aka.ms/azsdk/js/identity/powershellcredential/troubleshoot.`
       );
 
       sandbox.restore();

sdk/identity/identity/test/internal/node/clientCertificateCredential.spec.ts

@@ -86,7 +86,7 @@ describe("ClientCertificateCredential (internal)", function() {
     errors.forEach((e) => {
       assert.equal(
         e.message,
-        "ClientCertificateCredential: Provide either a PEM certificate in string form, or the path to that certificate in the filesystem."
+        "ClientCertificateCredential: Provide either a PEM certificate in string form, or the path to that certificate in the filesystem. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot."
       );
     });
 
@@ -103,7 +103,7 @@ describe("ClientCertificateCredential (internal)", function() {
     assert.ok(error);
     assert.equal(
       (error as Error).message,
-      "ClientCertificateCredential: To avoid unexpected behaviors, providing both the contents of a PEM certificate and the path to a PEM certificate is forbidden."
+      "ClientCertificateCredential: To avoid unexpected behaviors, providing both the contents of a PEM certificate and the path to a PEM certificate is forbidden. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot."
     );
   });
 

sdk/identity/identity/test/internal/node/clientSecretCredential.spec.ts

@@ -62,7 +62,7 @@ describe("ClientSecretCredential (internal)", function() {
     errors.forEach((e) => {
       assert.equal(
         e.message,
-        "ClientSecretCredential: tenantId, clientId, and clientSecret are required parameters."
+        "ClientSecretCredential: tenantId, clientId, and clientSecret are required parameters. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot."
       );
     });
   });

sdk/identity/identity/test/internal/node/usernamePasswordCredential.spec.ts

@@ -93,7 +93,7 @@ describe("UsernamePasswordCredential (internal)", function() {
     errors.forEach((e) => {
       assert.equal(
         e.message,
-        "UsernamePasswordCredential: tenantId, clientId, username and password are required parameters."
+        "UsernamePasswordCredential: tenantId, clientId, username and password are required parameters. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot."
       );
     });
   });