Azure/azure-sdk-for-js @azure/identity_2.0.0

on GitHub

2.0.0 (2021-10-15)

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 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.

Features Added

Plugin API

Identity v2 provides a top-level useIdentityPlugin function, which allows using two new plugin packages:

• @azure/identity-vscode, which provides the dependencies of VisualStudioCodeCredential and enables it.
  • If the @azure/identity-vscode plugin isn't used through the useIdentityPlugin function, the VisualStudioCodeCredential exposed by Identity v2 will throw a CredentialUnavailableError.
• @azure/identity-cache-persistence, which provides persistent token caching.

Most credentials on Identity v2 now support the persistent token caching feature. Such credentials include the property tokenCachePersistenceOptions in the constructor options which can be used to enable this feature.

The following example showcases how to enable persistence caching by first enabling the @azure/identity-cache-persistence plugin with useIdentityPlugin(cachePersistencePlugin), and then passing the tokenCachePersistenceOptions through the constructor of the DeviceCodeCredential:

import { cachePersistencePlugin } from "@azure/identity-cache-persistence";
import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity";

useIdentityPlugin(cachePersistencePlugin);

async function main() {
  const credential = new DeviceCodeCredential({
    tokenCachePersistenceOptions: {
      enabled: true
    }
  });
}

New credentials

Identity v2 includes two new credential types:

• AzurePowerShellCredential, which re-uses any account previously authenticated with the Az.Account PowerShell module.
• OnBehalfOfCredential, which enables the On-Behalf-Of authentication flow.

New features in all credentials

Identity v2 enables:

• Support for claims challenges resulting from Continuous Access Enforcement (CAE) and Conditional Access authentication context.
  • By default, credentials of Identity v2 will produce tokens that can be used to trigger the challenge authentication flows. After these tokens expire, the next HTTP requests to Azure will fail, but the response will contain information to re-authenticate.
  • To disable this behavior, set the environment variable AZURE_IDENTITY_DISABLE_CP1 to any value. For more about claims challenges, see Claims challenges, claims requests, and client capabilities.
• Support for multi-tenant authentication on all credentials except ManagedIdentityCredential.
  • At the moment, applications needing multi-tenancy support will need to call to the credentials' getToken directly, sending the new tenantId property.
  • A sample with more context will be provided in a future date.
  • To disable it, set the environment variable AZURE_IDENTITY_DISABLE_MULTITENANTAUTH. For more about multitenancy, see Identity management in multitenant apps.

New features in InteractiveBrowserCredential and DeviceCodeCredential

You can now control when the credential requests user input with the new disableAutomaticAuthentication option added to the options you pass to the credential constructors.

• When enabled, this option stops the getToken() method from requesting user input in case the credential is unable to authenticate silently.
• If getToken() fails to authenticate without user interaction, and disableAutomaticAuthentication has been set to true, a new error will be thrown: AuthenticationRequired. You may use this error to identify scenarios when manual authentication needs to be triggered (with authenticate(), as described in the next point).

A new method authenticate() is added to these credentials which is similar to getToken(), but it does not read the disableAutomaticAuthentication option described above.

• Use this to get an AuthenticationRecord which you can then use to create new credentials that will re-use the token information.
• The AuthenticationRecord object has a serialize() method that allows an authenticated account to be stored as a string and re-used in another credential at any time. Use the new helper function deserializeAuthenticationRecord to de-serialize this string.
• 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.
• Samples around persisting user authentication data.

New features in ManagedIdentityCredential

In Identity v2, the ManagedIdentityCredential retries with exponential back-off when a request for a token fails with a 404 status code. This change only applies to environments with available IMDS endpoints.

Azure Service Fabric support hasn't been added on the initial version 2 of Identity. Subscribe to issue #12420 for updates on this feature.

Other features

