@azure/identity 4.5.0-beta.3 → 4.5.0

package/README.md

@@ -47,7 +47,12 @@ Most of the credential types offered by `@azure/identity` use the [Microsoft Aut
 
 The `@azure/identity` credential types are implementations of [@azure/core-auth](https://www.npmjs.com/package/@azure/core-auth)'s `TokenCredential` class. In principle, any object with a `getToken` method that satisfies `getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>` works as a `TokenCredential`. This means developers can write their own credential types to support authentication cases not covered by `@azure/identity`. To learn more, see [Custom Credentials](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#custom-credentials).
 
-Though our credential types support many advanced cases, developers may want full control of the authentication protocol. For that use case, we recommend using [Microsoft Authentication Library for JavaScript (MSAL.js)](https://github.com/AzureAD/microsoft-authentication-library-for-js) directly. You can read more through the following links:
+Though our credential types support many advanced scenarios, developers may want to use [Microsoft Authentication Library for JavaScript (MSAL.js)](https://github.com/AzureAD/microsoft-authentication-library-for-js) directly instead. Consider using MSAL.js in the following scenarios:
+
+- Developers who want full control of the authentication protocol and its configuration.
+- Our credential types are designed to be used with Azure SDK clients with intelligent caching and token refreshing handled at the core HTTP layer. If you find yourself having to use `getToken` directly, you may benefit from using MSAL.js for more control over the authentication flow and token caching.
+
+You can read more through the following links:
 
 - We portray some advanced use cases of `@azure/identity` on the [Azure Identity Examples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md) page.
   - There, we specifically have an [Advanced Examples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#advanced-examples) section.
@@ -117,20 +122,7 @@ See [Credential Classes](#credential-classes).
 
 ### DefaultAzureCredential
 
-`DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in Azure. This is because `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed with credentials used to authenticate in a development environment.
-
-> Note: `DefaultAzureCredential` is intended to simplify getting started with the SDK by handling common scenarios with reasonable default behaviors. Developers who want more control or whose scenario isn't served by the default settings should use other credential types.
-
-If used from Node.js, `DefaultAzureCredential` attempts to authenticate via the following mechanisms in order:
-
-![DefaultAzureCredential authentication flow][defaultauthflow_image]
-
-1. **Environment** - `DefaultAzureCredential` reads account information specified via [environment variables](#environment-variables) and uses it to authenticate.
-1. **Workload Identity** - If the application is deployed to Azure Kubernetes Service with Managed Identity enabled, `DefaultAzureCredential` authenticates with it.
-1. **Managed Identity** - If the application is deployed to an Azure host with Managed Identity enabled, `DefaultAzureCredential` authenticates with that account.
-1. **Azure CLI** - If the developer authenticated an account via the Azure CLI `az login` command, `DefaultAzureCredential` authenticates with that account.
-1. **Azure PowerShell** - If the developer authenticated using the Azure PowerShell module `Connect-AzAccount` command, `DefaultAzureCredential` authenticates with that account.
-1. **Azure Developer CLI** - If the developer authenticated an account via the Azure Developer CLI `azd auth login` command, `DefaultAzureCredential` authenticates with that account.
+`DefaultAzureCredential` simplifies authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development. For more information, see [DefaultAzureCredential overview](https://aka.ms/azsdk/js/identity/credential-chains#use-defaultazurecredential-for-flexibility).
 
 #### Continuation policy
 
@@ -157,19 +149,14 @@ You can find more examples of using various credentials in [Azure Identity Examp
 
 This example demonstrates authenticating the `KeyClient` from the [@azure/keyvault-keys](https://www.npmjs.com/package/@azure/keyvault-keys) client library using `DefaultAzureCredential`.
 
-```javascript
-// The default credential first checks environment variables for configuration as described above.
-// If environment configuration is incomplete, it will try managed identity.
-
-// Azure Key Vault service to use
-import { KeyClient } from "@azure/keyvault-keys";
-
-// Azure authentication library to access Azure Key Vault
+```ts snippet:defaultazurecredential_authenticate
 import { DefaultAzureCredential } from "@azure/identity";
+import { KeyClient } from "@azure/keyvault-keys";
 
+// Configure vault URL
+const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
 // Azure SDK clients accept the credential as a parameter
 const credential = new DefaultAzureCredential();
-
 // Create authenticated client
 const client = new KeyClient(vaultUrl, credential);
 ```
@@ -182,17 +169,23 @@ A relatively common scenario involves authenticating using a user-assigned manag
 
 While `DefaultAzureCredential` is generally the quickest way to get started developing applications for Azure, more advanced users may want to customize the credentials considered when authenticating. The `ChainedTokenCredential` enables users to combine multiple credential instances to define a customized chain of credentials. This example demonstrates creating a `ChainedTokenCredential` that attempts to authenticate using two differently configured instances of `ClientSecretCredential`, to then authenticate the `KeyClient` from the [@azure/keyvault-keys](https://www.npmjs.com/package/@azure/keyvault-keys):
 
-```typescript
+```ts snippet:chaintedtokencredential_authenticate
 import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
+import { KeyClient } from "@azure/keyvault-keys";
 
+// Configure variables
+const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
+const tenantId = "<tenant-id>";
+const clientId = "<client-id>";
+const clientSecret = "<client-secret>";
+const anotherClientId = "<another-client-id>";
+const anotherSecret = "<another-client-secret>";
 // When an access token is requested, the chain will try each
 // credential in order, stopping when one provides a token
 const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
 const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
 const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);
-
 // The chain can be used anywhere a credential is required
-import { KeyClient } from "@azure/keyvault-keys";
 const client = new KeyClient(vaultUrl, credentialChain);
 ```
 
@@ -214,15 +207,16 @@ For examples of how to use managed identity for authentication, see [the example
 
 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";
+```ts snippet:cloudconfiguration_authenticate
+import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";
+
 const credential = new ClientSecretCredential(
   "<YOUR_TENANT_ID>",
   "<YOUR_CLIENT_ID>",
   "<YOUR_CLIENT_SECRET>",
   {
     authorityHost: AzureAuthorityHosts.AzureGovernment,
-  }
+  },
 );
 ```
 
@@ -234,15 +228,16 @@ 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";
+```ts snippet:cloudconfiguration_authorityhost
+import { ClientSecretCredential } from "@azure/identity";
+
 const credential = new ClientSecretCredential(
   "<YOUR_TENANT_ID>",
   "<YOUR_CLIENT_ID>",
   "<YOUR_CLIENT_SECRET>",
   {
     authorityHost: "https://login.partner.microsoftonline.cn",
-  }
+  },
 );
 ```
 

package/dist/index.js

@@ -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.3`;
+const SDK_VERSION = `4.5.0`;
 /**
  * The default client ID for authentication
  * @internal
@@ -640,6 +640,7 @@ class IdentityClient extends coreClient.ServiceClient {
                     token: parsedBody.access_token,
                     expiresOnTimestamp: parseExpirationTimestamp(parsedBody),
                     refreshAfterTimestamp: parseRefreshTimestamp(parsedBody),
+                    tokenType: "Bearer",
                 },
                 refreshToken: parsedBody.refresh_token,
             };
@@ -1017,18 +1018,16 @@ const pluginContext = {
  *
  * Example:
  *
- * ```javascript
- * import { cachePersistencePlugin } from "@azure/identity-cache-persistence";
+ * ```ts snippet:consumer_example
+ * import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity";
  *
- * import { useIdentityPlugin, DefaultAzureCredential } from "@azure/identity";
  * useIdentityPlugin(cachePersistencePlugin);
- *
- * // The plugin has the capability to extend `DefaultAzureCredential` and to
+ * // The plugin has the capability to extend `DeviceCodeCredential` and to
  * // add middleware to the underlying credentials, such as persistence.
- * const credential = new DefaultAzureCredential({
+ * const credential = new DeviceCodeCredential({
  *   tokenCachePersistenceOptions: {
- *     enabled: true
- *   }
+ *     enabled: true,
+ *   },
  * });
  * ```
  *
@@ -1184,7 +1183,8 @@ function handleMsalError(scopes, error, getTokenOptions) {
     }
     if (error.name === "ClientConfigurationError" ||
         error.name === "BrowserConfigurationAuthError" ||
-        error.name === "AbortError") {
+        error.name === "AbortError" ||
+        error.name === "AuthenticationError") {
         return error;
     }
     if (error.name === "NativeAuthError") {
@@ -1695,6 +1695,12 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
                 silentRequest.tokenQueryParameters["msal_request_type"] = "consumer_passthrough";
             }
         }
+        if (options.proofOfPossessionOptions) {
+            silentRequest.shrNonce = options.proofOfPossessionOptions.nonce;
+            silentRequest.authenticationScheme = "pop";
+            silentRequest.resourceRequestMethod = options.proofOfPossessionOptions.resourceRequestMethod;
+            silentRequest.resourceRequestUri = options.proofOfPossessionOptions.resourceRequestUrl;
+        }
         state.logger.getToken.info("Attempting to acquire token silently");
         return app.acquireTokenSilent(silentRequest);
     }
@@ -1753,6 +1759,7 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
             token: response.accessToken,
             expiresOnTimestamp: response.expiresOn.getTime(),
             refreshAfterTimestamp: (_b = response.refreshOn) === null || _b === void 0 ? void 0 : _b.getTime(),
+            tokenType: response.tokenType,
         };
     }
     async function getTokenByClientSecret(scopes, clientSecret, options = {}) {
@@ -1773,6 +1780,7 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
                 token: response.accessToken,
                 expiresOnTimestamp: response.expiresOn.getTime(),
                 refreshAfterTimestamp: (_a = response.refreshOn) === null || _a === void 0 ? void 0 : _a.getTime(),
+                tokenType: response.tokenType,
             };
         }
         catch (err) {
@@ -1798,6 +1806,7 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
                 token: response.accessToken,
                 expiresOnTimestamp: response.expiresOn.getTime(),
                 refreshAfterTimestamp: (_a = response.refreshOn) === null || _a === void 0 ? void 0 : _a.getTime(),
+                tokenType: response.tokenType,
             };
         }
         catch (err) {
@@ -1822,6 +1831,7 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
                 token: response.accessToken,
                 expiresOnTimestamp: response.expiresOn.getTime(),
                 refreshAfterTimestamp: (_a = response.refreshOn) === null || _a === void 0 ? void 0 : _a.getTime(),
+                tokenType: response.tokenType,
             };
         }
         catch (err) {
@@ -1923,6 +1933,7 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
                 token: response.accessToken,
                 expiresOnTimestamp: response.expiresOn.getTime(),
                 refreshAfterTimestamp: (_a = response.refreshOn) === null || _a === void 0 ? void 0 : _a.getTime(),
+                tokenType: response.tokenType,
             };
         }
         catch (err) {
@@ -1960,6 +1971,13 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
             else {
                 msalLogger.verbose("Attempting broker authentication without the default broker account");
             }
+            if (options.proofOfPossessionOptions) {
+                interactiveRequest.shrNonce = options.proofOfPossessionOptions.nonce;
+                interactiveRequest.authenticationScheme = "pop";
+                interactiveRequest.resourceRequestMethod =
+                    options.proofOfPossessionOptions.resourceRequestMethod;
+                interactiveRequest.resourceRequestUri = options.proofOfPossessionOptions.resourceRequestUrl;
+            }
             try {
                 return await app.acquireTokenInteractive(interactiveRequest);
             }
@@ -1994,6 +2012,13 @@ To work with multiple accounts for the same Client ID and Tenant ID, please prov
             if (state.pluginConfiguration.broker.isEnabled) {
                 return getBrokeredToken((_a = state.pluginConfiguration.broker.useDefaultBrokerAccount) !== null && _a !== void 0 ? _a : false);
             }
+            if (options.proofOfPossessionOptions) {
+                interactiveRequest.shrNonce = options.proofOfPossessionOptions.nonce;
+                interactiveRequest.authenticationScheme = "pop";
+                interactiveRequest.resourceRequestMethod =
+                    options.proofOfPossessionOptions.resourceRequestMethod;
+                interactiveRequest.resourceRequestUri = options.proofOfPossessionOptions.resourceRequestUrl;
+            }
             return app.acquireTokenInteractive(interactiveRequest);
         });
     }
@@ -2338,6 +2363,7 @@ class MsalMsiProvider {
                     expiresOnTimestamp: token.expiresOn.getTime(),
                     token: token.accessToken,
                     refreshAfterTimestamp: (_a = token.refreshOn) === null || _a === void 0 ? void 0 : _a.getTime(),
+                    tokenType: "Bearer",
                 };
             }
             catch (err) {
@@ -2612,6 +2638,7 @@ class AzureCliCredential {
             return {
                 token,
                 expiresOnTimestamp,
+                tokenType: "Bearer",
             };
         }
         // fallback to the older expiresOn - an RFC3339 date string
@@ -2623,6 +2650,7 @@ class AzureCliCredential {
         return {
             token,
             expiresOnTimestamp,
+            tokenType: "Bearer",
         };
     }
 }
