Add allowPlatformBrokerWithDOM experimental config flag (#8589)

Add experimental config flag 'allowPlatformBrokerWithDOM' under
BrowserExperimentalOptions to enable platform broker support through DOM
APIs in Edge. When both allowPlatformBroker and
allowPlatformBrokerWithDOM are set, MSAL first checks for DOM API
availability before falling back to PlatformAuthExtensionHandler.

- Add allowPlatformBrokerWithDOM to BrowserExperimentalOptions (default:
false)
- Replace session storage-based isDomEnabledForPlatformAuth with
explicit config parameter
- Add invalidPlatformBrokerConfiguration error code for invalid config
combinations
- Add config validation in isPlatformAuthAllowed
- Pass config flag through StandardController to getPlatformAuthProvider

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: lalimasharda <26092202+lalimasharda@users.noreply.github.com>
Co-authored-by: Thomas Norling <thomas.norling@microsoft.com>

Author: 4 people

change/@azure-msal-browser-allow-platform-broker-with-dom.json

@@ -0,0 +1,7 @@
+{
+    "type": "minor",
+    "comment": "Add allowPlatformBrokerWithDOM experimental config flag for DOM-based platform brokering [#8589](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/8589)",
+    "packageName": "@azure/msal-browser",
+    "email": "lalimasharda@microsoft.com",
+    "dependentChangeType": "patch"
+}

change/@azure-msal-common-allow-platform-broker-with-dom.json

@@ -0,0 +1,7 @@
+{
+    "type": "patch",
+    "comment": "Add invalidPlatformBrokerConfiguration error code for DOM-based platform brokering [#8589](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/8589)",
+    "packageName": "@azure/msal-common",
+    "email": "lalimasharda@microsoft.com",
+    "dependentChangeType": "patch"
+}

docs/errors.md

@@ -261,6 +261,10 @@ This error occurs when MSAL.js surpasses the allotted storage limit when attempt
 
 -   Cannot set allowPlatformBroker parameter to true when not in AAD protocol mode.
 
+### `invalid_platform_broker_configuration`
+
+-   Invalid platform broker configuration. `allowPlatformBrokerWithDOM` requires `allowPlatformBroker` to also be set to `true`.
+
 ### `authority_mismatch`
 
 -   Authority mismatch error. Authority provided in login request or PublicClientApplication config does not match the environment of the provided account. Please use a matching account or make an interactive request to login to this authority.

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

@@ -339,6 +339,7 @@ export { BrowserConfigurationAuthErrorCodes }
 // @internal (undocumented)
 export type BrowserExperimentalOptions = {
     iframeTimeoutTelemetry?: boolean;
+    allowPlatformBrokerWithDOM?: boolean;
 };
 
 // Warning: (ae-missing-release-tag) "BrowserPerformanceClient" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -911,13 +912,10 @@ function isInIframe(): boolean;
 // @public
 function isInPopup(): boolean;
 
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // 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(domConfig: boolean, loggerOptions?: LoggerOptions, perfClient?: IPerformanceClient, correlationId?: string): Promise<boolean>;
 
 // Warning: (ae-missing-release-tag) "IWindowStorage" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -1544,8 +1542,8 @@ export type WrapperSKU = (typeof WrapperSKU)[keyof typeof WrapperSKU];
 // src/cache/LocalStorage.ts:366:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:429:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:460:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/config/Configuration.ts:213:5 - (ae-incompatible-release-tags) The symbol "experimental" is marked as @public, but its signature references "BrowserExperimentalOptions" which is marked as @internal
-// src/config/Configuration.ts:222:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
+// src/config/Configuration.ts:217:5 - (ae-incompatible-release-tags) The symbol "experimental" is marked as @public, but its signature references "BrowserExperimentalOptions" which is marked as @internal
+// src/config/Configuration.ts:226:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
 // src/event/EventHandler.ts:116:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/event/EventHandler.ts:143: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`
@@ -45,10 +45,37 @@ pca.acquireTokenSilent();
 
 No other changes are needed to support this new feature. Any user accessing your app from a supported environment will now be able to acquire device bound tokens. Users in non-supported environments will continue to acquire tokens through the traditional web-based flows.
 
-## 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 invokes 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.
+
+To enable this feature, set the `allowPlatformBrokerWithDOM` flag to true in the `experimental` section of your configuration object like so:
+
+```javascript
+const msalConfig = {
+    auth: {
+        clientId: "insert-clientId",
+    },
+    system: {
+        allowPlatformBroker: true,
+    },
+    experimental: {
+        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. The behavior and availability of `experimental` flags is subject to change at any time, without following semver rules.

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

@@ -9,6 +9,8 @@ import {
     Logger,
     Constants,
     StubPerformanceClient,
+    createClientConfigurationError,
+    ClientConfigurationErrorCodes,
 } from "@azure/msal-common/browser";
 import { name, version } from "../../packageMetadata.js";
 import {
@@ -18,50 +20,57 @@ import {
 import { PlatformAuthExtensionHandler } from "./PlatformAuthExtensionHandler.js";
 import { IPlatformAuthHandler } from "./IPlatformAuthHandler.js";
 import { PlatformAuthDOMHandler } from "./PlatformAuthDOMHandler.js";
-import { BrowserCacheLocation } from "../../utils/BrowserConstants.js";
-import { PLATFORM_AUTH_DOM_SUPPORT } from "../../cache/CacheKeys.js";
+import { createNewGuid } from "../../crypto/BrowserCrypto.js";
 
 /**
  * Checks if the platform broker is available in the current environment.
- * @param loggerOptions
- * @param perfClient
- * @param correlationId
- * @returns
+ * @param domConfig - Whether to enable platform broker DOM API support (required)
+ * @param loggerOptions - Optional logger options
+ * @param perfClient - Optional performance client
+ * @param correlationId - Optional correlation ID
+ * @returns Promise<boolean> indicating if platform broker is available
  */
 export async function isPlatformBrokerAvailable(
+    domConfig: boolean,
     loggerOptions?: LoggerOptions,
     perfClient?: IPerformanceClient,
     correlationId?: string
 ): Promise<boolean> {
     const logger = new Logger(loggerOptions || {}, name, version);
-    const cid = correlationId || "";
-
-    logger.trace("isPlatformBrokerAvailable called", cid);
 
     const performanceClient = perfClient || new StubPerformanceClient();
 
     if (typeof window === "undefined") {
-        logger.trace("Non-browser environment detected, returning false", cid);
+        logger.trace(
+            "Non-browser environment detected, returning false",
+            correlationId || createNewGuid()
+        );
         return false;
     }
 
-    return !!(await getPlatformAuthProvider(logger, performanceClient, cid));
+    return !!(await getPlatformAuthProvider(
+        logger,
+        performanceClient,
+        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}'`,
         correlationId
     );
