allow_broker becomes conditional per platform

Author: rayluo

msal/application.py

@@ -450,7 +450,7 @@ def __init__(
             This factor would become mandatory
             if a tenant's admin enables a corresponding Conditional Access (CA) policy.
             The broker's presence allows Microsoft identity platform
-            to have higher confidence that the tokens are being issued to your device,
+            to have more confidence that the tokens are being issued to your device,
             and that is more secure.
 
             An additional benefit of broker is,
@@ -459,29 +459,24 @@ def __init__(
             so that your broker-enabled apps (even a CLI)
             could automatically SSO from a previously established signed-in session.
 
-            This parameter defaults to None, which means MSAL will not utilize a broker.
-            If this parameter is set to True,
-            MSAL will use the broker whenever possible,
-            and automatically fall back to non-broker behavior.
-            That also means your app does not need to enable broker conditionally,
-            you can always set allow_broker to True,
-            as long as your app meets the following prerequisite:
+            This parameter defaults to None, which means MSAL will not utilize a broker,
+            and your end users will have the traditional browser-based login experience.
 
-            * Installed optional dependency, e.g. ``pip install msal[broker]>=1.20,<2``.
-              (Note that broker is currently only available on Windows 10+)
+            You can set it to True, based on the OS platform.
+            Currently, MSAL supports broker on Windows 10+, and errors out on others.
+            So, for example, you can do ``allow_broker = sys.platform=="win32"``.
 
-            * Register a new redirect_uri for your desktop app as:
-              ``ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id``
-
-            * Tested your app in following scenarios:
+            In order to allow broker, your app must also meet the following prerequisite:
 
-              * Windows 10+
+            * Install optional dependency, e.g. ``pip install msal[broker]>=1.20,<2``.
 
-              * PublicClientApplication's following methods::
-                acquire_token_interactive(), acquire_token_by_username_password(),
-                acquire_token_silent() (or acquire_token_silent_with_error()).
+            * Register a new redirect_uri for your desktop app as:
+              ``ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id``
 
-              * AAD and MSA accounts (i.e. Non-ADFS, non-B2C)
+            * Test your app with AAD and MSA accounts (i.e. Non-ADFS, non-B2C)
+              in PublicClientApplication's following methods:
+              acquire_token_interactive(), acquire_token_by_username_password(),
+              acquire_token_silent() (or acquire_token_silent_with_error()).
 
             New in version 1.20.0.
         """
@@ -549,6 +544,9 @@ def __init__(
                     )
             else:
                 raise
+
+        if allow_broker and sys.platform != "win32":
+            raise ValueError("allow_broker=True is only supported on Windows")
         is_confidential_app = bool(
             isinstance(self, ConfidentialClientApplication) or self.client_credential)
         if is_confidential_app and allow_broker:

sample/interactive_sample.py

@@ -33,7 +33,7 @@
 # Create a preferably long-lived app instance which maintains a token cache.
 app = msal.PublicClientApplication(
     config["client_id"], authority=config["authority"],
-    #allow_broker=True,  # If opted in, you will be guided to meet the prerequisites, when applicable
+    #allow_broker=sys.platform in ["win32"],  # If opted in, you will be guided to meet the prerequisites, when applicable
                          # See also: https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-desktop-acquire-token-wam#wam-value-proposition
     # token_cache=...  # Default cache is in memory only.
                        # You can learn how to use SerializableTokenCache from

tests/test_application.py

@@ -625,3 +625,17 @@ def test_organizations_authority_should_emit_warnning(self):
         self._test_certain_authority_should_emit_warnning(
             authority="https://login.microsoftonline.com/organizations")
 
+
+class TestBrokerAllowance(unittest.TestCase):
+    def test_opt_in_for_broker_should_error_out_on_nonsupported_platforms(self):
+        supported_platforms = ["win32"]
+        if sys.platform in supported_platforms:
+            try:
+                PublicClientApplication("client_id", allow_broker=True)
+                # It would either create an app instance successfully
+            except ImportError:
+                pass  # Or detect the absence of MsalRuntime
+        else:
+            with self.assertRaises(ValueError):  # We decide to error out
+                PublicClientApplication("client_id", allow_broker=True)
+