From dee81c3453eba83601cce2ae51b69df3e22d671a Mon Sep 17 00:00:00 2001 From: Karishma Ghiya Date: Fri, 17 Sep 2021 17:21:07 -0700 Subject: [PATCH 01/24] add troubleshooting guide for identity Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/CHANGELOG.md | 3 +- sdk/identity/identity/README.md | 8 +- sdk/identity/identity/Troubleshooting.md | 256 +++++++++++++++++- .../authorizationCodeCredential.browser.ts | 2 +- .../credentials/azureApplicationCredential.ts | 2 +- .../credentials/azurePowerShellCredential.ts | 11 +- .../clientCertificateCredential.ts | 4 +- .../src/credentials/clientSecretCredential.ts | 2 +- .../src/credentials/defaultAzureCredential.ts | 2 +- .../src/credentials/environmentCredential.ts | 5 +- .../credentials/usernamePasswordCredential.ts | 2 +- .../credentials/visualStudioCodeCredential.ts | 4 +- .../node/azurePowerShellCredential.spec.ts | 6 +- .../node/clientCertificateCredential.spec.ts | 4 +- .../node/clientSecretCredential.spec.ts | 2 +- .../node/usernamePasswordCredential.spec.ts | 2 +- 16 files changed, 290 insertions(+), 25 deletions(-) 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..c4ec787464f9 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -1 +1,255 @@ -# 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 `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 AD group. Alternatively, use "Owner" on the 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 | Troubleshoot Guide | +| ----------------------------- | ------------------------------------------------------------------------------------------------------- | +| Environment Credential | [Environment Credential Troubleshoot Guide](#troubleshoot-environment-credential-authentication-issues) | +| Managed Identity Credential | [Managed Identity Troubleshoot Guide](#troubleshoot-managed-identity-authentication-issues) | +| Visual Studio Code Credential | [Visual Studio Code Troubleshoot Guide](#troubleshoot-visual-studio-code-authentication-issues) | +| Azure CLI Credential | [Azure CLI Troubleshoot Guide](#troubleshoot-azure-cli-authentication-issues) | +| Azure PowerShell Credential | [Azure PowerShell Troubleshoot 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 | Troubleshoot Guide | +| ------------------------------- | -------------------------------------------------------------------------------------------------- | +| ClientSecret/ ClientCertificate | [Service Principal Auth Troubleshoot Guide](#troubleshoot-service-principal-authentication-issues) | +| Username Password | [Username Password Auth Troubleshoot Guide](#troubleshoot-username-password-authentication-issues) | + +## Troubleshoot username and password authentication issues + +### Two-factor authentication required error + +The `UsernamePassword` credential 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' + +When you get the error `The request body must contain the following parameter: 'client_assertion' or 'client_secret'`, it happens because of how the AAD app is configured. The AAD app registration seems to be configured as a confidential app. The `UsernamePassword` credential works only with public clients and doesn't support confidential apps. To support confidential apps, use `ClientSecret` or `ClientCertificate` credentials instead. + +To allow public client authentication on your Azure AD tenant: + +- Go to the Azure portal. +- Go to the `Authentication` page. +- Scroll to the bottom of this page, and you will see something that says: `Allow public client flows`, and close to that, you will see a `yes` and `no` switch. Make sure this is set to `yes`. + After that, you should not 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 application uses to prove its identity when requesting a token. This can also can be referred to as an application 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 `Client Certificate Credential` accepts `pem` certificates (`pfx` certificates are not supported by JS SDK for now). The certificate needs to be associated with your registered application/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. + +The Visual Studio Code authentication is handled by an integration with the Azure Account extension. +To use this form of authentication, ensure that you have installed the Azure Account extension, +then use View > Command Palette to execute the Azure: Sign In command. 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 application +(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 get expired, and the sign in with `DefaultAzureCredential` will begin to fail. In such cases, you have to log out on 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 are not supported via the Azure Account extension in VS Code currently. +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 `Azure CLI Credential` failed to execute as Azure CLI command line tool isn't installed. +To use 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 and then try running the credential again. + +#### Azure account not logged in + +The `Azure CLI Credential` utilizes the current logged in Azure user in Azure CLI to fetch an access token. +You need to login to your account in Azure CLI via `az login` command. You can further read instructions to [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 is installed on your platform by following the instructions [here](https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-7.1) and 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." ); }); }); From 71d36426f345f2e48d220c772f8458df3114e38d Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:42:54 -0700 Subject: [PATCH 02/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index c4ec787464f9..8c821bd0362c 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -21,7 +21,7 @@ This troubleshooting guide covers mitigation steps to resolve errors thrown by t ## 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 `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 AD group. Alternatively, use "Owner" on the 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. +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 From 21128c8fad1b3a20d59262d109577a60059392df Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:43:47 -0700 Subject: [PATCH 03/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 8c821bd0362c..881631b7f03c 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -226,7 +226,7 @@ Once logged in try running the credential again. #### PowerShell not installed -The `Azure PowerShell Credential` utilizes the locally installed `PowerShell` command line tool to fetch an access token. Ensure it is installed on your platform by following the instructions [here](https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-7.1) and then run the credential again. +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 From d49bca605217f624bdf0615e084db8e7b6d4cf6c Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:43:55 -0700 Subject: [PATCH 04/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 881631b7f03c..f1180546ee00 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -211,7 +211,7 @@ The supported clouds are: #### Azure CLI not installed -The `Azure CLI Credential` failed to execute as Azure CLI command line tool isn't installed. +The `AzureCliCredential` failed to execute as the Azure CLI command line tool isn't installed. To use 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 and then try running the credential again. #### Azure account not logged in From c19de81623cfb5a4fc2d72d010911a37cc4b9613 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:44:03 -0700 Subject: [PATCH 05/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index f1180546ee00..9fc3c2711f23 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -212,7 +212,7 @@ The supported clouds are: #### Azure CLI not installed The `AzureCliCredential` failed to execute as the Azure CLI command line tool isn't installed. -To use 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 and then try running the credential again. +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 From 6b0ea8e075e19aaf4d314a2b46f6e6634bb4c357 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:44:18 -0700 Subject: [PATCH 06/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 9fc3c2711f23..1781a302aa75 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -239,8 +239,7 @@ 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. +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 From d2ab2be19acbd7cb45db072eb7c0c7efc17c36a2 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:44:25 -0700 Subject: [PATCH 07/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 1781a302aa75..693fcfe341ad 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -216,9 +216,7 @@ To use the Azure CLI credential, the Azure CLI needs to be installed. Follow the #### Azure account not logged in -The `Azure CLI Credential` utilizes the current logged in Azure user in Azure CLI to fetch an access token. -You need to login to your account in Azure CLI via `az login` command. You can further read instructions to [Sign in with Azure CLI](https://docs.microsoft.com/cli/azure/authenticate-azure-cli). -Once logged in try running the credential again. +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 From 4a940436fd986def7eb560fcefd43e45f661d92c Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:44:37 -0700 Subject: [PATCH 08/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 693fcfe341ad..b7999b0f6f03 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -31,7 +31,7 @@ The `DefaultAzureCredential` attempts to retrieve an access token by sequentiall 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 | Troubleshoot Guide | +| Credential Type | Troubleshooting Guide | | ----------------------------- | ------------------------------------------------------------------------------------------------------- | | Environment Credential | [Environment Credential Troubleshoot Guide](#troubleshoot-environment-credential-authentication-issues) | | Managed Identity Credential | [Managed Identity Troubleshoot Guide](#troubleshoot-managed-identity-authentication-issues) | From 02ad9426ee4b6164b9d100a67f2616bd2b8784c0 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:45:20 -0700 Subject: [PATCH 09/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index b7999b0f6f03..ba33881dd15c 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -33,11 +33,11 @@ Follow the configuration instructions in the `Credential unavailable error` sect | Credential Type | Troubleshooting Guide | | ----------------------------- | ------------------------------------------------------------------------------------------------------- | -| Environment Credential | [Environment Credential Troubleshoot Guide](#troubleshoot-environment-credential-authentication-issues) | -| Managed Identity Credential | [Managed Identity Troubleshoot Guide](#troubleshoot-managed-identity-authentication-issues) | -| Visual Studio Code Credential | [Visual Studio Code Troubleshoot Guide](#troubleshoot-visual-studio-code-authentication-issues) | -| Azure CLI Credential | [Azure CLI Troubleshoot Guide](#troubleshoot-azure-cli-authentication-issues) | -| Azure PowerShell Credential | [Azure PowerShell Troubleshoot Guide](#troubleshoot-azure-powershell-authentication-issues) | +| 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 From f49a2399f530f4a6a65f9fe22f9973dd27851266 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:45:26 -0700 Subject: [PATCH 10/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index ba33881dd15c..9cfe9ba16b8d 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -103,8 +103,8 @@ Follow the troubleshooting guidelines below for the respective authentication ty | Authentication Type | Troubleshoot Guide | | ------------------------------- | -------------------------------------------------------------------------------------------------- | -| ClientSecret/ ClientCertificate | [Service Principal Auth Troubleshoot Guide](#troubleshoot-service-principal-authentication-issues) | -| Username Password | [Username Password Auth Troubleshoot Guide](#troubleshoot-username-password-authentication-issues) | +| 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 From 014e341a203a312ee00f9db679bed981c37ee0bc Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:45:37 -0700 Subject: [PATCH 11/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 9cfe9ba16b8d..cb96e8289e8b 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -29,7 +29,7 @@ If you're using app registration to authenticate the service, ensure the app reg 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`: +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 | | ----------------------------- | ------------------------------------------------------------------------------------------------------- | From 10a3dd071fbdcfef1d1bb7b1430a3ae744c5f848 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:45:49 -0700 Subject: [PATCH 12/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index cb96e8289e8b..be2093a7351e 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -101,7 +101,7 @@ To utilize the desired authentication type via `EnvironmentCredential`, ensure t 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 | Troubleshoot Guide | +| 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) | From 646e4f6788cf2fa5dc94969584465f7b1079769f Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:46:20 -0700 Subject: [PATCH 13/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index be2093a7351e..927b25c95a7e 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -114,7 +114,7 @@ The `UsernamePassword` credential works only for users whose two-factor authenti ### Request body must contain the following parameter: 'client_assertion' or 'client_secret' -When you get the error `The request body must contain the following parameter: 'client_assertion' or 'client_secret'`, it happens because of how the AAD app is configured. The AAD app registration seems to be configured as a confidential app. The `UsernamePassword` credential works only with public clients and doesn't support confidential apps. To support confidential apps, use `ClientSecret` or `ClientCertificate` credentials instead. +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: From 1adc093254f5d36d3e008e1f5851fa48d27148a4 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:46:51 -0700 Subject: [PATCH 14/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 927b25c95a7e..0394943abec0 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -118,10 +118,10 @@ The error `The request body must contain the following parameter: 'client_assert To allow public client authentication on your Azure AD tenant: -- Go to the Azure portal. -- Go to the `Authentication` page. -- Scroll to the bottom of this page, and you will see something that says: `Allow public client flows`, and close to that, you will see a `yes` and `no` switch. Make sure this is set to `yes`. - After that, you should not need to specify a client secret to authenticate with this credential. +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 From 412e1160e8f9d81bf9c94de14d5978ddc57c0a62 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:47:05 -0700 Subject: [PATCH 15/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 0394943abec0..74420d3be812 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -76,9 +76,9 @@ To utilize the desired authentication type via `EnvironmentCredential`, ensure t | 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. | +| `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 From 3f3040624f3b6620e920e530f1976e53bb900719 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:47:22 -0700 Subject: [PATCH 16/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 74420d3be812..dfe1c8be8f4f 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -84,9 +84,9 @@ To utilize the desired authentication type via `EnvironmentCredential`, ensure t | 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). | +| `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 From 297ebc2b092168d52257a7a105066c80ca61901b Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:48:25 -0700 Subject: [PATCH 17/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index dfe1c8be8f4f..5b4e9e45dbbd 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -92,9 +92,9 @@ To utilize the desired authentication type via `EnvironmentCredential`, ensure t | 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. | +| `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 From f1a6d6508020f30e6ff0ff0e3faacffb824abd66 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:48:48 -0700 Subject: [PATCH 18/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 5b4e9e45dbbd..9dd3060845b4 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -110,7 +110,7 @@ Follow the troubleshooting guidelines below for the respective authentication ty ### Two-factor authentication required error -The `UsernamePassword` credential 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). +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' From c04b3040133dd8f9271ed6a3812f77fa70036f4d Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:49:25 -0700 Subject: [PATCH 19/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 9dd3060845b4..85df567c5722 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -139,8 +139,7 @@ The tenant ID is the Global Unique Identifier (GUID) that identifies your organi #### Client secret argument -The client secret is the secret string that the application uses to prove its identity when requesting a token. This can also can be referred to as an application 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. +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 From a441c89535d4a859d4cb32dc492bbd22054bf5ca Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:53:13 -0700 Subject: [PATCH 20/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 85df567c5722..f8d51f079b98 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -145,7 +145,7 @@ The client secret is the secret string that the app uses to prove its identity w #### Client certificate argument -The `Client Certificate Credential` accepts `pem` certificates (`pfx` certificates are not supported by JS SDK for now). The certificate needs to be associated with your registered application/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). +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 From bc74222c4e9918a36c77584fb875ce09bd684d61 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:53:27 -0700 Subject: [PATCH 21/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index f8d51f079b98..c18c9d1c42dd 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -176,11 +176,7 @@ The Managed Identity credential runs only on Azure-hosted machines/servers. Ensu The Visual Studio Code credential failed to read the credential details from the cache. -The Visual Studio Code authentication is handled by an integration with the Azure Account extension. -To use this form of authentication, ensure that you have installed the Azure Account extension, -then use View > Command Palette to execute the Azure: Sign In command. 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 application -(either in the debugger or anywhere on the development machine) will use the credential from your sign-in. +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. From d784927b57d1e056376e000483fa79c426f72a52 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:53:48 -0700 Subject: [PATCH 22/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index c18c9d1c42dd..3e3165bbbc19 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -190,7 +190,7 @@ In VS Code, log in to the Azure Account extension via **View** > **Command Palet #### ADFS tenant not supported -The ADFS Tenants are not supported via the Azure Account extension in VS Code currently. +The ADFS tenants aren't currently supported via the Azure Account extension in VS Code. The supported clouds are: | Azure Cloud | Cloud Authority Host | From 2f5a25735a5b19288bb06c3b26ab46b76be0819a Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:54:12 -0700 Subject: [PATCH 23/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index 3e3165bbbc19..ba293d9a9334 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -181,7 +181,7 @@ Visual Studio Code authentication is handled by an integration with the Azure Ac 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 get expired, and the sign in with `DefaultAzureCredential` will begin to fail. In such cases, you have to log out on the VS Code extension (and log in again if you want to continue using it). +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 From dee997b9ee51dc5c37e661fb92e9db505039e852 Mon Sep 17 00:00:00 2001 From: KarishmaGhiya Date: Tue, 12 Oct 2021 18:54:31 -0700 Subject: [PATCH 24/24] Update sdk/identity/identity/Troubleshooting.md Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com> --- sdk/identity/identity/Troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/identity/identity/Troubleshooting.md b/sdk/identity/identity/Troubleshooting.md index ba293d9a9334..b8f53dc8b46f 100644 --- a/sdk/identity/identity/Troubleshooting.md +++ b/sdk/identity/identity/Troubleshooting.md @@ -185,8 +185,7 @@ After using the VS Code extension to authenticate once, if you use the `DefaultA #### 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**. +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