@azure/identity 3.2.0-beta.2 → 3.2.1

package/README.md

@@ -68,9 +68,9 @@ While we recommend using managed identity or service principal authentication in
 
 Developers coding outside of an IDE can also use the [Azure Developer CLI][azure_developer_cli] to authenticate. Applications using the `DefaultAzureCredential` or the `AzureDeveloperCliCredential` can then use this account to authenticate calls in their application when running locally.
 
-To authenticate with the [Azure Developer CLI][azure_developer_cli], users can run the command `azd login`. For users running on a system with a default web browser, the Azure Developer CLI will launch the browser to authenticate the user.
+To authenticate with the [Azure Developer CLI][azure_developer_cli], users can run the command `azd auth login`. For users running on a system with a default web browser, the Azure Developer CLI will launch the browser to authenticate the user.
 
-For systems without a default web browser, the `azd login --use-device-code` command will use the device code authentication flow.
+For systems without a default web browser, the `azd auth login --use-device-code` command will use the device code authentication flow.
 
 #### Authenticate via the Azure CLI
 
@@ -133,7 +133,7 @@ If used from Node.js, the `DefaultAzureCredential` will attempt to authenticate
 1. **Environment** - The `DefaultAzureCredential` will read account information specified via [environment variables](#environment-variables) and use it to authenticate.
 1. **Workload Identity** - If the application is deployed to Azure Kubernetes Service with Managed Identity enabled, `DefaultAzureCredential` will authenticate with it.
 1. **Managed Identity** - If the application is deployed to an Azure host with Managed Identity enabled, the `DefaultAzureCredential` will authenticate with that account.
-1. **Azure Developer CLI** - If the developer has authenticated an account via the Azure Developer CLI `azd login` command, the `DefaultAzureCredential` will authenticate with that account.
+1. **Azure Developer CLI** - If the developer has authenticated an account via the Azure Developer CLI `azd auth login` command, the `DefaultAzureCredential` will authenticate with that account.
 1. **Azure CLI** - If the developer has authenticated an account via the Azure CLI `az login` command, the `DefaultAzureCredential` will authenticate with that account.
 1. **Azure PowerShell** - If the developer has authenticated using the Azure PowerShell module `Connect-AzAccount` command, the `DefaultAzureCredential` will authenticate with that account.
 
@@ -298,6 +298,14 @@ Not all credentials require this configuration. Credentials that authenticate th
 
 Configuration is attempted in the above order. For example, if values for a client secret and certificate are both present, the client secret will be used.
 
+## Token caching
+Token caching is a feature provided by the Azure Identity library that allows apps to:
+- Cache tokens in memory (default) and on disk (opt-in).
+- Improve resilience and performance.
+- Reduce the number of requests made to Azure AD to obtain access tokens.
+
+The Azure Identity library offers both in-memory and persistent disk caching. For more details, see the [token caching documentation](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/TOKEN_CACHING.md).
+
 ## Troubleshooting
 
 ### Error handling

package/dist/index.js

@@ -257,7 +257,7 @@ function credentialLogger(title, log = logger$n) {
 /**
  * Current version of the `@azure/identity` package.
  */
-const SDK_VERSION = `3.2.0-beta.2`;
+const SDK_VERSION = `3.2.1`;
 /**
  * The default client ID for authentication
  * @internal
@@ -1970,9 +1970,18 @@ const SupportedWorkloadEnvironmentVariables = [
 ];
 const logger$g = credentialLogger(credentialName$3);
 /**
- * WorkloadIdentityCredential supports Azure workload identity authentication on Kubernetes.
- * Refer to <a href="https://learn.microsoft.com/azure/aks/workload-identity-overview">Azure Active Directory Workload Identity</a>
- * for more information.
+ * Workload Identity authentication is a feature in Azure that allows applications running on virtual machines (VMs)
+ * to access other Azure resources without the need for a service principal or managed identity. With Workload Identity
+ * authentication, applications authenticate themselves using their own identity, rather than using a shared service
+ * principal or managed identity. Under the hood, Workload Identity authentication uses the concept of Service Account
+ * Credentials (SACs), which are automatically created by Azure and stored securely in the VM. By using Workload
+ * Identity authentication, you can avoid the need to manage and rotate service principals or managed identities for
+ * each application on each VM. Additionally, because SACs are created automatically and managed by Azure, you don't
+ * need to worry about storing and securing sensitive credentials themselves.
+ * The WorkloadIdentityCredential supports Azure workload identity authentication on Azure Kubernetes and acquires
+ * a token using the SACs available in the Azure Kubernetes environment.
+ * Refer to <a href="https://learn.microsoft.com/azure/aks/workload-identity-overview">Azure Active Directory
+ * Workload Identity</a> for more information.
  */
 class WorkloadIdentityCredential {
     /**
@@ -1986,12 +1995,11 @@ class WorkloadIdentityCredential {
         // Logging environment variables for error details
         const assignedEnv = processEnvVars(SupportedWorkloadEnvironmentVariables).assigned.join(", ");
         logger$g.info(`Found the following environment variables: ${assignedEnv}`);
-        const workloadIdentityCredentialOptions = options;
+        const workloadIdentityCredentialOptions = options !== null && options !== void 0 ? options : {};
         const tenantId = workloadIdentityCredentialOptions.tenantId || process.env.AZURE_TENANT_ID;
         const clientId = workloadIdentityCredentialOptions.clientId || process.env.AZURE_CLIENT_ID;
         this.federatedTokenFilePath =
-            workloadIdentityCredentialOptions.federatedTokenFilePath ||
-                process.env.AZURE_FEDERATED_TOKEN_FILE;
+            workloadIdentityCredentialOptions.tokenFilePath || process.env.AZURE_FEDERATED_TOKEN_FILE;
         if (tenantId) {
             checkTenantId(logger$g, tenantId);
         }
@@ -2014,7 +2022,7 @@ class WorkloadIdentityCredential {
       In DefaultAzureCredential and ManagedIdentityCredential, these can be provided as environment variables - 
       "AZURE_TENANT_ID",
       "AZURE_CLIENT_ID",
-      "AZURE_FEDERATED_TOKEN_FILE"`;
+      "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);
         }
@@ -2066,7 +2074,7 @@ function tokenExchangeMsi() {
         async getToken(configuration, getTokenOptions = {}) {
             const { scopes, clientId } = configuration;
             const identityClientTokenCredentialOptions = {};
-            const workloadIdentityCredential = new WorkloadIdentityCredential(Object.assign(Object.assign({ clientId, tenantId: process.env.AZURE_TENANT_ID, federatedTokenFilePath: process.env.AZURE_FEDERATED_TOKEN_FILE }, identityClientTokenCredentialOptions), { disableInstanceDiscovery: true }));
+            const workloadIdentityCredential = new WorkloadIdentityCredential(Object.assign(Object.assign({ clientId, tenantId: process.env.AZURE_TENANT_ID, tokenFilePath: process.env.AZURE_FEDERATED_TOKEN_FILE }, identityClientTokenCredentialOptions), { disableInstanceDiscovery: true }));
             const token = await workloadIdentityCredential.getToken(scopes, getTokenOptions);
             return token;
         },
@@ -2893,14 +2901,18 @@ class ChainedTokenCredential {
      *                `TokenCredential` implementation might make.
      */
     async getToken(scopes, options = {}) {
+        const { token } = await this.getTokenInternal(scopes, options);
+        return token;
+    }
+    async getTokenInternal(scopes, options = {}) {
         let token = null;
-        let successfulCredentialName = "";
+        let successfulCredential;
         const errors = [];
         return tracingClient.withSpan("ChainedTokenCredential.getToken", options, async (updatedOptions) => {
             for (let i = 0; i < this._sources.length && token === null; i++) {
                 try {
                     token = await this._sources[i].getToken(scopes, updatedOptions);
-                    successfulCredentialName = this._sources[i].constructor.name;
+                    successfulCredential = this._sources[i];
                 }
                 catch (err) {
                     if (err.name === "CredentialUnavailableError" ||
@@ -2918,11 +2930,11 @@ class ChainedTokenCredential {
                 logger$9.getToken.info(formatError(scopes, err));
                 throw err;
             }
-            logger$9.getToken.info(`Result for ${successfulCredentialName}: ${formatSuccess(scopes)}`);
+            logger$9.getToken.info(`Result for ${successfulCredential.constructor.name}: ${formatSuccess(scopes)}`);
             if (token === null) {
                 throw new CredentialUnavailableError("Failed to retrieve a valid token");
             }
-            return token;
+            return { token, successfulCredential };
         });
     }
 }
@@ -3415,17 +3427,36 @@ const developerCliCredentialInternals = {
 };
 const logger$4 = credentialLogger("AzureDeveloperCliCredential");
 /**
- * This credential will use the currently logged-in user login information
- * via the Azure Developer CLI ('az') commandline tool.
- * To do so, it will read the user access token and expire time
- * with Azure Developer CLI command "azd auth token".
+ * Azure Developer CLI is a command-line interface tool that allows developers to create, manage, and deploy
+ * resources in Azure. It's built on top of the Azure CLI and provides additional functionality specific
+ * to Azure developers. It allows users to authenticate as a user and/or a service principal against
+ * <a href="https://learn.microsoft.com/azure/active-directory/fundamentals/">Azure Active Directory (Azure AD)
+ * </a>. The AzureDeveloperCliCredential authenticates in a development environment and acquires a token on behalf of
+ * the logged-in user or service principal in the Azure Developer CLI. It acts as the Azure Developer CLI logged in user or
+ * service principal and executes an Azure CLI command underneath to authenticate the application against
+ * Azure Active Directory.
+ *
+ * <h2> Configure AzureDeveloperCliCredential </h2>
+ *
+ * To use this credential, the developer needs to authenticate locally in Azure Developer CLI using one of the
+ * commands below:
+ *
+ * <ol>
+ *     <li>Run "azd auth login" in Azure Developer CLI to authenticate interactively as a user.</li>
+ *     <li>Run "azd auth login --client-id clientID --client-secret clientSecret
+ *     --tenant-id tenantID" to authenticate as a service principal.</li>
+ * </ol>
+ *
+ * You may need to repeat this process after a certain time period, depending on the refresh token validity in your
+ * organization. Generally, the refresh token validity period is a few weeks to a few months.
+ * AzureDeveloperCliCredential will prompt you to sign in again.
  */
 class AzureDeveloperCliCredential {
     /**
      * Creates an instance of the {@link AzureDeveloperCliCredential}.
      *
      * To use this credential, ensure that you have already logged
-     * in via the 'azd' tool using the command "azd login" from the commandline.
+     * in via the 'azd' tool using the command "azd auth login" from the commandline.
      *
      * @param options - Options, to optionally allow multi-tenant requests.
      */
@@ -3453,19 +3484,20 @@ class AzureDeveloperCliCredential {
         }
         logger$4.getToken.info(`Using the scopes ${scopes}`);
         return tracingClient.withSpan(`${this.constructor.name}.getToken`, options, async () => {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             try {
                 const obj = await developerCliCredentialInternals.getAzdAccessToken(scopeList, tenantId, this.timeout);
-                const isNotLoggedInError = (_a = obj.stderr) === null || _a === void 0 ? void 0 : _a.match("not logged in, run `azd login` to login");
-                const isNotInstallError = ((_b = obj.stderr) === null || _b === void 0 ? void 0 : _b.match("azd:(.*)not found")) ||
-                    ((_c = obj.stderr) === null || _c === void 0 ? void 0 : _c.startsWith("'azd' is not recognized"));
+                const isNotLoggedInError = ((_a = obj.stderr) === null || _a === void 0 ? void 0 : _a.match("not logged in, run `azd login` to login")) ||
+                    ((_b = obj.stderr) === null || _b === void 0 ? void 0 : _b.match("not logged in, run `azd auth login` to login"));
+                const isNotInstallError = ((_c = obj.stderr) === null || _c === void 0 ? void 0 : _c.match("azd:(.*)not found")) ||
+                    ((_d = obj.stderr) === null || _d === void 0 ? void 0 : _d.startsWith("'azd' is not recognized"));
                 if (isNotInstallError || (obj.error && obj.error.code === "ENOENT")) {
-                    const error = new CredentialUnavailableError("Azure Developer CLI could not be found. Please visit https://aka.ms/azure-dev for installation instructions and then, once installed, authenticate to your Azure account using 'azd login'.");
+                    const error = new CredentialUnavailableError("Azure Developer CLI couldn't be found. To mitigate this issue, see the troubleshooting guidelines at https://aka.ms/azsdk/js/identity/azdevclicredential/troubleshoot.");
                     logger$4.getToken.info(formatError(scopes, error));
                     throw error;
                 }
                 if (isNotLoggedInError) {
-                    const error = new CredentialUnavailableError("Please run 'azd login' from a command prompt to authenticate before using this credential.");
+                    const error = new CredentialUnavailableError("Please run 'azd auth login' from a command prompt to authenticate before using this credential. For more information, see the troubleshooting guidelines at https://aka.ms/azsdk/js/identity/azdevclicredential/troubleshoot.");
                     logger$4.getToken.info(formatError(scopes, error));
                     throw error;
                 }
@@ -3546,7 +3578,7 @@ class DefaultWorkloadIdentityCredential extends WorkloadIdentityCredential {
         const workloadFile = process.env.AZURE_FEDERATED_TOKEN_FILE;
         const tenantId = (_c = options === null || options === void 0 ? void 0 : options.tenantId) !== null && _c !== void 0 ? _c : process.env.AZURE_TENANT_ID;
         if (workloadFile && workloadIdentityClientId) {
-            const workloadIdentityCredentialOptions = Object.assign(Object.assign({}, options), { tenantId, clientId: workloadIdentityClientId, federatedTokenFilePath: workloadFile });
+            const workloadIdentityCredentialOptions = Object.assign(Object.assign({}, options), { tenantId, clientId: workloadIdentityClientId, tokenFilePath: workloadFile });
             super(workloadIdentityCredentialOptions);
         }
         else if (tenantId) {
@@ -3560,17 +3592,17 @@ class DefaultWorkloadIdentityCredential extends WorkloadIdentityCredential {
 }
 class DefaultAzureDeveloperCliCredential extends AzureDeveloperCliCredential {
     constructor(options) {
-        super(Object.assign({ processTimeoutInMs: options === null || options === void 0 ? void 0 : options.developerCredentialTimeOutInMs }, options));
+        super(Object.assign({ processTimeoutInMs: options === null || options === void 0 ? void 0 : options.processTimeoutInMs }, options));
     }
 }
 class DefaultAzureCliCredential extends AzureCliCredential {
     constructor(options) {
-        super(Object.assign({ processTimeoutInMs: options === null || options === void 0 ? void 0 : options.developerCredentialTimeOutInMs }, options));
+        super(Object.assign({ processTimeoutInMs: options === null || options === void 0 ? void 0 : options.processTimeoutInMs }, options));
     }
 }
 class DefaultAzurePowershellCredential extends AzurePowerShellCredential {
     constructor(options) {
-        super(Object.assign({ processTimeoutInMs: options === null || options === void 0 ? void 0 : options.developerCredentialTimeOutInMs }, options));
+        super(Object.assign({ processTimeoutInMs: options === null || options === void 0 ? void 0 : options.processTimeoutInMs }, options));
     }
 }
 const defaultCredentials = [