• ClientCertificateCredential now optionally accepts a configuration object as its third constructor parameter, instead of the PEM certificate path. This new object, called ClientCertificateCredentialPEMConfiguration, can contain either the PEM certificate path with the certificatePath property, or the contents of the PEM certificate with the certificate property..
• The Node.js version of InteractiveBrowserCredential has Proof Key for Code Exchange (PKCE) enabled by default.
• InteractiveBrowserCredential has a new loginHint constructor option, which allows a username to be pre-selected for interactive logins.
• In AzureCliCredential, we allow specifying a tenantId in the parameters through the AzureCliCredentialOptions.
• A new error, named AuthenticationRequiredError, has been added. This error shows up when a credential fails to authenticate silently.
• Errors and logged exceptions may point to the new troubleshooting guidelines.
• On all of the credentials we're providing, the initial authentication attempt in the lifetime of your app will include an additional request to first discover relevant endpoint metadata information from Azure.

Breaking changes

Breaking changes from v1

• For ClientCertificateCredential specifically, the validity of the PEM certificate is evaluated on getToken and not on the constructor.

• We have also renamed the error CredentialUnavailable to CredentialUnavailableError, to align with the naming convention used for error classes in the Azure SDKs in JavaScript.

• In v1 of Identity some getToken calls could resolve with null in the case the authentication request succeeded with a malformed output. In v2, issues with the getToken method will always throw errors.

• Breaking changes to InteractiveBrowserCredential

  • The InteractiveBrowserCredential will use the Auth Code Flow with PKCE rather than Implicit Grant Flow to better support browsers with enhanced security restrictions. Learn how to migrate in the migration guide. Read more about the latest InteractiveBrowserCredential here.
  • The default client ID used for InteractiveBrowserCredential was viable only in Node.js and not for the browser. Therefore, on v2 client ID is a required parameter when using this credential in browser apps.
  • Identity v2 also removes the postLogoutRedirectUri from the options to the constructor for InteractiveBrowserCredential. This option wasn't being used. Instead of using this option, use MSAL directly. For more information, see Authenticating with the @azure/msal-browser Public Client.
  • In Identity v2, VisualStudioCodeCredential throws a CredentialUnavailableError unless the new @azure/identity-vscode plugin is used.

• Standardizing the tracing span names to be <className>.<operationName> over <className>-<operationName>

Breaking Changes from 2.0.0-beta.4

• Removed the allowMultiTenantAuthentication option from all of the credentials. Multi-tenant authentication is now enabled by default. On Node.js, it can be disabled with the AZURE_IDENTITY_DISABLE_MULTITENANTAUTH environment variable.
• Removed support for specific Azure regions on ClientSecretCredential and `ClientCertificateCredential. This feature will be added back on the next beta.

Breaking Changes from 2.0.0-beta.6

• Stopped exporting the ApplicationCredential from the package. This will be re-introduced in the future.
• Removed the CredentialPersistenceOptions from DefaultAzureCredential and EnvironmentCredential.
• Merged the configuration and the options bag on the OnBehalfOfCredential into a single options bag.
• AuthenticationRequiredError (introduced in 2.0.0-beta.1) now has its parameters into a single options bag.
• AuthenticationRequiredError (introduced in 2.0.0-beta.1) now has its parameters in a single options bag, AuthenticationRequiredErrorOptions.
• InteractiveBrowserCredentialOptions has been renamed to InteractiveBrowserCredentialNodeOptions, and InteractiveBrowserCredentialBrowserOptions has been named InteractiveBrowserCredentialInBrowserOptions.

Bugs Fixed

• ClientSecretCredential, ClientCertificateCredential, and UsernamePasswordCredential throw if the required parameters aren't provided (even in JavaScript).
• Fixed a bug that caused AzureCliCredential to fail when a custom tenant ID was provided.
• Caught up with the bug fixes for Azure POD Identity that were implemented on version 1.5.1.

Other Changes

Identity v2 no longer includes native dependencies (neither ordinary, peer, nor optional dependencies). Previous distributions of @azure/identity included an optional dependency on keytar, which caused issues for some users in restrictive environments.

Identity v2 for JavaScript now also depends on the latest available versions of @azure/msal-common, @azure/msal-node, and @azure/msal-browser. Our goal is to always be up-to-date with the MSAL versions.