Enable Edge API for Platform brokering (#8171)

This pull request:

* Introduces support for configuring DOM API usage for platform broker
authentication in MSAL.js, specifically targeting Edge browser
environments.
* Updates documentation to clarify platform broker support across
Windows and Mac, adds a new configuration flag
(`allowPlatformBrokerWithDOM`), and introduces validation to prevent
misconfiguration.
* Error handling and messaging are also improved for invalid
configuration scenarios.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: 3 people

change/@azure-msal-browser-bdb9bd60-08c2-4532-b0cd-2b9830ffa03f.json

@@ -0,0 +1,7 @@
+{
+    "type": "minor",
+    "comment": "Add DOM API configuration, #8171",
+    "packageName": "@azure/msal-browser",
+    "email": "sameera.gajjarapu@microsoft.com",
+    "dependentChangeType": "patch"
+}

change/@azure-msal-common-c8d42435-3b15-43cc-9cce-19f00d77e61e.json

@@ -0,0 +1,7 @@
+{
+    "type": "patch",
+    "comment": "Add DOM API configuration, #8171",
+    "packageName": "@azure/msal-common",
+    "email": "sameera.gajjarapu@microsoft.com",
+    "dependentChangeType": "patch"
+}

lib/msal-browser/apiReview/msal-browser.api.md

@@ -586,6 +586,7 @@ export type BrowserSystemOptions = SystemOptions & {
     asyncPopups?: boolean;
     allowRedirectInIframe?: boolean;
     allowPlatformBroker?: boolean;
+    allowPlatformBrokerWithDOM?: boolean;
     nativeBrokerHandshakeTimeout?: number;
     pollIntervalMilliseconds?: number;
 };
@@ -1165,7 +1166,7 @@ function isInPopup(): boolean;
 // Warning: (ae-missing-release-tag) "isPlatformBrokerAvailable" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
-export function isPlatformBrokerAvailable(loggerOptions?: LoggerOptions, perfClient?: IPerformanceClient, correlationId?: string): Promise<boolean>;
+export function isPlatformBrokerAvailable(loggerOptions?: LoggerOptions, perfClient?: IPerformanceClient, correlationId?: string, domConfig?: boolean): Promise<boolean>;
 
 // Warning: (ae-missing-release-tag) "ITokenCache" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -1827,7 +1828,7 @@ export type WrapperSKU = (typeof WrapperSKU)[keyof typeof WrapperSKU];
 // src/cache/LocalStorage.ts:363:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:426:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:457:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/config/Configuration.ts:260:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
+// src/config/Configuration.ts:264:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
 // src/event/EventHandler.ts:113:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/event/EventHandler.ts:139:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/index.ts:8:12 - (tsdoc-characters-after-block-tag) The token "@azure" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"

lib/msal-browser/docs/device-bound-tokens.md

@@ -1,12 +1,12 @@
-# Acquiring Device Bound Tokens using Web Account Manager (WAM) on Windows
+# Acquiring Device Bound Tokens using platform brokers
 
-MSAL.js supports acquiring tokens from the Web Account Manager (WAM) on Windows. These tokens are bound to the device they were acquired on and are not cached in the browser's localStorage or sessionStorage.
+MSAL.js supports acquiring tokens from the platform broker, say Web Account Manager (WAM) on Windows and Mac Broker on Mac. These tokens are bound to the device they were acquired on and are not cached in the browser's localStorage or sessionStorage.
 
 ## Supported Environment
 
 This feature is currently only supported in the following environment:
 
--   A machine running a Windows build that supports the feature (more to come on this)
+-   A machine running a Windows build that supports the feature (more to come on this) or a Company Portal managed Mac with a specific Mac OS version (more to come on this).
 -   Chrome and Edge browsers or Teams
 -   [Windows Accounts extension](https://chrome.google.com/webstore/detail/windows-accounts/ppnbnpeolgkicgegkbkbjmhlideopiji) (version 1.0.5 or higher) is installed if using Chrome or Edge
 -   App must be hosted on `https`
@@ -47,10 +47,35 @@ No other changes are needed to support this new feature. Any user accessing your
 
 A working sample can be found [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-browser-samples/VanillaJSTestApp2.0/app/wamBroker)
 
-## Differences when using WAM to acquire tokens
+## Differences when using Platform Broker to acquire tokens
 
-There are a few things that may behave a little differently when acquiring tokens through WAM.
+There are a few things that may behave a little differently when acquiring tokens through the platform broker.
 
--   All cache related configuration applies only to MSAL's local cache. The native broker controls its own, more secure, cache which is used instead of browser storage and it does not support configuration of its cache behavior. This means you may receive a cached token regardless of the value of request parameters such as: `forceRefresh`, `cacheLookupPolicy` or `storeInCache`. In addition, tokens received from the native broker are _not_ stored in local or session storage regardless of what you have configured on PublicClientApplication.
--   If WAM needs to prompt the user for interaction a system prompt will be opened. This prompt looks a bit different from the browser popup windows you may be used to.
--   Switching your account in the WAM prompt is not supported and MSAL.js will throw an error (Error Code: user_switch) if this happens. It is your app's responsibility to catch this error and handle it in a way that makes sense for your scenarios (e.g. Show an error page, retry with the new account, retry with the original account, etc.)
+-   All cache related configuration applies only to MSAL's local cache. The platform broker controls its own, more secure, cache which is used instead of browser storage and it does not support configuration of its cache behavior. This means you may receive a cached token regardless of the value of request parameters such as: `forceRefresh`, `cacheLookupPolicy` or `storeInCache`. In addition, tokens received from the platform broker are _not_ stored in local or session storage regardless of what you have configured on PublicClientApplication.
+-   If the platform broker needs to prompt the user for interaction a system prompt will be opened. This prompt looks a bit different from the browser popup windows you may be used to.
+-   Switching your account in the platform broker prompt is not supported and MSAL.js will throw an error (Error Code: user_switch) if this happens. It is your app's responsibility to catch this error and handle it in a way that makes sense for your scenarios (e.g. Show an error page, retry with the new account, retry with the original account, etc.)
+
+# Acquiring Device Bound Tokens using DOM API
+
+MSAL.js also supports acquiring tokens from the platform broker using DOM APIs in Edge. Instead of using a browser extension to communicate with the platform broker, MSAL.js can directly call a DOM API in the Edge browser, which in turn manages to invoke the platform broker to acquire tokens.
+
+-   This feature is currently only supported in the Edge browser and all other OS requirements mentioned above still apply. (more details to come).
+-   This feature is currently only in private-preview and requires special enablement. Please reach out to your Microsoft representative for more details.
+
+To enable this feature, set the `allowPlatformBrokerWithDOM` flag to true in your configuration object like so:
+
+```javascript
+const msalConfig = {
+    auth: {
+        clientId: "insert-clientId",
+    },
+    system: {
+        allowPlatformBroker: true,
+        allowPlatformBrokerWithDOM: true,
+    },
+};
+```
+
+Note: The `allowPlatformBroker` flag must also be set to true in order to use this feature. There will be a configuration error - `invalid_platform_broker_configuration` if `allowPlatformBrokerWithDOM` is set to true while `allowPlatformBroker` is false.
+
+Eventually, in a future major version, this flag will be merged with `allowPlatformBroker` and MSAL.js will make the decision to use either the browser extension or DOM APIs based on the environment automatically.

lib/msal-browser/src/broker/nativeBroker/PlatformAuthProvider.ts

@@ -9,6 +9,8 @@ import {
     Logger,
     AuthenticationScheme,
     StubPerformanceClient,
+    createClientConfigurationError,
+    ClientConfigurationErrorCodes,
 } from "@azure/msal-common/browser";
 import { name, version } from "../../packageMetadata.js";
 import {
@@ -19,8 +21,6 @@ import { PlatformAuthExtensionHandler } from "./PlatformAuthExtensionHandler.js"
 import { IPlatformAuthHandler } from "./IPlatformAuthHandler.js";
 import { PlatformAuthDOMHandler } from "./PlatformAuthDOMHandler.js";
 import { createNewGuid } from "../../crypto/BrowserCrypto.js";
-import { BrowserCacheLocation } from "../../utils/BrowserConstants.js";
-import { PLATFORM_AUTH_DOM_SUPPORT } from "../../cache/CacheKeys.js";
 
 /**
  * Checks if the platform broker is available in the current environment.
@@ -31,7 +31,8 @@ import { PLATFORM_AUTH_DOM_SUPPORT } from "../../cache/CacheKeys.js";
 export async function isPlatformBrokerAvailable(
     loggerOptions?: LoggerOptions,
     perfClient?: IPerformanceClient,
-    correlationId?: string
+    correlationId?: string,
+    domConfig?: boolean
 ): Promise<boolean> {
     const logger = new Logger(loggerOptions || {}, name, version);
 
@@ -47,24 +48,26 @@ export async function isPlatformBrokerAvailable(
     return !!(await getPlatformAuthProvider(
         logger,
         performanceClient,
-        correlationId || createNewGuid()
+        correlationId || createNewGuid(),
+        undefined,
+        domConfig
     ));
 }
 
 export async function getPlatformAuthProvider(
     logger: Logger,
     performanceClient: IPerformanceClient,
     correlationId: string,
-    nativeBrokerHandshakeTimeout?: number
+    nativeBrokerHandshakeTimeout?: number,
+    enablePlatformBrokerDOMSupport?: boolean
 ): Promise<IPlatformAuthHandler | undefined> {
     logger.trace("getPlatformAuthProvider called", correlationId);
 
-    const enablePlatformBrokerDOMSupport = isDomEnabledForPlatformAuth();
-
     logger.trace(
         "Has client allowed platform auth via DOM API: " +
             enablePlatformBrokerDOMSupport
     );
+
     let platformAuthProvider: IPlatformAuthHandler | undefined;
     try {
         if (enablePlatformBrokerDOMSupport) {
@@ -97,22 +100,6 @@ export async function getPlatformAuthProvider(
     return platformAuthProvider;
 }
 
-/**
- * Returns true if the DOM API support for platform auth is enabled in session storage
- * @returns boolean
- * @deprecated
- */
-export function isDomEnabledForPlatformAuth(): boolean {
-    let sessionStorage: Storage | undefined;
-    try {
-        sessionStorage = window[BrowserCacheLocation.SessionStorage];
-        // Mute errors if it's a non-browser environment or cookies are blocked.
-        return sessionStorage?.getItem(PLATFORM_AUTH_DOM_SUPPORT) === "true";
-    } catch (e) {
-        return false;
-    }
-}
-
 /**
  * Returns boolean indicating whether or not the request should attempt to use native broker
  * @param logger
@@ -127,6 +114,17 @@ export function isPlatformAuthAllowed(
     authenticationScheme?: AuthenticationScheme
 ): boolean {
     logger.trace("isPlatformAuthAllowed called");
+
+    // throw an error if allowPlatformBroker is not enabled and allowPlatformBrokerWithDOM is enabled
+    if (
+        !config.system.allowPlatformBroker &&
+        config.system.allowPlatformBrokerWithDOM
+    ) {
+        throw createClientConfigurationError(
+            ClientConfigurationErrorCodes.invalidPlatformBrokerConfiguration
+        );
+    }
+
     if (!config.system.allowPlatformBroker) {
         logger.trace(
             "isPlatformAuthAllowed: allowPlatformBroker is not enabled, returning false"

lib/msal-browser/src/config/Configuration.ts

@@ -209,6 +209,10 @@ export type BrowserSystemOptions = SystemOptions & {
      * Flag to enable native broker support (e.g. acquiring tokens from WAM on Windows, MacBroker on Mac)
      */
     allowPlatformBroker?: boolean;
+    /**
+     * Flag to enable native broker support through DOM APIs in Edge
+     */
+    allowPlatformBrokerWithDOM?: boolean;
     /**
      * Sets the timeout for waiting for the native broker handshake to resolve
      */
@@ -357,6 +361,7 @@ export function buildConfiguration(
         asyncPopups: false,
         allowRedirectInIframe: false,
         allowPlatformBroker: false,
+        allowPlatformBrokerWithDOM: false,
         nativeBrokerHandshakeTimeout:
             userInputSystem?.nativeBrokerHandshakeTimeout ||
             DEFAULT_NATIVE_BROKER_HANDSHAKE_TIMEOUT_MS,

lib/msal-browser/src/controllers/StandardController.ts

@@ -356,7 +356,8 @@ export class StandardController implements IController {
                     this.logger,
                     this.performanceClient,
                     initCorrelationId,
-                    this.config.system.nativeBrokerHandshakeTimeout
+                    this.config.system.nativeBrokerHandshakeTimeout,
+                    this.config.system.allowPlatformBrokerWithDOM
                 );
             } catch (e) {
                 this.logger.verbose(e as string);

lib/msal-browser/test/app/PublicClientApplication.spec.ts

@@ -496,13 +496,6 @@ describe("PublicClientApplication.ts Class Unit Tests", () => {
                 },
             };
 
-            jest.spyOn(
-                PlatformAuthProvider,
-                "isDomEnabledForPlatformAuth"
-            ).mockImplementation(() => {
-                return false;
-            });
-
             const getPlatformAuthProviderSpy = jest.spyOn(
                 PlatformAuthProvider,
                 "getPlatformAuthProvider"
@@ -555,7 +548,7 @@ describe("PublicClientApplication.ts Class Unit Tests", () => {
             expect(pca.platformAuthProvider).toBeUndefined();
         });
 
-        it("creates platform auth dom handler if allowPlatformBroker is true and dom APIs are present", async () => {
+        it("creates platform auth dom handler if allowPlatformBrokerWithDOM is true and dom APIs are present", async () => {
             const getPlatformAuthProviderSpy = jest.spyOn(
                 PlatformAuthProvider,
                 "getPlatformAuthProvider"
@@ -567,14 +560,11 @@ describe("PublicClientApplication.ts Class Unit Tests", () => {
                 },
                 system: {
                     allowPlatformBroker: true,
+                    allowPlatformBrokerWithDOM: true,
                 },
             };
 
             pca = new PublicClientApplication(config);
-            window.sessionStorage.setItem(
-                "msal.browser.platform.auth.dom",
-                "true"
-            );
 
             const createDOMProviderSpy = stubDOMProvider(config);
             await pca.initialize();