+
     let platformAuthProvider: IPlatformAuthHandler | undefined;
     try {
         if (enablePlatformBrokerDOMSupport) {
@@ -96,22 +105,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 platform broker
  * @param logger
@@ -128,6 +121,17 @@ export function isPlatformAuthAllowed(
     authenticationScheme?: Constants.AuthenticationScheme
 ): boolean {
     logger.trace("isPlatformAuthAllowed called", correlationId);
+
+    // throw an error if allowPlatformBroker is not enabled and allowPlatformBrokerWithDOM is enabled
+    if (
+        !config.system.allowPlatformBroker &&
+        config.experimental.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

@@ -175,6 +175,10 @@ export type BrowserExperimentalOptions = {
      * Enables iframe timeout telemetry experiment for silent iframe bridge monitoring.
      */
     iframeTimeoutTelemetry?: boolean;
+    /**
+     * Flag to enable native broker support through DOM APIs in Edge
+     */
+    allowPlatformBrokerWithDOM?: boolean;
 };
 
 /**
@@ -329,6 +333,7 @@ export function buildConfiguration(
 
     const DEFAULT_EXPERIMENTAL_OPTIONS: Required<BrowserExperimentalOptions> = {
         iframeTimeoutTelemetry: false,
+        allowPlatformBrokerWithDOM: false,
     };
 
     // Throw an error if user has set OIDCOptions without being in OIDC protocol mode

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

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

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

@@ -499,13 +499,6 @@ describe("PublicClientApplication.ts Class Unit Tests", () => {
                 },
             };
 
-            jest.spyOn(
-                PlatformAuthProvider,
-                "isDomEnabledForPlatformAuth"
-            ).mockImplementation(() => {
-                return false;
-            });
-
             const getPlatformAuthProviderSpy = jest.spyOn(
                 PlatformAuthProvider,
                 "getPlatformAuthProvider"
@@ -558,7 +551,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"
@@ -571,13 +564,12 @@ describe("PublicClientApplication.ts Class Unit Tests", () => {
                 system: {
                     allowPlatformBroker: true,
                 },
+                experimental: {
+                    allowPlatformBrokerWithDOM: true,
+                },
             };
 
             pca = new PublicClientApplication(config);
-            window.sessionStorage.setItem(
-                "msal.browser.platform.auth.dom",
-                "true"
-            );
 
             const createDOMProviderSpy = stubDOMProvider(config);
             await pca.initialize();