@@ -2771,6 +2799,7 @@ class AzureDeveloperCliCredential {
                     return {
                         token: resp.token,
                         expiresOnTimestamp: new Date(resp.expiresOn).getTime(),
+                        tokenType: "Bearer",
                     };
                 }
                 catch (e) {
@@ -2991,6 +3020,7 @@ class AzurePowerShellCredential {
                 return {
                     token: response.Token,
                     expiresOnTimestamp: new Date(response.ExpiresOn).getTime(),
+                    tokenType: "Bearer",
                 };
             }
             catch (err) {
@@ -3061,7 +3091,14 @@ class ChainedTokenCredential {
      * @param sources - `TokenCredential` implementations to be tried in order.
      *
      * Example usage:
-     * ```javascript
+     * ```ts snippet:chained_token_credential_example
+     * import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
+     *
+     * const tenantId = "<tenant-id>";
+     * const clientId = "<client-id>";
+     * const clientSecret = "<client-secret>";
+     * const anotherClientId = "<another-client-id>";
+     * const anotherSecret = "<another-client-secret>";
      * const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
      * const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
      * const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);
@@ -3725,13 +3762,15 @@ class DeviceCodeCredential {
      *
      * Developers can configure how this message is shown by passing a custom `userPromptCallback`:
      *
-     * ```js
+     * ```ts snippet:device_code_credential_example
+     * import { DeviceCodeCredential } from "@azure/identity";
+     *
      * const credential = new DeviceCodeCredential({
-     *   tenantId: env.AZURE_TENANT_ID,
-     *   clientId: env.AZURE_CLIENT_ID,
+     *   tenantId: process.env.AZURE_TENANT_ID,
+     *   clientId: process.env.AZURE_CLIENT_ID,
      *   userPromptCallback: (info) => {
      *     console.log("CUSTOMIZED PROMPT CALLBACK", info.message);
-     *   }
+     *   },
      * });
      * ```
      *
@@ -3803,7 +3842,8 @@ class AzurePipelinesCredential {
      * @param systemAccessToken - The pipeline's <see href="https://learn.microsoft.com/azure/devops/pipelines/build/variables?view=azure-devops%26tabs=yaml#systemaccesstoken">System.AccessToken</see> value.
      * @param options - The identity client options to use for authentication.
      */
-    constructor(tenantId, clientId, serviceConnectionId, systemAccessToken, options) {
+    constructor(tenantId, clientId, serviceConnectionId, systemAccessToken, options = {}) {
+        var _a, _b;
         if (!clientId) {
             throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. clientId is a required parameter.`);
         }
