[identity] update docs, readme and TS guide for broker feature (Azure#27637)

Author: KarishmaGhiya

common/config/rush/pnpm-lock.yaml

@@ -1,14 +1,9 @@
 # Release History
 
-## 1.0.0-beta.2 (Unreleased)
+## 1.0.0 (2023-11-06)
 
 ### Features Added
-
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- First GA release of the plugin package `@azure/identity-broker` to [support authentication through broker such as WAM](https://learn.microsoft.com/azure/active-directory/develop/scenario-desktop-acquire-token-wam). This plugin works with the [`brokerOptions` on `InteractiveBrowserCredential` added in the `@azure/identity` package](https://github.com/Azure/azure-sdk-for-js/pull/26091/).
 
 ## 1.0.0-beta.1 (2023-10-23)
 

sdk/identity/identity-broker/CHANGELOG.md

@@ -1,8 +1,10 @@
 # Azure Identity plugin for brokered authentication
 
-This package provides a plugin to the Azure Identity library for JavaScript ([`@azure/identity`](https://npmjs.com/package/@azure/identity)) that enables using an authentication broker such as [WAM](https://learn.microsoft.com/azure/active-directory/develop/scenario-desktop-acquire-token-wam).
+This package provides a plugin to the Azure Identity library for JavaScript ([`@azure/identity`](https://npmjs.com/package/@azure/identity)) that enables using an authentication broker such as [WAM](https://learn.microsoft.com/entra/identity-platform/scenario-desktop-acquire-token-wam).
 
-[Source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity-broker) | [Samples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity-broker/samples)
+An authentication broker is an application that runs on a user’s machine that manages the authentication handshakes and token maintenance for connected accounts. Currently, only the Windows authentication broker, Web Account Manager (WAM), is supported.
+
+[Source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity-broker) | [Samples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity-broker/samples) | [API reference documentation](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-identity-broker/1.0.0-beta.1/index.html) | [Microsoft Entra ID documentation] (https://learn.microsoft.com/entra/identity/)
 
 ## Getting started
 
@@ -34,6 +36,22 @@ Azure Identity plugins for JavaScript support stable (even numbered) versions of
 
 If this is your first time using `@azure/identity` or Microsoft Entra ID, we recommend that you read [Using `@azure/identity` with Microsoft Entra ID](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/using-azure-identity.md) first. This document will give you a deeper understanding of the platform and how to configure your Azure account correctly.
 
+### Parent window handles
+
+When authenticating with the broker via `InteractiveBrowserCredential`, a parent window handle is required to ensure that the authentication dialog is shown correctly over the requesting window. In the context of graphical user interfaces on devices, a window handle is a unique identifier that the operating system assigns to each window. For the Windows operating system, this handle is an integer value that serves as a reference to a specific window.
+
+## Microsoft account (MSA) passthrough
+
+Microsoft accounts (MSA) are personal accounts created by users to access Microsoft services. MSA passthrough is a legacy configuration which enables users to get tokens to resources which normally don't accept MSA logins. This feature is only available to first-party applications. Users authenticating with an application that is configured to use MSA passthrough can set `legacyEnableMsaPassthrough` to `true` inside `InteractiveBrowserCredentialNodeOptions.brokerOptions` to allow these personal accounts to be listed by WAM.
+
+## Redirect URIs
+
+Microsoft Entra applications rely on redirect URIs to determine where to send the authentication response after a user has logged in. To enable brokered authentication through WAM, a redirect URI matching the following pattern should be registered to the application:
+
+```
+ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}
+```
+
 ### Azure Identity plugins
 
 As of `@azure/identity` version 2.0.0, the Identity client library for JavaScript includes a plugin API. This package (`@azure/identity-broker`) exports a plugin object that you must pass as an argument to the top-level `useIdentityPlugin` function from the `@azure/identity` package. Enable native broker in your program as follows:
@@ -67,6 +85,7 @@ async function main() {
   const credential = new InteractiveBrowserCredential({
     brokerOptions: {
       enabled: true,
+      parentWindowHandle: <insert_current_window_handle>
     },
   });
 
@@ -82,9 +101,12 @@ main().catch((error) => {
   process.exit(1);
 });
 ```
+For an example of using Electron app for retrieving a window handle, check [this sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity-broker/samples/v1-beta/typescript/src/index.ts).
 
 ## Troubleshooting
 
+See the Azure Identity [troubleshooting guide][https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/TROUBLESHOOTING.md] for details on how to diagnose various failure scenarios.
+
 ### Logging
 
 Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:

sdk/identity/identity-broker/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@azure/identity-broker",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0",
   "sdk-type": "client",
   "description": "A native plugin for Azure Identity credentials to enable broker authentication such as WAM",
   "main": "dist/index.js",
@@ -58,7 +58,7 @@
   "sideEffects": false,
   "dependencies": {
     "@azure/core-auth": "^1.4.0",
-    "@azure/identity": "4.0.0-beta.2",
+    "@azure/identity": "^4.0.0",
     "@azure/msal-node": "^2.3.0",
     "@azure/msal-node-extensions": "^1.0.5",
     "tslib": "^2.2.0"

sdk/identity/identity-broker/package.json

@@ -6,7 +6,7 @@
  * packages for WAM MSA support.
  */
 
-import { InteractiveBrowserCredential, useIdentityPlugin } from "@azure/identity";
+import { InteractiveBrowserCredential, InteractiveBrowserCredentialNodeOptions, useIdentityPlugin } from "@azure/identity";
 import { nativeBrokerPlugin } from "@azure/identity-broker";
 import { setLogLevel } from "@azure/logger";
 
@@ -50,7 +50,7 @@ app.on("ready", async () => {
         parentWindowHandle: winHandle,
         legacyEnableMsaPassthrough: true,
       },
-    });
+    } as InteractiveBrowserCredentialNodeOptions);
 
     // This is the scope we will use to get a token from the Microsoft Entra token endpoint.
     // By default, we'll use the Microsoft Graph scope as an example, but when

sdk/identity/identity-broker/samples/v1-beta/typescript/src/index.ts

@@ -60,7 +60,7 @@
   "sideEffects": false,
   "dependencies": {
     "@azure/core-auth": "^1.5.0",
-    "@azure/identity": "4.0.0-beta.2",
+    "@azure/identity": "^4.0.0",
     "@azure/msal-node": "^2.3.0",
     "@azure/msal-node-extensions": "1.0.0-alpha.25",
     "keytar": "^7.6.0",

sdk/identity/identity-cache-persistence/package.json

@@ -1,14 +1,12 @@
 # Release History
 
-## 4.0.0-beta.2 (Unreleased)
+## 4.0.0 (2023-11-06)
 
 ### Features Added
+- All the features shipped as part of 4.0.0-beta.1 will be GA with this version. The most important feature being the support of brokered authentication on Windows OS, such as WAM.
 
 ### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Starting with v4.0.0 of `@azure/identity`, Node.js v20 will be supported and Node.js v16 will no longer be supported.
 
 ## 4.0.0-beta.1 (2023-10-26)