Purpose: Support Windows broker-backed silent token acquisition from WSL

[hcoona]

Purpose

This proposal suggests adding WSL-specific broker support so AzureAuth running inside WSL can use Windows Auth Broker integration through a Windows-side AzureAuth helper.

The goal is to improve the authentication experience for WSL users by allowing them to reuse existing Windows broker state and acquire tokens silently when possible, without changing the current default auth behavior for non-Windows platforms.

Expected behavior

When AzureAuth runs inside WSL and broker mode is explicitly requested through the existing --mode broker option, AzureAuth should attempt to acquire a token through Windows Auth Broker integration by delegating to a compatible Windows AzureAuth executable.

If Windows broker-backed silent acquisition succeeds, the WSL invocation should return the token successfully.

If the Windows helper is unavailable, incompatible, or unable to acquire a token silently, AzureAuth should follow the existing fallback semantics for the requested auth modes. For example, if only broker mode was requested, AzureAuth should fail gracefully rather than unexpectedly launching a different interactive flow. If additional modes were requested, AzureAuth should continue through the requested flow sequence.

Current behavior

WSL currently appears to be treated as regular Linux. Broker flow selection is platform-gated for Windows and macOS, and there does not appear to be WSL-specific logic that bridges to the Windows broker.

As a result, AzureAuth running in WSL cannot use Windows Auth Broker integration, even though WSL can execute Windows .exe files. Users may need to rely on Linux web or device code flows instead of reusing the Windows broker session that may already exist on the host.

Detailed proposal

Add a WSL-specific broker path that delegates silent token acquisition to a Windows-side AzureAuth executable.

The high-level model would be similar to helper patterns used by developer tooling in WSL: the WSL process detects that it is running under WSL, locates a Windows helper executable, and invokes it as a subprocess. The Windows helper performs broker-backed token acquisition through Windows Auth Broker and returns the token result to the WSL caller through a stable machine-readable contract.

Key design points:

1. Detect WSL explicitly rather than treating it as generic Linux for broker flow selection.
2. Use the existing --mode broker request as the trigger for this behavior.
3. Keep the feature opt-in initially; this proposal does not require changing the current non-Windows default of web auth.
4. Locate a compatible Windows AzureAuth helper through a safe and documented lookup strategy.
5. Avoid executing an untrusted helper accidentally; helper discovery should account for version compatibility and trust boundaries.
6. Invoke the Windows helper in a silent-only broker path so WSL invocations do not unexpectedly trigger Windows UI.
7. Return the result using a stable machine-readable contract with clear stdout/stderr separation, exit codes, and no token leakage through logs.
8. Handle common WSL edge cases, including WSL1 vs. WSL2, Windows interop being disabled, missing Windows installation, path translation issues, and helper version mismatch.
9. Preserve existing --domain, tenant, client, and scope behavior where applicable.
10. Document setup requirements, fallback behavior, and compatibility expectations between the WSL and Windows AzureAuth installations.

Possible implementation approach and estimated effort

Estimated effort: approximately 2-3 senior engineer days.

Rough breakdown:

1. WSL detection and Windows helper discovery: 0.5 day
2. Windows helper invocation and silent-only broker contract: 1 day
3. Auth flow wiring, fallback behavior, and error handling: 0.5-1 day
4. Tests, documentation, and manual validation in WSL: 0.5 day

This assumes the feature stays opt-in through the existing broker mode and does not change default auth flow behavior.

The estimate may increase if the implementation requires stronger version negotiation between WSL and Windows AzureAuth installations, a broader helper protocol, or additional security hardening around helper discovery.

Suggested acceptance criteria

1. AzureAuth can detect WSL separately from generic Linux.
2. --mode broker from WSL attempts Windows broker delegation when a compatible Windows helper is available.
3. No unexpected interactive Windows UI is launched during the WSL broker attempt.
4. Helper-not-found, helper-incompatible, silent-token-unavailable, timeout, and cancellation cases are handled cleanly.
5. Existing Linux, macOS, and Windows behavior remains unchanged.
6. Tests cover WSL detection, helper discovery, successful silent acquisition, helper failure, fallback behavior, and output parsing.
7. Documentation explains setup, compatibility expectations, and fallback behavior.

Request for feedback

Would the owners be open to this direction?

In particular, I would appreciate feedback on:

1. Whether invoking a Windows AzureAuth helper from WSL is an acceptable architecture for this project.
2. Whether WSL broker support should remain opt-in through the existing broker mode initially.
3. What helper discovery and compatibility requirements would be acceptable from a security and supportability perspective.