Sidestepped the need to provide a HWND while using a broker (on Windows)

[rayluo]

Context: Recent versions of MSAL Python supports enabling a broker (currently on Windows platform only), but this mechanism requires the caller to provide a parent window handle a.k.a. HWND.

@craigwalton mentioned,

Yes, I appreciate that using WAM results in a better UX and the cancellation error. Unfortunately, we haven't been able to come up with a reliable way of obtaining a suitable Windows HWND to pass to MSAL given our library is expected to be run in numerous different environments and we're hesitant about requiring our library users to provide a HWND.

and

Just in case this is of interest to you or other readers:

In the meantime, we've opted to:

• first try to acquire a token silently* using the a broker-enabled PublicClientApplication
• if that requires user interaction, fall back to using a PublicClientApplication without broker (i.e. via browser).

We prevent the broker from becoming interactive by either by:

• setting prompt="none" in acquire_token_interactive() OIDC Spec or
• by raising an exception (which we catch) via the on_before_launching_ui callback. We pass in the useful PublicClientApplication.CONSOLE_WINDOW_HANDLE as the parent_window_handle, despite knowing it will never be used.

This is a similar approach to what we've taken in another library which uses MSAL for .NET. We've again sidestepped the need to provide a HWND. The main difference being that the .NET MSAL library has explicit support for acquiring a token silently from the broker via PublicClientApplication.AcquireTokenSilent(<scopes>, PublicClientApplication.OperatingSystemAccount). It raises an MsalUiRequiredException when it needs interaction, in which case we fall back to a non-broker approach.

Thanks again for your suggestions and support.

[rayluo]

It is eye-opening to see our customers creatively went extra mile to bypass the requirement of an HWND. We will take that into consideration, when/if we revisit our design decision of requiring a HWND.

Meanwhile, your workaround above can reach your goal of bypassing the requirement of needing a HWND. But we would like to point out some subtlety.

• There is nothing wrong with using the prompt=none pattern in itself.

  We prevent the broker from becoming interactive by either by:

  1. setting prompt="none" in acquire_token_interactive() OIDC Spec or
  2. by raising an exception (which we catch) via the on_before_launching_ui callback. We pass in the useful PublicClientApplication.CONSOLE_WINDOW_HANDLE as the parent_window_handle, despite knowing it will never be used.

  The second approach is too hacky. You would rather stick with the first approach, which is the equivalent of MSAL .Net's explicit support for acquiring a token silently from the broker via PublicClientApplication.AcquireTokenSilent(<scopes>, PublicClientApplication.OperatingSystemAccount). As @craigwalton correctly pointed out, the prompt="none" is the standard way of using a default account, defined by OIDC specs.

In the meantime, we've opted to:

• first try to acquire a token silently* using the a broker-enabled PublicClientApplication
• if that requires user interaction, fall back to using a PublicClientApplication without broker (i.e. via browser).

• PublicClientApplication(..., enable_broker_on_windows=True).acquire_token_silent(...) will get you a token only when there is an account previously established, either logically by a PublicClientApplication(..., enable_broker_on_windows=True).acquire_token_interactive(...), or opportunistically by the end user already signed into via the broker somehow.

• In particular, the expected recovery strategy of an PublicClientApplication(..., enable_broker_on_windows=True).acquire_token_silent(...) failure is to call PublicClientApplication(..., enable_broker_on_windows=True).acquire_token_interactive(...). But since you now purposely blend broker mode and non-broker mode together to sidestep the broker behavior in your acquire_token_interactive() code path, that interaction-via-browser attempt would be successful on the spot, but the token acquired without using broker would not be as "good" as the token acquired via broker. If/when the tenant admin eventually enables some conditional access policy (CAP) that requires tokens to be issued for user's broker-enabled device, the non-broker tokens would not be useful. And your app risks stuck in a non-recoverable user experience loop of "interactively sign-in successfully -> token rejected -> interactive sign-in successfully -> token rejected".