@@ -3816,6 +3856,12 @@ class AzurePipelinesCredential {
         if (!systemAccessToken) {
             throw new CredentialUnavailableError(`${credentialName$1}: is unavailable. systemAccessToken is a required parameter.`);
         }
+        // Allow these headers to be logged for troubleshooting by AzurePipelines.
+        options.loggingOptions = Object.assign(Object.assign({}, options === null || options === void 0 ? void 0 : options.loggingOptions), { additionalAllowedHeaderNames: [
+                ...((_b = (_a = options.loggingOptions) === null || _a === void 0 ? void 0 : _a.additionalAllowedHeaderNames) !== null && _b !== void 0 ? _b : []),
+                "x-vss-e2eid",
+                "x-msedge-ref",
+            ] });
         this.identityClient = new IdentityClient(options);
         checkTenantId(logger$2, tenantId);
         logger$2.info(`Invoking AzurePipelinesCredential with tenant ID: ${tenantId}, client ID: ${clientId}, and service connection ID: ${serviceConnectionId}`);
@@ -3864,6 +3910,8 @@ class AzurePipelinesCredential {
             headers: coreRestPipeline.createHttpHeaders({
                 "Content-Type": "application/json",
                 Authorization: `Bearer ${systemAccessToken}`,
+                // Prevents the service from responding with a redirect HTTP status code (useful for automation).
+                "X-TFS-FedAuthRedirect": "Suppress",
             }),
         });
         const response = await this.identityClient.sendRequest(request);
