@azure/identity 4.5.0-beta.1 → 4.5.0-beta.2

package/README.md

@@ -213,7 +213,7 @@ For examples of how to use managed identity for authentication, see [the example
 
 ## Cloud configuration
 
-Credentials default to authenticating to the Microsoft Entra endpoint for Azure Public Cloud. To access resources in other clouds, such as Azure Government or a private cloud, configure credentials with the `authorityHost` argument in the constructor. The `AzureAuthorityHosts` interface defines authorities for well-known clouds. For the US Government cloud, you could instantiate a credential this way:
+Credentials default to authenticating to the Microsoft Entra endpoint for Azure Public Cloud. To access resources in other clouds, such as Azure Government or a private cloud, configure credentials with the `authorityHost` argument in the constructor. The [`AzureAuthorityHosts`][authority_hosts] enum defines authorities for well-known clouds. For the US Government cloud, you could instantiate a credential this way:
 
 ```typescript
 import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
@@ -227,6 +227,26 @@ const credential = new ClientSecretCredential(
 );
 ```
 
+As an alternative to specifying the `authorityHost` argument, you can also set the `AZURE_AUTHORITY_HOST` environment variable to the URL of your cloud's authority. This approach is useful when configuring multiple credentials to authenticate to the same cloud or when the deployed environment needs to define the target cloud:
+
+```sh
+AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
+```
+
+The `AzureAuthorityHosts` enum defines authorities for well-known clouds for your convenience; however, if the authority for your cloud isn't listed in `AzureAuthorityHosts`, you may pass any valid authority URL as a string argument. For example:
+
+```typescript
+import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
+const credential = new ClientSecretCredential(
+  "<YOUR_TENANT_ID>",
+  "<YOUR_CLIENT_ID>",
+  "<YOUR_CLIENT_SECRET>",
+  {
+    authorityHost: "https://login.partner.microsoftonline.cn",
+  }
+);
+```
+
 Not all credentials require this configuration. Credentials that authenticate through a development tool, such as `AzureCliCredential`, use that tool's configuration. Similarly, `VisualStudioCodeCredential` accepts an `authorityHost` argument but defaults to the `authorityHost` matching Visual Studio Code's **Azure: Cloud** setting.
 
 ## Credential classes
@@ -369,5 +389,6 @@ If you'd like to contribute to this library, please read the [contributing guide
 [defaultauthflow_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/identity/identity/images/mermaidjs/DefaultAzureCredentialAuthFlow.svg
 [azure_identity_broker]: https://www.npmjs.com/package/@azure/identity-broker
 [azure_identity_broker_readme]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity-broker
+[authority_hosts]: https://learn.microsoft.com/javascript/api/@azure/identity/azureauthorityhosts
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fidentity%2Fidentity%2FREADME.png)

package/dist/index.js

@@ -6,18 +6,18 @@ var logger$m = require('@azure/logger');
 var coreClient = require('@azure/core-client');
 var coreUtil = require('@azure/core-util');
 var coreRestPipeline = require('@azure/core-rest-pipeline');
-var abortController = require('@azure/abort-controller');
 var coreTracing = require('@azure/core-tracing');
 var fs = require('fs');
 var os = require('os');
 var path = require('path');
+var abortController = require('@azure/abort-controller');
 var msalCommon = require('@azure/msal-node');
 var open = require('open');
 var promises = require('fs/promises');
 var child_process = require('child_process');
 var crypto = require('crypto');
-var promises$1 = require('node:fs/promises');
 var node_crypto = require('node:crypto');
+var promises$1 = require('node:fs/promises');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -44,7 +44,7 @@ var child_process__namespace = /*#__PURE__*/_interopNamespaceDefault(child_proce
 /**
  * Current version of the `@azure/identity` package.
  */
-const SDK_VERSION = `4.5.0-beta.1`;
+const SDK_VERSION = `4.5.0-beta.2`;
 /**
  * The default client ID for authentication
  * @internal
@@ -289,8 +289,9 @@ const CredentialUnavailableErrorName = "CredentialUnavailableError";
  * an error that should halt the chain, it's caught and the chain continues
  */
 class CredentialUnavailableError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        // @ts-expect-error - TypeScript does not recognize this until we use ES2022 as the target; however, all our major runtimes do support the `cause` property
+        super(message, options);
         this.name = CredentialUnavailableErrorName;
     }
 }