• Lastly, since you choose to have a broker-enabled PublicClientApplication and a broker-disabled PublicClientApplication side-by-side, your use case falls into a situation that we would recommend you to reuse same token cache across your different PublicClientApplication instances, demonstrated in this sample.

[craigwalton]

Thank you Ray for taking the time to open this new issue and for your detailed responses to each of my points - there is some very valuable knowledge here.

I had not considered that the broker-acquired token would be "better" (in case of particular security policies) than the browser acquired one.

I will look into using a shared msal.TokenCache() between the two PublicClientApplication instances.

Going forward, on balance, it sounds like using the broker (interactively if required) when available is the best practice with the fewest pitfalls. I'll keep an eye out for any package updates which somehow relinquish the need to provide a HWND, or approaches taken by fellow users to get an appropriate HWND.

For info, we had experimented with PublicClientApplication.CONSOLE_WINDOW_HANDLE (against recommendation of the docs: "use msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE when and only when your application is a console app"), but this can result in the broker UI being shown under other windows.

We also considered using the win32gui package's GetForegroundWindow(), but the foreground window isn't necessarily the window which you want the broker to be shown over e.g. sometimes the user is browsing Outlook at the moment the Python script tries to acquire a token.

[rayluo]

For info, we had experimented with PublicClientApplication.CONSOLE_WINDOW_HANDLE (against recommendation of the docs: "use msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE when and only when your application is a console app"), but this can result in the broker UI being shown under other windows.

That is kind of a known behavior. The CONSOLE_WINDOW_HANDLE is only expected to work in most console scenario. But if an app is a GUI app, the assumption is that the app developer shall know what HWND to provide.

That being said, since @craigwalton you mentioned that you are working on a library, so, logically your library won't know whether the current app is a GUI app, then your library seems to have to expose this HWND parameter to your downstream apps.

FWIW, MSAL's downstream library, Azure Identity for Python, is in the same boat as you. They ended up spinning off another package to for broker-only API, and the original package for non-broker API.

[bgavrilMS]

Another approach, which Git Credential Manger uses, is:

• accept a window handle as an optional input paramter. If specified, use it.
• otherwise, try console window handle (if it can be detected) as per https://learn.microsoft.com/en-us/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam#parent-window-handles
• otherwise, use GetForegroundWindow

[craigwalton]

Thank you both. Interesting to see what Azure Identity for Python have done.

The Git Credential Manager approach sounds like a sensible order of options for us to consider.

Perhaps once we have a better grasp on what environments our users will be most commonly using our library in, we can revisit. (Likely: python interpreter, Jupyter notebook (kernel local or remote), GUI app.)

[rayluo]

Another approach, which Git Credential Manger uses, is:

• accept a window handle as an optional input paramter. If specified, use it.

• otherwise, try console window handle (if it can be detected) as per https://learn.microsoft.com/en-us/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam#parent-window-handles

• otherwise, use GetForegroundWindow

Thanks for sharing the GCM approach, @bgavrilMS . I have two follow-up questions.

• MSAL Python was instructed to use this similar algorithm but with slightly different function calls. Is that GCM algorithm better, so that MSAL Python shall also adopt it?

• "accept a window handle as an optional input parameter". Whether to make the window handle parameter optional, that was the crux of all the dilemma and debate. MSAL Python currently uses a middle ground, in which the downstream libraries/apps can explicitly opt in to use a "console mode" (by specifying a flag CONSOLE_WINDOW_HANDLE). It is up to the downstream libraries to go one step further by making the window handle optional by defaulting to use that flag, at the cost of sometimes detecting wrong window handle, which was already experienced by @craigwalton:

  For info, we had experimented with PublicClientApplication.CONSOLE_WINDOW_HANDLE (against recommendation of the docs: "use msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE when and only when your application is a console app"), but this can result in the broker UI being shown under other windows.
  We also considered using the win32gui package's GetForegroundWindow(), but the foreground window isn't necessarily the window which you want the broker to be shown over e.g. sometimes the user is browsing Outlook at the moment the Python script tries to acquire a token.

  My question is, does GCM not run into those kind of issues in their "optional, default to console mode" approach?