@@ -3871,6 +3919,7 @@ class AzurePipelinesCredential {
     }
 }
 function handleOidcResponse(response) {
+    // OIDC token is present in `bodyAsText` field
     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)}`);
@@ -3888,7 +3937,7 @@ function handleOidcResponse(response) {
             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`;
+                errorDescription = `Response body = ${text}. Response Headers ["x-vss-e2eid"] = ${response.headers.get("x-vss-e2eid")} and ["x-msedge-ref"] = ${response.headers.get("x-msedge-ref")}. See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/azurepipelinescredential/troubleshoot`;
             }
             logger$2.error(errorMessage);
             logger$2.error(errorDescription);
@@ -3900,11 +3949,12 @@ function handleOidcResponse(response) {
     }
     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(`Response from service = ${text}, Response Headers ["x-vss-e2eid"] = ${response.headers.get("x-vss-e2eid")} 
+      and ["x-msedge-ref"] = ${response.headers.get("x-msedge-ref")}, 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`,
+            error_description: `Response = ${text}. Response headers ["x-vss-e2eid"] = ${response.headers.get("x-vss-e2eid")} and ["x-msedge-ref"] =  ${response.headers.get("x-msedge-ref")}. See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/azurepipelinescredential/troubleshoot`,
         });
     }
 }
@@ -4072,14 +4122,14 @@ class OnBehalfOfCredential {
 /**
  * Returns a callback that provides a bearer token.
  * For example, the bearer token can be used to authenticate a request as follows:
- * ```js
- * import { DefaultAzureCredential } from "@azure/identity";
+ * ```ts snippet:token_provider_example
+ * import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
+ * import { createPipelineRequest } from "@azure/core-rest-pipeline";
  *
  * const credential = new DefaultAzureCredential();
  * const scope = "https://cognitiveservices.azure.com/.default";
  * const getAccessToken = getBearerTokenProvider(credential, scope);
  * const token = await getAccessToken();
- *
  * // usage
  * const request = createPipelineRequest({ url: "https://example.com" });
  * request.headers.set("Authorization", `Bearer ${token}`);