@@ -305,7 +306,7 @@ const AuthenticationErrorName = "AuthenticationError";
  */
 class AuthenticationError extends Error {
     // eslint-disable-next-line @typescript-eslint/ban-types
-    constructor(statusCode, errorBody) {
+    constructor(statusCode, errorBody, options) {
         let errorResponse = {
             error: "unknown",
             errorDescription: "An unknown error occurred and no additional details are available.",
@@ -323,8 +324,8 @@ class AuthenticationError extends Error {
             catch (e) {
                 if (statusCode === 400) {
                     errorResponse = {
-                        error: "authority_not_found",
-                        errorDescription: "The specified authority URL was not found.",
+                        error: "invalid_request",
+                        errorDescription: `The service indicated that the request was invalid.\n\n${errorBody}`,
                     };
                 }
                 else {
@@ -341,7 +342,9 @@ class AuthenticationError extends Error {
                 errorDescription: "An unknown error occurred and no additional details are available.",
             };
         }
-        super(`${errorResponse.error} Status code: ${statusCode}\nMore details:\n${errorResponse.errorDescription}`);
+        super(`${errorResponse.error} Status code: ${statusCode}\nMore details:\n${errorResponse.errorDescription},`, 
+        // @ts-expect-error - TypeScript does not recognize this until we use ES2022 as the target; however, all our major runtimes do support the `cause` property
+        options);
         this.statusCode = statusCode;
         this.errorResponse = errorResponse;
         // Ensure that this type reports the correct name
@@ -384,7 +387,9 @@ class AuthenticationRequiredError extends Error {
      * Optional parameters. A message can be specified. The {@link GetTokenOptions} of the request can also be specified to more easily associate the error with the received parameters.
      */
     options) {
-        super(options.message);
+        super(options.message, 
+        // @ts-expect-error - TypeScript does not recognize this until we use ES2022 as the target; however, all our major runtimes do support the `cause` property
+        options.cause ? { cause: options.cause } : undefined);
         this.scopes = options.scopes;
         this.getTokenOptions = options.getTokenOptions;
         this.name = "AuthenticationRequiredError";
@@ -674,7 +679,7 @@ class IdentityClient extends coreClient.ServiceClient {
     // Here is a custom layer that allows us to abort requests that go through MSAL,
     // since MSAL doesn't allow us to pass options all the way through.
     generateAbortSignal(correlationId) {
-        const controller = new abortController.AbortController();
+        const controller = new AbortController();
         const controllers = this.abortControllers.get(correlationId) || [];
         controllers.push(controller);
         this.abortControllers.set(correlationId, controllers);
@@ -682,7 +687,7 @@ class IdentityClient extends coreClient.ServiceClient {
         controller.signal.onabort = (...params) => {
             this.abortControllers.set(correlationId, undefined);
             if (existingOnAbort) {
-                existingOnAbort(...params);
+                existingOnAbort.apply(controller.signal, params);
             }
         };
         return controller.signal;
@@ -1524,6 +1529,10 @@ function calculateRegionalAuthority(regionalAuthority) {
 
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
+/**
+ * The default logger used if no logger was passed in by the credential.
+ */
+const msalLogger = credentialLogger("MsalClient");
 /**
  * A call to open(), but mockable
  * @internal
@@ -1531,13 +1540,6 @@ function calculateRegionalAuthority(regionalAuthority) {
 const interactiveBrowserMockable = {
     open,
 };
-
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-/**
- * The default logger used if no logger was passed in by the credential.
- */
-const msalLogger = credentialLogger("MsalClient");
 /**
  * Generates the configuration for MSAL (Microsoft Authentication Library).
  *
@@ -1983,8 +1985,14 @@ class ClientAssertionCredential {
      * @param options - Options for configuring the client which makes the authentication request.
      */
     constructor(tenantId, clientId, getAssertion, options = {}) {
-        if (!tenantId || !clientId || !getAssertion) {
-            throw new Error("ClientAssertionCredential: tenantId, clientId, and clientAssertion are required parameters.");
+        if (!tenantId) {
+            throw new CredentialUnavailableError("ClientAssertionCredential: tenantId is a required parameter.");
+        }
+        if (!clientId) {
+            throw new CredentialUnavailableError("ClientAssertionCredential: clientId is a required parameter.");
+        }
+        if (!getAssertion) {
+            throw new CredentialUnavailableError("ClientAssertionCredential: clientAssertion is a required parameter.");
         }
         this.tenantId = tenantId;
         this.additionallyAllowedTenantIds = resolveAdditionallyAllowedTenantIds(options === null || options === void 0 ? void 0 : options.additionallyAllowedTenants);
@@ -2059,10 +2067,20 @@ class WorkloadIdentityCredential {
         if (tenantId) {
             checkTenantId(logger$g, tenantId);
         }
-        if (clientId && tenantId && this.federatedTokenFilePath) {
-            logger$g.info(`Invoking ClientAssertionCredential with tenant ID: ${tenantId}, clientId: ${workloadIdentityCredentialOptions.clientId} and federated token path: [REDACTED]`);
-            this.client = new ClientAssertionCredential(tenantId, clientId, this.readFileContents.bind(this), options);
+        if (!clientId) {
+            throw new CredentialUnavailableError(`${credentialName$4}: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
+        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot`);
         }
+        if (!tenantId) {
+            throw new CredentialUnavailableError(`${credentialName$4}: is unavailable. tenantId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_TENANT_ID".
+        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot`);
+        }
+        if (!this.federatedTokenFilePath) {
+            throw new CredentialUnavailableError(`${credentialName$4}: is unavailable. federatedTokenFilePath is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_FEDERATED_TOKEN_FILE".
+        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot`);
+        }
+        logger$g.info(`Invoking ClientAssertionCredential with tenant ID: ${tenantId}, clientId: ${workloadIdentityCredentialOptions.clientId} and federated token path: [REDACTED]`);
+        this.client = new ClientAssertionCredential(tenantId, clientId, this.readFileContents.bind(this), options);
     }
     /**
      * Authenticates with Microsoft Entra ID and returns an access token if successful.
@@ -2078,7 +2096,7 @@ class WorkloadIdentityCredential {
       In DefaultAzureCredential and ManagedIdentityCredential, these can be provided as environment variables - 
       "AZURE_TENANT_ID",
       "AZURE_CLIENT_ID",
-      "AZURE_FEDERATED_TOKEN_FILE". See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot  `;
+      "AZURE_FEDERATED_TOKEN_FILE". See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot`;
             logger$g.info(errorMessage);
             throw new CredentialUnavailableError(errorMessage);
         }
@@ -2217,6 +2235,7 @@ class MsalMsiProvider {
                 // We will continue to implement these features in the Identity library.
                 const identitySource = this.managedIdentityApp.getManagedIdentitySource();
                 const isImdsMsi = identitySource === "DefaultToImds" || identitySource === "Imds"; // Neither actually checks that IMDS endpoint is available, just that it's the source the MSAL _would_ try to use.
+                logger$e.getToken.info(`MSAL Identity source: ${identitySource}`);
                 if (isTokenExchangeMsi) {
                     // In the AKS scenario we will use the existing tokenExchangeMsi indefinitely.
                     logger$e.getToken.info("Using the token exchange managed identity.");
@@ -2228,7 +2247,7 @@ class MsalMsiProvider {
                         resourceId: this.resourceId,
                     });
                     if (result === null) {
-                        throw new CredentialUnavailableError("The managed identity endpoint was reached, yet no tokens were received.");
+                        throw new CredentialUnavailableError("Attempted to use the token exchange managed identity, but received a null response.");
                     }
                     return result;
                 }
@@ -2244,7 +2263,7 @@ class MsalMsiProvider {
                         resourceId: this.resourceId,
                     });
                     if (!isAvailable) {
-                        throw new CredentialUnavailableError(`ManagedIdentityCredential: The managed identity endpoint is not available.`);
+                        throw new CredentialUnavailableError(`ManagedIdentityCredential: Attempted to use the IMDS endpoint, but it is not available.`);
                     }
                 }
                 // If we got this far, it means:
@@ -2270,9 +2289,9 @@ class MsalMsiProvider {
                     throw err;
                 }
                 if (isNetworkError(err)) {
-                    throw new CredentialUnavailableError(`ManagedIdentityCredential: Network unreachable. Message: ${err.message}`);
+                    throw new CredentialUnavailableError(`ManagedIdentityCredential: Network unreachable. Message: ${err.message}`, { cause: err });
                 }
-                throw new CredentialUnavailableError(`ManagedIdentityCredential: Authentication failed. Message ${err.message}`);
+                throw new CredentialUnavailableError(`ManagedIdentityCredential: Authentication failed. Message ${err.message}`, { cause: err });
             }
         });
     }
@@ -2289,7 +2308,7 @@ class MsalMsiProvider {
             });
         };
         if (!msalToken) {
-            throw createError("No response");
+            throw createError("No response.");
         }
         if (!msalToken.expiresOn) {
             throw createError(`Response had no "expiresOn" property.`);
@@ -2848,33 +2867,45 @@ class AzurePowerShellCredential {
                 commandStack.shift();
                 continue;
             }
-            let tenantSection = "";
-            if (tenantId) {
-                tenantSection = `-TenantId "${tenantId}"`;
-            }
             const results = await runCommands([
                 [
                     powerShellCommand,
                     "-NoProfile",
                     "-NonInteractive",
                     "-Command",
-                    "Import-Module Az.Accounts -MinimumVersion 2.2.0 -PassThru",
-                ],
-                [
-                    powerShellCommand,
-                    "-NoProfile",
-                    "-NonInteractive",
-                    "-Command",
-                    `Get-AzAccessToken ${tenantSection} -ResourceUrl "${resource}" | ConvertTo-Json`,
+                    `
+          $tenantId = "${tenantId !== null && tenantId !== void 0 ? tenantId : ""}"
+          $m = Import-Module Az.Accounts -MinimumVersion 2.2.0 -PassThru
+          $useSecureString = $m.Version -ge [version]'2.17.0'
+
+          $params = @{
+            ResourceUrl = "${resource}"
+          }
+
+          if ($tenantId.Length -gt 0) {
+            $params["TenantId"] = $tenantId
+          }
+
+          if ($useSecureString) {
+            $params["AsSecureString"] = $true
+          }
+
+          $token = Get-AzAccessToken @params
+
+          $result = New-Object -TypeName PSObject
+          $result | Add-Member -MemberType NoteProperty -Name ExpiresOn -Value $token.ExpiresOn
+          if ($useSecureString) {
+            $result | Add-Member -MemberType NoteProperty -Name Token -Value (ConvertFrom-SecureString -AsPlainText $token.Token)
+          } else {
+            $result | Add-Member -MemberType NoteProperty -Name Token -Value $token.Token
+          }
+
+          Write-Output (ConvertTo-Json $result)
+          `,
                 ],
             ]);
-            const result = results[1];
-            try {
-                return JSON.parse(result);
-            }
-            catch (e) {
-                throw new Error(`Unable to parse the output of PowerShell. Received output: ${result}`);
-            }
+            const result = results[0];
+            return parseJsonToken(result);
         }
         throw new Error(`Unable to execute PowerShell. Ensure that it is installed in your system`);
     }
@@ -2921,6 +2952,38 @@ class AzurePowerShellCredential {
         });
     }
 }
+/**
+ *
+ * @internal
+ */
+async function parseJsonToken(result) {
+    const jsonRegex = /{[^{}]*}/g;
+    const matches = result.match(jsonRegex);
+    let resultWithoutToken = result;
+    if (matches) {
+        try {
+            for (const item of matches) {
+                try {
+                    const jsonContent = JSON.parse(item);
+                    if (jsonContent === null || jsonContent === void 0 ? void 0 : jsonContent.Token) {
+                        resultWithoutToken = resultWithoutToken.replace(item, "");
+                        if (resultWithoutToken) {
+                            logger$b.getToken.warning(resultWithoutToken);
+                        }
+                        return jsonContent;
+                    }
+                }
+                catch (e) {
+                    continue;
+                }
+            }
+        }
+        catch (e) {
+            throw new Error(`Unable to parse the output of PowerShell. Received output: ${result}`);
+        }
+    }
+    throw new Error(`No access token found in the output. Received output: ${result}`);
+}
 
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
@@ -3053,7 +3116,8 @@ class ClientCertificateCredential {
         });
     }
     async buildClientCertificate() {
-        const parts = await this.parseCertificate();
+        var _a;
+        const parts = await parseCertificate(this.certificateConfiguration, (_a = this.sendCertificateChain) !== null && _a !== void 0 ? _a : false);
         let privateKey;
         if (this.certificateConfiguration.certificatePassword !== undefined) {
             privateKey = crypto.createPrivateKey({
@@ -3076,34 +3140,41 @@ class ClientCertificateCredential {
             x5c: parts.x5c,
         };
     }
-    async parseCertificate() {
-        const certificate = this.certificateConfiguration.certificate;
-        const certificatePath = this.certificateConfiguration.certificatePath;
-        const certificateContents = certificate || (await promises.readFile(certificatePath, "utf8"));
-        const x5c = this.sendCertificateChain ? certificateContents : undefined;
-        const certificatePattern = /(-+BEGIN CERTIFICATE-+)(\n\r?|\r\n?)([A-Za-z0-9+/\n\r]+=*)(\n\r?|\r\n?)(-+END CERTIFICATE-+)/g;
-        const publicKeys = [];
-        // Match all possible certificates, in the order they are in the file. These will form the chain that is used for x5c
-        let match;
-        do {
-            match = certificatePattern.exec(certificateContents);
-            if (match) {
-                publicKeys.push(match[3]);
-            }
-        } while (match);
-        if (publicKeys.length === 0) {
-            throw new Error("The file at the specified path does not contain a PEM-encoded certificate.");
+}
+/**
+ * Parses a certificate into its relevant parts
+ *
+ * @param certificateConfiguration - The certificate contents or path to the certificate
+ * @param sendCertificateChain - true if the entire certificate chain should be sent for SNI, false otherwise
+ * @returns The parsed certificate parts and the certificate contents
+ */
+async function parseCertificate(certificateConfiguration, sendCertificateChain) {
+    const certificate = certificateConfiguration.certificate;
+    const certificatePath = certificateConfiguration.certificatePath;
+    const certificateContents = certificate || (await promises.readFile(certificatePath, "utf8"));
+    const x5c = sendCertificateChain ? certificateContents : undefined;
+    const certificatePattern = /(-+BEGIN CERTIFICATE-+)(\n\r?|\r\n?)([A-Za-z0-9+/\n\r]+=*)(\n\r?|\r\n?)(-+END CERTIFICATE-+)/g;
+    const publicKeys = [];
+    // Match all possible certificates, in the order they are in the file. These will form the chain that is used for x5c
+    let match;
+    do {
+        match = certificatePattern.exec(certificateContents);
+        if (match) {
+            publicKeys.push(match[3]);
         }
-        const thumbprint = crypto.createHash("sha1")
-            .update(Buffer.from(publicKeys[0], "base64"))
-            .digest("hex")
-            .toUpperCase();
-        return {
-            certificateContents,
-            thumbprint,
-            x5c,
-        };
-    }
+    } while (match);
+    if (publicKeys.length === 0) {
+        throw new Error("The file at the specified path does not contain a PEM-encoded certificate.");
+    }
+    const thumbprint = crypto.createHash("sha1")
+        .update(Buffer.from(publicKeys[0], "base64"))
+        .digest("hex")
+        .toUpperCase();
+    return {
+        certificateContents,
+        thumbprint,
+        x5c,
+    };
 }
 
 // Copyright (c) Microsoft Corporation.
@@ -3129,8 +3200,14 @@ class ClientSecretCredential {
      * @param options - Options for configuring the client which makes the authentication request.
      */
     constructor(tenantId, clientId, clientSecret, options = {}) {
-        if (!tenantId || !clientId || !clientSecret) {
-            throw new Error("ClientSecretCredential: tenantId, clientId, and clientSecret are required parameters. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.");
+        if (!tenantId) {
+            throw new CredentialUnavailableError("ClientSecretCredential: tenantId is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.");
+        }
+        if (!clientId) {
+            throw new CredentialUnavailableError("ClientSecretCredential: clientId is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.");
+        }
+        if (!clientSecret) {
+            throw new CredentialUnavailableError("ClientSecretCredential: clientSecret is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.");
         }
         this.clientSecret = clientSecret;
         this.tenantId = tenantId;
@@ -3176,8 +3253,17 @@ class UsernamePasswordCredential {
      * @param options - Options for configuring the client which makes the authentication request.
      */
     constructor(tenantId, clientId, username, password, options = {}) {
-        if (!tenantId || !clientId || !username || !password) {
-            throw new Error("UsernamePasswordCredential: tenantId, clientId, username and password are required parameters. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot.");
+        if (!tenantId) {
+            throw new CredentialUnavailableError("UsernamePasswordCredential: tenantId is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot.");
+        }
+        if (!clientId) {
+            throw new CredentialUnavailableError("UsernamePasswordCredential: clientId is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot.");
+        }
+        if (!username) {
+            throw new CredentialUnavailableError("UsernamePasswordCredential: username is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot.");
+        }
+        if (!password) {
+            throw new CredentialUnavailableError("UsernamePasswordCredential: password is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/usernamepasswordcredential/troubleshoot.");
         }
         this.tenantId = tenantId;
         this.additionallyAllowedTenantIds = resolveAdditionallyAllowedTenantIds(options === null || options === void 0 ? void 0 : options.additionallyAllowedTenants);
@@ -3224,6 +3310,7 @@ const AllSupportedEnvironmentVariables = [
     "AZURE_USERNAME",
     "AZURE_PASSWORD",
     "AZURE_ADDITIONALLY_ALLOWED_TENANTS",
+    "AZURE_CLIENT_SEND_CERTIFICATE_CHAIN",
 ];
 function getAdditionallyAllowedTenants() {
     var _a;
@@ -3232,6 +3319,13 @@ function getAdditionallyAllowedTenants() {
 }
 const credentialName$2 = "EnvironmentCredential";
 const logger$6 = credentialLogger(credentialName$2);
+function getSendCertificateChain() {
+    var _a;
+    const sendCertificateChain = ((_a = process.env.AZURE_CLIENT_SEND_CERTIFICATE_CHAIN) !== null && _a !== void 0 ? _a : "").toLowerCase();
+    const result = sendCertificateChain === "true" || sendCertificateChain === "1";
+    logger$6.verbose(`AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: ${process.env.AZURE_CLIENT_SEND_CERTIFICATE_CHAIN}; sendCertificateChain: ${result}`);
+    return result;
+}
 /**
  * Enables authentication to Microsoft Entra ID using a client secret or certificate, or as a user
  * with a username and password.
@@ -3251,6 +3345,7 @@ class EnvironmentCredential {
      * - `AZURE_CLIENT_SECRET`: A client secret that was generated for the App Registration.
      * - `AZURE_CLIENT_CERTIFICATE_PATH`: The path to a PEM certificate to use during the authentication, instead of the client secret.
      * - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the certificate file.
+     * - `AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`: (optional) indicates that the certificate chain should be set in x5c header to support subject name / issuer based authentication.
      *
      * Alternatively, users can provide environment variables for username and password authentication:
      * - `AZURE_USERNAME`: Username to authenticate with.
@@ -3268,7 +3363,8 @@ class EnvironmentCredential {
         logger$6.info(`Found the following environment variables: ${assigned}`);
         const tenantId = process.env.AZURE_TENANT_ID, clientId = process.env.AZURE_CLIENT_ID, clientSecret = process.env.AZURE_CLIENT_SECRET;
         const additionallyAllowedTenantIds = getAdditionallyAllowedTenants();
-        const newOptions = Object.assign(Object.assign({}, options), { additionallyAllowedTenantIds });
+        const sendCertificateChain = getSendCertificateChain();
+        const newOptions = Object.assign(Object.assign({}, options), { additionallyAllowedTenantIds, sendCertificateChain });
         if (tenantId) {
             checkTenantId(logger$6, tenantId);
         }
@@ -3529,7 +3625,7 @@ class InteractiveBrowserCredential {
      * Authenticates with Microsoft Entra ID and returns an access token if successful.
      * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
      *
-     * If the token can't be retrieved silently, this method will require user interaction to retrieve the token.
+     * If the token can't be retrieved silently, this method will always generate a challenge for the user.
      *
      * On Node.js, this credential has [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) enabled by default.
      * PKCE is a security feature that mitigates authentication code interception attacks.
@@ -3615,7 +3711,7 @@ class DeviceCodeCredential {
      * Authenticates with Microsoft Entra ID and returns an access token if successful.
      * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
      *
-     * If the token can't be retrieved silently, this method will require user interaction to retrieve the token.
+     * If the token can't be retrieved silently, this method will always generate a challenge for the user.
      *
      * @param scopes - The list of scopes for which the token will have access.
      * @param options - The options used to configure any requests this
@@ -3649,8 +3745,17 @@ class AzurePipelinesCredential {
      * @param options - The identity client options to use for authentication.
      */
     constructor(tenantId, clientId, serviceConnectionId, systemAccessToken, options) {
-        if (!clientId || !tenantId || !serviceConnectionId || !systemAccessToken) {
-            throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. tenantId, clientId, serviceConnectionId, and systemAccessToken are required parameters.`);
+        if (!clientId) {
+            throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. clientId is a required parameter.`);
+        }
+        if (!tenantId) {
+            throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. tenantId is a required parameter.`);
+        }
+        if (!serviceConnectionId) {
+            throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. serviceConnectionId is a required parameter.`);
+        }
+        if (!systemAccessToken) {
+            throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. systemAccessToken is a required parameter.`);
         }
         this.identityClient = new IdentityClient(options);
         checkTenantId(logger$2, tenantId);
@@ -3703,30 +3808,45 @@ class AzurePipelinesCredential {
             }),
         });
         const response = await this.identityClient.sendRequest(request);
-        const text = response.bodyAsText;
-        if (!text) {
-            logger$2.error(`${credentialName$1}: Authenticated Failed. Received null token from OIDC request. Response status- ${response.status}. Complete response - ${JSON.stringify(response)}`);
-            throw new AuthenticationError(response.status, `${credentialName$1}: Authenticated Failed. Received null token from OIDC request. Response status- ${response.status}. Complete response - ${JSON.stringify(response)}`);
+        return handleOidcResponse(response);
+    }
+}
+function handleOidcResponse(response) {
+    const text = response.bodyAsText;
+    if (!text) {
+        logger$2.error(`${credentialName$1}: Authentication Failed. Received null token from OIDC request. Response status- ${response.status}. Complete response - ${JSON.stringify(response)}`);
+        throw new AuthenticationError(response.status, {
+            error: `${credentialName$1}: Authentication Failed. Received null token from OIDC request.`,
+            error_description: `${JSON.stringify(response)}. See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/azurepipelinescredential/troubleshoot`,
+        });
+    }
+    try {
+        const result = JSON.parse(text);
+        if (result === null || result === void 0 ? void 0 : result.oidcToken) {
+            return result.oidcToken;
         }
-        try {
-            const result = JSON.parse(text);
-            if (result === null || result === void 0 ? void 0 : result.oidcToken) {
-                return result.oidcToken;
-            }
-            else {
-                let errorMessage = `${credentialName$1}: Authentication Failed. oidcToken field not detected in the response.`;
-                if (response.status !== 200) {
-                    errorMessage += `Response = ${JSON.stringify(result)}`;
-                }
-                logger$2.error(errorMessage);
-                throw new AuthenticationError(response.status, errorMessage);
+        else {
+            const errorMessage = `${credentialName$1}: Authentication Failed. oidcToken field not detected in the response.`;
+            let errorDescription = ``;
+            if (response.status !== 200) {
+                errorDescription = `Complete response - ${JSON.stringify(result)}. See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/azurepipelinescredential/troubleshoot`;
             }
+            logger$2.error(errorMessage);
+            logger$2.error(errorDescription);
+            throw new AuthenticationError(response.status, {
+                error: errorMessage,
+                error_description: errorDescription,
+            });
         }
-        catch (e) {
-            logger$2.error(e.message);
-            logger$2.error(`${credentialName$1}: Authentication Failed. oidcToken field not detected in the response. Response = ${text}`);
-            throw new AuthenticationError(response.status, `${credentialName$1}: Authentication Failed. oidcToken field not detected in the response. Response = ${text}`);
-        }
+    }
+    catch (e) {
+        const errorDetails = `${credentialName$1}: Authentication Failed. oidcToken field not detected in the response.`;
+        logger$2.error(`Response from service = ${text} and error message = ${e.message}`);
+        logger$2.error(errorDetails);
+        throw new AuthenticationError(response.status, {
+            error: errorDetails,
+            error_description: `Response = ${text}. See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/azurepipelinescredential/troubleshoot`,
+        });
     }
 }
 
@@ -3797,11 +3917,17 @@ class OnBehalfOfCredential {
         const { certificatePath, sendCertificateChain } = options;
         const { getAssertion } = options;
         const { tenantId, clientId, userAssertionToken, additionallyAllowedTenants: additionallyAllowedTenantIds, } = options;
-        if (!tenantId ||
-            !clientId ||
-            !(clientSecret || certificatePath || getAssertion) ||
-            !userAssertionToken) {
-            throw new Error(`${credentialName}: tenantId, clientId, clientSecret (or certificatePath or getAssertion) and userAssertionToken are required parameters.`);
+        if (!tenantId) {
+            throw new CredentialUnavailableError(`${credentialName}: tenantId is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.`);
+        }
+        if (!clientId) {
+            throw new CredentialUnavailableError(`${credentialName}: clientId is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.`);
+        }
+        if (!clientSecret && !certificatePath && !getAssertion) {
+            throw new CredentialUnavailableError(`${credentialName}: You must provide one of clientSecret, certificatePath, or a getAssertion callback but none were provided. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.`);
+        }
+        if (!userAssertionToken) {
+            throw new CredentialUnavailableError(`${credentialName}: userAssertionToken is a required parameter. To troubleshoot, visit https://aka.ms/azsdk/js/identity/serviceprincipalauthentication/troubleshoot.`);
         }
         this.certificatePath = certificatePath;
         this.clientSecret = clientSecret;