diff --git a/sdk/identity/identity/CHANGELOG.md b/sdk/identity/identity/CHANGELOG.md index 330867712dea..0f96abc785f7 100644 --- a/sdk/identity/identity/CHANGELOG.md +++ b/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). diff --git a/sdk/identity/identity/README.md b/sdk/identity/identity/README.md index 96406269d74b..f813a6f34411 100644 --- a/sdk/identity/identity/README.md +++ b/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"; diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 4f341277d354..b8f53dc8b46f 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -1 +1,246 @@ -# Troubleshooting +## Troubleshooting Azure Identity Authentication Issues + +The Azure Identity SDK offers various `TokenCredential` implementations. The most common errors observed for failure scenarios tend to throw `CredentialUnavailableError` and `AuthenticationRequired` errors. + +- The `CredentialUnavailableError` indicates that the credential cannot execute in the current environment setup due to lack of required configuration. +- The `AuthenticationRequiredError` indicates that the credential was able to send an authentication request, but then received an error from the authority host. This can happen due to invalid configuration passed in to the credential at construction time. + +This troubleshooting guide covers mitigation steps to resolve errors thrown by the credentials in the Azure Identity client library for JavaScript and TypeScript. + +## Table of contents + +- [Permission issues](#permission-issues) +- [Troubleshoot default Azure credential authentication issues](#troubleshoot-default-azure-credential-authentication-issues) +- [Troubleshoot environment credential authentication issues](#troubleshoot-environment-credential-authentication-issues) +- [Troubleshoot service principal authentication issues](#troubleshoot-service-principal-authentication-issues) +- [Troubleshoot username and password authentication issues](#troubleshoot-username-and-password-authentication-issues) +- [Troubleshoot Managed Identity authentication issues](#troubleshoot-managed-identity-authentication-issues) +- [Troubleshoot Visual Studio Code authentication issues](#troubleshoot-visual-studio-code-authentication-issues) +- [Troubleshoot Azure CLI authentication issues](#troubleshoot-azure-cli-authentication-issues) +- [Troubleshoot Azure PowerShell authentication issues](#troubleshoot-azure-powershell-authentication-issues) + +## Permission issues + +If you're using app registration to authenticate the service, ensure the app registration has the correct permissions and role assignments in the service you want to use. For example, if you want to have access to the Azure App Configuration service through Azure Active Directory (Azure AD), make sure your app registration has the permissions and the role assignments for access to Azure AD. You can either be assigned the role directly or be in a group that is assigned the role. The "Contributor" and the "Owner" roles allow you to manage the App Configuration resource. In this case, you can either use "App Configuration Data Owner" directly on the user or the Azure AD group. Alternatively, use "Owner" on the Azure AD group. While the App Configuration data can be accessed using access keys, these keys don't grant direct access to the data using Azure AD. + +## Troubleshoot default Azure credential authentication issues + +### Credential unavailable + +The `DefaultAzureCredential` attempts to retrieve an access token by sequentially invoking a chain of credentials. In this scenario, the `CredentialUnavailableError` signifies that all credentials in the chain failed to retrieve the token in the current environment setup/configuration. You need to follow the configuration instructions for the respective credential you're looking to use via the `DefaultAzureCredential` chain, so that the credential can work in your environment. + +Follow the configuration instructions in the "Credential unavailable error" sections of the troubleshooting guidelines below for the respective credential/authentication type you're looking to use via `DefaultAzureCredential`: + +| Credential Type | Troubleshooting Guide | +| ----------------------------- | ------------------------------------------------------------------------------------------------------- | +| Environment credential | [Environment credential guide](#troubleshoot-environment-credential-authentication-issues) | +| Managed Identity credential | [Managed Identity guide](#troubleshoot-managed-identity-authentication-issues) | +| Visual Studio Code credential | [Visual Studio Code guide](#troubleshoot-visual-studio-code-authentication-issues) | +| Azure CLI credential | [Azure CLI guide](#troubleshoot-azure-cli-authentication-issues) | +| Azure PowerShell credential | [Azure PowerShell guide](#troubleshoot-azure-powershell-authentication-issues) | + +## Logging + +To help diagnose any errors in credentials that encompass multiple credentials like `DefaultAzureCredential`, [enabling logging](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md) will also help you get a better understanding. + +Consider a scenario in which you have the following environment variables set up either in your environment or _.env_ file: + +- `AZURE_TENANT_ID` +- `AZURE_CLIENT_ID` +- `AZURE_CLIENT_SECRET` + +You authenticate using `DefaultAzureCredential` and enable logging. You'll see the following logging statements: + +``` +azure:identity:info EnvironmentCredential => Found the following environment variables: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET +azure:identity:info EnvironmentCredential => Invoking ClientSecretCredential with tenant ID: [REDACTED], clientId: [REDACTED] and clientSecret: [REDACTED] +``` + +These logging statements indicate that the `EnvironmentCredential` is being used for authentication and `ClientSecretCredential` is invoked. + +## Troubleshoot environment credential authentication issues + +### Credential unavailable error + +#### Environment variables not configured + +The `EnvironmentCredential` supports the following types of authentication: + +- Client Secret +- Client Certificate +- Username and Password + +To utilize the desired authentication type via `EnvironmentCredential`, ensure the following environment variables are configured properly and that the app can read them. + +##### ClientSecret credential + +| Variable Name | Value | +| ------------------- | -------------------------------- | +| `AZURE_CLIENT_ID` | ID of an Azure AD app. | +| `AZURE_TENANT_ID` | ID of the app's Azure AD tenant. | +| `AZURE_CLIENT_SECRET` | One of the app's client secrets. | + +##### ClientCertificate credential + +| Variable name | Value | +| ----------------------------- | ------------------------------------------------------------------------------------------- | +| `AZURE_CLIENT_ID` | ID of an Azure AD app. | +| `AZURE_TENANT_ID` | ID of the app's Azure AD tenant. | +| `AZURE_CLIENT_CERTIFICATE_PATH` | Path to a PEM-encoded certificate file including private key (without password protection). | + +##### Username and password + +| Variable name | Value | +| --------------- | ----------------------------------------------- | +| `AZURE_CLIENT_ID` | ID of an Azure AD app. | +| `AZURE_USERNAME` | A username (usually an email address). | +| `AZURE_PASSWORD` | The associated password for the given username. | + +### Client authentication error + +The `EnvironmentCredential` supports service principal authentication and username and password authentication. +Follow the troubleshooting guidelines below for the respective authentication type that failed. + +| Authentication Type | Troubleshooting Guide | +| ------------------------------- | -------------------------------------------------------------------------------------------------- | +| ClientSecret/ClientCertificate | [Service principal auth guide](#troubleshoot-service-principal-authentication-issues) | +| Username and password | [Username and password auth guide](#troubleshoot-username-password-authentication-issues) | + +## Troubleshoot username and password authentication issues + +### Two-factor authentication required error + +The `UsernamePasswordCredential` works only for users whose two-factor authentication has been disabled in Azure AD. You can change the multi-factor authentication in the Azure portal with the steps [here](https://docs.microsoft.com/azure/active-directory/authentication/howto-mfa-userstates#change-the-status-for-a-user). + +### Request body must contain the following parameter: 'client_assertion' or 'client_secret' + +The error `The request body must contain the following parameter: 'client_assertion' or 'client_secret'`, occurs because of how the Azure AD app is configured. The Azure AD app registration seems to be configured as a confidential app. The `UsernamePasswordCredential` works only with public clients and doesn't support confidential apps. To support confidential apps, use either `ClientSecretCredential` or `ClientCertificateCredential` instead. + +To allow public client authentication on your Azure AD tenant: + +1. In the Azure portal, navigate to the **Authentication** page. +2. Scroll to the bottom of the page. You'll see something that says **Allow public client flows**. Near that, you'll see a **yes** / **no** toggle. Set this toggle to **yes**. + +After that, you shouldn't need to specify a client secret to authenticate with this credential. + +## Troubleshoot service principal authentication issues + +### Invalid argument issues + +#### Client Id + +The Client ID is the app ID of the registered app / service principal in Azure AD. It's a required parameter for `ClientSecretCredential` and `ClientCertificateCredential`. If you've already created your service principal, you can retrieve the client/app ID by following the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). + +#### Tenant Id + +The tenant ID is the Global Unique Identifier (GUID) that identifies your organization. It's a required parameter for `ClientSecretCredential` and `ClientCertificateCredential`. If you've already created your service principal, you can retrieve the client/app ID by following the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). + +### Client secret credential issues + +#### Client secret argument + +The client secret is the secret string that the app uses to prove its identity when requesting a token. This can also can be referred to as an app password. If you've already created a service principal, follow the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret) to get the client secret for your app. + +### Client certificate credential issues + +#### Client certificate argument + +The `ClientCertificateCredential` accepts PEM certificates (`pfx` certificates aren't supported by the JavaScript SDK for now). The certificate needs to be associated with your registered app/service principal. To create and associate a certificate with your registered app, follow the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-1-upload-a-certificate). + +### Create a new service principal + +If you're looking to create a new service principal and would like to use that, then follow the instructions [here](https://docs.microsoft.com/azure/developer/javascript/how-to/with-sdk/set-up-development-environment?tabs=azure-sdk-for-javascript#1-create-a-service-principal) to create a new service principal. + +## Troubleshoot Managed Identity authentication issues + +### Credential unavailable error + +#### Connection timed out / connection could not be established / target environment could not be determined + +The Managed Identity credential runs only on Azure-hosted machines/servers. Ensure that you're running your app on an Azure-hosted resource. Currently, the Azure Identity SDK supports [Managed Identity authentication](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) in the below listed Azure services. Ensure you're running your app on one of these resources and have enabled the Managed Identity on them by following the instructions at their configuration links below. + +| Azure Service | Managed Identity Configuration | +| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) | +| [Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=javascript) | [Configuration Instructions](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | +| [Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/use-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/aks/use-managed-identity) | +| [Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/msi-authorization) | | +| [Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-azure-arc-enabled-servers) | +| [Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) | + +## Troubleshoot Visual Studio Code authentication issues + +### Credential unavailable error + +#### Failed to read VS Code credentials / authenticate via Azure Tools plugin in VS Code + +The Visual Studio Code credential failed to read the credential details from the cache. + +Visual Studio Code authentication is handled by an integration with the Azure Account extension. To use this form of authentication, ensure that you've installed the Azure Account extension. Then select **View** > **Command Palette** > **Azure: Sign In**. This command opens a browser window and displays a page that allows you to sign in to Azure. After you've completed the login process, you can close the browser as directed. Running your app (either in the debugger or anywhere on the development machine) will use the credential from your sign-in. + +If you already had the Azure Account extension installed and had logged in to your account. Then try logging out and logging in again, as +that will re-populate the cache on the disk and potentially mitigate the error you're getting. + +After using the VS Code extension to authenticate once, if you use the `DefaultAzureCredential` outside of the VS Code, it will try to authenticate with the `VSCode credentials`. In this scenario, if you stop using VS Code for a while, your VS Code auth token will eventually expire. The sign-in with `DefaultAzureCredential` will begin to fail. In such cases, you have to log out of the VS Code extension (and log in again if you want to continue using it). + +#### MSAL interaction required error + +The VS Code credential was able to read the cached credentials from the cache but the cached token is likely expired. In VS Code, log in to the Azure Account extension via **View** > **Command Palette** > **Azure: Sign In**. + +#### ADFS tenant not supported + +The ADFS tenants aren't currently supported via the Azure Account extension in VS Code. +The supported clouds are: + +| Azure Cloud | Cloud Authority Host | +| ------------------ | ---------------------------------- | +| AZURE PUBLIC CLOUD | https://login.microsoftonline.com/ | +| AZURE GERMANY | https://login.microsoftonline.de/ | +| AZURE CHINA | https://login.chinacloudapi.cn/ | +| AZURE GOVERNMENT | https://login.microsoftonline.us/ | + +## Troubleshoot Azure CLI authentication issues + +### Credential unavailable error + +#### Azure CLI not installed + +The `AzureCliCredential` failed to execute as the Azure CLI command line tool isn't installed. +To use the Azure CLI credential, the Azure CLI needs to be installed. Follow the instructions [here](https://aka.ms/azure-cli) to install it for your platform. Then try running the credential again. + +#### Azure account not logged in + +The `AzureCliCredential` utilizes the currently logged in Azure user in Azure CLI to fetch an access token. You need to log in to your account in Azure CLI via the `az login` command. For further instructions, see [Sign in with Azure CLI](https://docs.microsoft.com/cli/azure/authenticate-azure-cli). Once logged in, try running the credential again. + +## Troubleshoot Azure PowerShell authentication issues + +### Credential unavailable error + +#### PowerShell not installed + +The `Azure PowerShell Credential` utilizes the locally installed `PowerShell` command line tool to fetch an access token. Ensure it's installed on your platform by following the instructions [here](https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-7.1). Then run the credential again. + +#### Azure Az Moudle not installed + +The Azure PowerShell credential failed to execute, as the Azure Az module isn't installed. To use the Azure PowerShell credential, install the Azure Az PowerShell module: + +````powershell +Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force +Then try running the credential again. + +#### Azure account not logged in + +The Azure PowerShell credential utilizes the currently logged in Azure user in Azure PowerShell to fetch an access token. +You need to log in to your account in Azure PowerShell via the `Connect-AzAccount` command. For further instructions, see [Sign in with Azure PowerShell](https://docs.microsoft.com/powershell/azure/authenticate-azureps?view=azps-6.3.0). Once logged in, try running the credential again. + +#### Deserialization error + +The Azure PowerShell credential was able to retrieve a response when attempting to get an access token but failed to parse that response. In your local PowerShell window, run the following command to ensure that Azure PowerShell returns an access token in the correct format: + +```powershell +Get-AzAccessToken -ResourceUrl "" +```` + +If the preceding command isn't working properly, follow the instructions to resolve the Azure PowerShell issue. Then try running the credential again. + +If this guide doesn't help you diagnose the errors you're experiencing, [open an issue](https://github.com/Azure/azure-sdk-for-js/issues). To contribute to the SDK, read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md). diff --git a/sdk/identity/identity/src/credentials/authorizationCodeCredential.browser.ts b/sdk/identity/identity/src/credentials/authorizationCodeCredential.browser.ts index 237b47c5a53a..ceb2c40eb988 100644 --- a/sdk/identity/identity/src/credentials/authorizationCodeCredential.browser.ts +++ b/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"); diff --git a/sdk/identity/identity/src/credentials/azureApplicationCredential.ts b/sdk/identity/identity/src/credentials/azureApplicationCredential.ts index a0343af27538..0fe2682104a4 100644 --- a/sdk/identity/identity/src/credentials/azureApplicationCredential.ts +++ b/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."; } } diff --git a/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts b/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts index 47eecd8036a0..095db8065661 100644 --- a/sdk/identity/identity/src/credentials/azurePowerShellCredential.ts +++ b/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; } diff --git a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts index 9157451d59ea..8e441faf52f2 100644 --- a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts +++ b/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({ diff --git a/sdk/identity/identity/src/credentials/clientSecretCredential.ts b/sdk/identity/identity/src/credentials/clientSecretCredential.ts index 55dd6f001a4d..5b42248de218 100644 --- a/sdk/identity/identity/src/credentials/clientSecretCredential.ts +++ b/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({ diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts index 5a17348d154d..76550f794253 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts +++ b/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."; } } diff --git a/sdk/identity/identity/src/credentials/environmentCredential.ts b/sdk/identity/identity/src/credentials/environmentCredential.ts index 3fe853d4da8a..1545a42557f8 100644 --- a/sdk/identity/identity/src/credentials/environmentCredential.ts +++ b/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." ); }); } diff --git a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts index 6cf85eab6638..aa27070120d0 100644 --- a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts +++ b/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({ diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts index 970f01bb318f..28597b3a3097 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts +++ b/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; diff --git a/sdk/identity/identity/test/internal/node/azurePowerShellCredential.spec.ts b/sdk/identity/identity/test/internal/node/azurePowerShellCredential.spec.ts index d84e6a70e90a..31188895b77a 100644 --- a/sdk/identity/identity/test/internal/node/azurePowerShellCredential.spec.ts +++ b/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(); diff --git a/sdk/identity/identity/test/internal/node/clientCertificateCredential.spec.ts b/sdk/identity/identity/test/internal/node/clientCertificateCredential.spec.ts index 367c12e4e6a2..285763044780 100644 --- a/sdk/identity/identity/test/internal/node/clientCertificateCredential.spec.ts +++ b/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." ); }); diff --git a/sdk/identity/identity/test/internal/node/clientSecretCredential.spec.ts b/sdk/identity/identity/test/internal/node/clientSecretCredential.spec.ts index 53fd67c3ca5e..0394ce916a2a 100644 --- a/sdk/identity/identity/test/internal/node/clientSecretCredential.spec.ts +++ b/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." ); }); }); diff --git a/sdk/identity/identity/test/internal/node/usernamePasswordCredential.spec.ts b/sdk/identity/identity/test/internal/node/usernamePasswordCredential.spec.ts index e01c78cf6259..a2fa3f00cd83 100644 --- a/sdk/identity/identity/test/internal/node/usernamePasswordCredential.spec.ts +++ b/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." ); }); });