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

on GitHub

2.0.0-beta.1 (2021-03-24)

This update marks the preview for the first major version update of the @azure/identity package since the first stable version was released in October, 2019. This is mainly driven by the improvements we are making for the InteractiveBrowserCredential when used in browser applications by updating it to use the new @azure/msal-browser which is replacing the older msal package.

Breaking changes

• Changes to InteractiveBrowserCredential
  • When used in browser applications, the InteractiveBrowserCredential has been updated to use the Auth Code Flow with PKCE rather than Implicit Grant Flow by default to better support browsers with enhanced security restrictions. Please note that this credential always used the Auth Code Flow when used in Node.js applications. Read more on this in our docs on Interactive Browser Credential.
  • The default client ID used for InteractiveBrowserCredential was viable only in Node.js and not for the browser. Therefore, client Id is now a required parameter when constructing this credential in browser applications.
  • The loginStyle and flow options to the constructor for InteractiveBrowserCredential will now show up only when used in browser applications as these were never applicable to Node.js
  • Removed the postLogoutRedirectUri from the options to the constructor for InteractiveBrowserCredential. This option was not being used since we don't have a way for users to log out yet.
• When a token is not available, some credentials had the promise returned by the getToken method resolve with null, others had the getToken method throw the CredentialUnavailable error. This behavior is now made consistent across all credentials to throw the CredentialUnavailable error.
  • This change has no bearing on the user if all they ever did was create the credentials and pass it to the Azure SDKs.
  • This change affects only those users who called the getToken() method directly and did not handle resulting errors.
• The constructor for DeviceCodeCredential always had multiple optional parameters and no required ones. As per our guidelines, this has now been simplified to take a single optional bag of parameters.

New features

• Changes to InteractiveBrowserCredential, DeviceCodeCredential, ClientSecretCredential, ClientCertificateCredential and UsernamePasswordCredential:
  • Migrated to use the latest MSAL. This update improves caching of tokens, significantly reducing the number of network requests.
  • Added the feature of persistence caching of credentials. This is driven by the new tokenCachePersistenceOptions option available in the options you pass to the credential constructors.
    • For now, to use this feature, users will need to install @azure/msal-node-extensions 1.0.0-alpha.6 on their own. This experience will be improved in the next update.
    • This feature uses DPAPI on Windows, it tries to use the Keychain on OSX and the Keyring on Linux.
    • To learn more on the usage, please refer to our docs on the TokenCachePersistenceOptions interface.
    • IMPORTANT: As part of this beta, this feature is only supported in Node 10, 12 and 14.
• Changes to InteractiveBrowserCredential, DeviceCodeCredential, and UsernamePasswordCredential:
  • 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.
  • 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.

Other changes

• Updated the @azure/msal-node dependency to ^1.0.0.
• DefaultAzureCredential's implementation for browsers is simplified to throw the BrowserNotSupportedError in its constructor. Previously, we relied on getting the same error from trying to instantiate the different credentials that DefaultAzureCredential supports in Node.js.
  • As before, please use only the InteractiveBrowserCredential in your browser applications.
• For the InteractiveBrowserCredential for node, replaced the use of the express module with a native http server for Node, shrinking the resulting identity module considerably.