[Identity] 2.0.0-beta.1 release date (Azure#14452)

This PR is to review the changelog and define the release date for 2.0.0-beta.1

Continues from: Azure#14405

Author: sadasant

sdk/identity/identity/CHANGELOG.md

@@ -1,29 +1,46 @@
 # Release History
 
-## 2.0.0-beta.1 (Unreleased)
-
-This release continues with the changes from `1.2.4` and `1.2.4-beta.1`.
-
-- The `getToken` methods will now never return `null`. If a token is not available, we will return a rejected promise.
-- `DefaultAzureCredential`'s implementation for browsers was simplified to throw a simple error instead of trying credentials that were already not supported for the browser.
-- Breaking Change: `InteractiveBrowserCredential` for the browser now requires the client ID to be provided.
-- Documentation was added to elaborate on how to configure an AAD application to support `InteractiveBrowserCredential`.
-- Replaced the use of the 'express' module with a Node-native http server, shrinking the resulting identity module considerably
-- Updated `@azure/msal-node-extensions` to [1.0.0-alpha.6](https://www.npmjs.com/package/@azure/msal-node-extensions/v/1.0.0-alpha.6).
-- Refactored our use of MSAL to better centralize the handling of inputs, outputs and errors.
-- Migrated the `InteractiveBrowserCredential`, `DeviceCodeCredential`, `ClientSecretCredential`, `ClientCertificateCredential` and `UsernamePasswordCredential` to the latest MSAL.
-  - This update improves caching of tokens, significantly reducing the number of network requests.
-- Credentials `InteractiveBrowserCredential`, `DeviceCodeCredential` and `UsernamePasswordCredential` now can:
-  - Receive a `tokenCachePersistenceOptions` parameter to specify persitence caching of the credentials used to authenticate. This feature uses DPAPI on Windows, it tries to use the Keychain on OSX and the Keyring on Linux, and if the user sets `allowUnencryptedStorage` to true in the `tokenCachePersistenceOptions`, it allows to fall back to an unprotected file if neither the Keychain nor the Keyring are available.
-    - As part of this beta, this feature is only supported in Node 10, 12 and 14.
-  - Receive an `authenticationRecord` from a previous authentication on their constructors, which skips the initial request altogether.
-  - Receive a `disableAutomaticAuthentication` setting on the constructor, which stops `getToken` from requesting the user to authenticate manually.
-  - An `authenticate()` method has been added besides the `getToken()` method.
-  - The `authenticate()` method returns an `AuthenticationRecord` which can be serialized into strings with their property `serialize()`. To later deserialize from string into an `AuthenticationRecord`, use the new function `deserializeAuthenticationRecord()`.
-  - If `disableAutomaticAuthentication` is set on the constructor of these credentials, developers can now control when to manually authenticate by calling to these credential's `authenticate()` method.
-- `DeviceCodeCredential` now can receive its optional parameters as a single parameter object.
-- Breaking change: `InteractiveBrowserCredential` now only has `loginStyle` and `flow` in the optional parameters when the credential is bundled for browsers. This reflects the intended behavior.
-- Breaking change: Removed the `postLogoutRedirectUri` from the optional properties of the `InteractiveBrowserCredential`.
+## 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](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow) with [PKCE](https://tools.ietf.org/html/rfc7636) rather than [Implicit Grant Flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-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](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/interactive-browser-credential.md).
+  - 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](https://www.npmjs.com/package/@azure/msal-node-extensions/v/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.
+
+
 
 ## 1.2.4 (2021-03-08)
 

sdk/identity/identity/README.md

@@ -31,6 +31,8 @@ npm install --save @azure/identity
   - You can sign up for a [free account](https://azure.microsoft.com/free/).
 - The [Azure CLI][azure_cli] can also be useful for authenticating in a development environment, creating accounts, and managing account roles.
 
+Credentials `InteractiveBrowserCredential`, `DeviceCodeCredential`, `ClientSecretCredential`, `ClientCertificateCredential` and `UsernamePasswordCredential` allow specifying `tokenCachePersistenceOptions` to enable persistent caching. To use this feature, developers will also need to install [@azure/msal-node-extensions](https://www.npmjs.com/package/@azure/msal-node-extensions).
+
 ### Authenticate the client in development environment
 
 While we recommend using managed identity or service principal authentication in your production application, it is typical for a developer to use their own account for authenticating calls to Azure services when debugging and executing code locally. There are several developer tools which can be used to perform this authentication in your development environment.

sdk/identity/identity/interactive-browser-credential.md

@@ -1,11 +1,13 @@
 # Interactive Browser Credential
 
-The `InteractiveBrowserCredential` uses [Authorization Code Flow][AuthCodeFlow], which uses [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) both on the browser and on NodeJS. Under the hood it uses [@azure/msal-node](https://www.npmjs.com/package/@azure/msal-node) for NodeJS. For the browser it uses [MSAL v2.x](https://github.com/AzureAD/microsoft-authentication-library-for-js) by default (which also uses Authorization Code Flow), while it also allows switching back to the older [Implicit Grant Flow][ImplicitGrantFlow] by passing the `flow` property with the value `implicit-grant` through to the constructor of the `InteractiveBrowserCredential`, as follows:
+The `InteractiveBrowserCredential` uses [Authorization Code Flow][AuthCodeFlow], which uses [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) both on the browser and on NodeJS. Under the hood it uses [@azure/msal-node](https://www.npmjs.com/package/@azure/msal-node) for Node.js and [@azure/msal-browser](https://www.npmjs.com/package/@azure/msal-browser) in browsers.
+
+For the browser, we allow switching back to the older [Implicit Grant Flow][ImplicitGrantFlow] (which was the only option in v1 of this package for this credential) by passing the `flow` property with the value `implicit-grant` through to the constructor of the `InteractiveBrowserCredential`, as follows:
 
 ```ts
 const credential = new InteractiveBrowserCredential({
   // Authorization Code Flow is recommended and used by default.
-  // But you can switch batch to the Implicit Grant Flow if you need to:
+  // But on the browser you can switch batch to the Implicit Grant Flow if you need to:
   flow: "implicit-grant",
 });
 ```