feat: macOS brokered authentication support by dggsax · Pull Request #452 · AzureAD/microsoft-authentication-cli

dggsax · 2026-04-08T17:27:33Z

Summary

Adds macOS brokered authentication support via MSAL.NET, NativeInterop, and the macOS Enterprise SSO Extension (deployed through Company Portal).

What this does

Broker auth on macOS — opt-in via --mode broker. Supports interactive broker (first run) and silent broker (subsequent runs via persisted account).
Company Portal version gating — requires CP >= 5.2603.0. Clear error message with CP path if version is insufficient.
Main thread dispatch — broker interactive calls are dispatched to the main thread via MacMainThreadScheduler, as required by MSAL on macOS.
Account persistence — DefaultAccountStore persists the authenticated username to ~/.azureauth/default_account_{tenant}_{client}.json for silent re-auth (since OperatingSystemAccount is not supported on macOS).
Browser fallback — when both --mode broker --mode web are specified, falls back to browser auth if broker fails.
NuGet upgrades — MSAL 4.65.0 → 4.83.1, added NativeInterop v0.20.3.

Key design decisions

Broker is opt-in on macOS (--mode broker) — apps with broker-required Conditional Access policies (token protection, error 530084) will hang indefinitely on web auth, so we do not include broker in the default mode.
No OperatingSystemAccount — this Windows-only concept does not work on macOS. We persist the username and look up the IAccount from the MSAL cache instead.
SSO Extension check disabled — app-sso -l returned empty on test devices yet broker worked fine. The check is kept as commented-out code for future investigation.

Testing

✅ All 373 unit tests pass (95 AdoPat + 109 AzureAuth + 169 MSALWrapper)
✅ Functional end-to-end testing verified with Work IQ 3P Graph app registration
- Interactive broker → account picker → token acquired in ~3.6s
- Silent broker → cached account → token acquired in ~1s
✅ New unit tests: DefaultAccountStoreTest (8 tests), BrokerMacOSTest (6 tests)
✅ Functional test script at bin/mac/test-macos-broker.sh

Files changed

New files:

src/MSALWrapper/DefaultAccountStore.cs — account username persistence
src/MSALWrapper.Test/DefaultAccountStoreTest.cs — 8 unit tests
src/MSALWrapper.Test/AuthFlow/BrokerMacOSTest.cs — 6 unit tests
bin/mac/test-macos-broker.sh — functional test script
bin/mac/swap-cp.sh — CP version swap utility for testing

Modified files:

src/MSALWrapper/MSALWrapper.csproj — NuGet upgrades
src/MSALWrapper/AuthFlow/Broker.cs — major rewrite for cross-platform
src/MSALWrapper/AuthFlow/AuthFlowFactory.cs — broker availability gating
src/MSALWrapper/PlatformUtils.cs — CP version detection, macOS checks
src/MSALWrapper/AuthMode.cs — broker opt-in on non-Windows
src/MSALWrapper/Constants.cs — macOS broker redirect URI
src/AzureAuth/Program.cs — main thread scheduler pattern
src/AzureAuth/Commands/CommandAad.cs — --mode broker option
docs/usage.md — macOS broker prerequisites and redirect URI config
README.md — feature matrix updated

Prerequisites for broker auth

Company Portal >= 5.2603.0 installed
Device MDM-compliant
App registration configured with redirect URI: msauth.com.msauth.unsignedapp://auth

Add support for macOS Enterprise SSO Extension brokered authentication, bringing feature parity with Windows WAM broker support. Key changes: - Upgrade MSAL 4.65.0 → 4.83.1, add NativeInterop v0.20.3 - Extend Broker auth flow with macOS-specific PCA config, account resolution, and browser fallback - Add DefaultAccountStore to persist account username for silent auth (OperatingSystemAccount not supported on macOS) - Add MacMainThreadScheduler message loop in Program.cs - Extend AuthMode enum and CLI parsing to support broker on macOS - Update docs with macOS broker prerequisites and redirect URI config Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Skip macOS broker auth if Company Portal is not installed or is below version 2603 (which added redirect_uri validation fix for unsigned apps). Falls back to web auth transparently in those cases. - Add IsMacOSBrokerAvailable() to IPlatformUtils/PlatformUtils - AuthFlowFactory uses IsMacOSBrokerAvailable() as gatekeeper - Broker.cs still uses IsMacOS() for runtime behavior (fallback, persist) - Reads CP version from Info.plist via 'defaults read' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

On macOS, broker is no longer included in default auth modes. Users must explicitly pass '--mode broker' to use it. If broker is requested but Company Portal >= 5.2603.0 is not installed, AuthFlowFactory throws a clear InvalidOperationException instead of silently falling through to web auth (which hangs for apps with broker-required CA policies like token protection). - AuthMode.Default on non-Windows: Broker|Web -> Web - AuthFlowFactory: explicit error when broker requested but CP unavailable - New test: BrokerRequested_Mac_CP_Unavailable_Throws Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Include CP path in broker unavailable error message - Add trace-level logging: CP path, raw version output, stderr, parsed version parts (major/release/build) - Expose CompanyPortalAppPath as public const for error messages - Update test script to reflect broker-opt-in behavior: new tests for broker+web combined, trace diagnostics, reordered Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The macOS broker requires AcquireTokenInteractive to run on the main thread. Program.cs starts the MacMainThreadScheduler message loop on main and dispatches CLI work to Task.Run, but the broker interactive calls were still executing on the background thread. Now GetTokenInteractive/WithClaims dispatch through MacMainThreadScheduler.RunOnMainThreadAsync when running on macOS with the scheduler active (IsRunning check prevents deadlock in tests). Also: improved CP diagnostics trace logging and included CP path in the broker unavailable error message. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Check 'app-sso -l' for registered Enterprise SSO Extensions before attempting broker auth. If no extensions are registered (MDM profile not applied), gives a clear error instead of a cryptic broker failure. Designed for easy revert: - Set AZUREAUTH_SKIP_SSO_CHECK=1 to bypass the check entirely - If app-sso fails or isn't available, assumes broker may work (non-fatal) - The check is a single method call in CheckMacOSBrokerAvailable() Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Move test-macos-broker.sh and swap-cp.sh from repo root to bin/mac/ alongside existing macOS build scripts. Update REPO_ROOT to resolve two levels up from the new location. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add AZUREAUTH_TEST_VERBOSITY env var (default: debug) to control log level across all tests (Test 3 always uses trace) - Comment out SSO Extension check (confirmed unnecessary for broker) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

Match the existing Windows pattern where broker is silently skipped on unsupported platforms (e.g., Windows Server). On macOS, if broker is requested but Company Portal is insufficient, log a warning and continue to the next flow (Web, DeviceCode, etc.) instead of throwing. This means '--mode broker --mode web' will fall through to web when CP is unavailable, and '--mode broker' alone will try CachedAuth only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Web auth hangs for this broker-required app (token protection CA policy), so comment out Tests 2 and 5. Add cache clear + broker interactive re-prompt cycle (Tests 6-8) to verify full broker lifecycle: authenticate → clear → re-authenticate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

ChristopherJMiller · 2026-04-09T17:02:11Z

can this script have a comment at the top describing what it's for testing wise and why it's needed?

ChristopherJMiller · 2026-04-09T17:04:23Z

+    --resource "$RESOURCE" \
+    --mode broker --output json --verbosity "$VERBOSITY"
+
+# ── Test 2: Broker + web combined — COMMENTED OUT ─────────────


for a checked in testing suite is it worth keeping this commented out test?

ChristopherJMiller · 2026-04-09T17:05:40Z


-            var subject = new[] { AuthMode.Web, AuthMode.DeviceCode };
+            // Default on macOS is Web only (broker is opt-in).
+            var subject = new[] { AuthMode.Web };


should this be an os specific test?

ChristopherJMiller · 2026-04-09T17:13:29Z

+                        return false;
+                    }
+
+                    // TODO: Re-enable once we confirm SSO Extension registration is required.


we may want to track this in an issue so it's not forgotten about

siddharthpaudwal · 2026-04-10T11:49:24Z

 #else
        public const string AuthModeHelperText = $@"Authentication mode. Repeated invocations allowed
-[default: web]
+[default: broker, then web]


just like windows it has condition -
#if PlatformWindows
[default: broker, then web]

can we add the same for MAC ?
broker may impact linux machines

dggsax and others added 11 commits April 6, 2026 16:30

chore: move macOS test scripts to bin/mac/

f5c85d9

Move test-macos-broker.sh and swap-cp.sh from repo root to bin/mac/ alongside existing macOS build scripts. Update REPO_ROOT to resolve two levels up from the new location. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs: add usage examples to test script header

0d98f66

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

ChristopherJMiller requested changes Apr 9, 2026

View reviewed changes

siddharthpaudwal reviewed Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: macOS brokered authentication support#452

feat: macOS brokered authentication support#452
dggsax wants to merge 11 commits intoAzureAD:mainfrom
dggsax:feature/macos-brokered-auth

dggsax commented Apr 8, 2026

Uh oh!

ChristopherJMiller Apr 9, 2026

Uh oh!

ChristopherJMiller Apr 9, 2026

Uh oh!

ChristopherJMiller Apr 9, 2026

Uh oh!

ChristopherJMiller Apr 9, 2026

Uh oh!

siddharthpaudwal Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dggsax commented Apr 8, 2026

Summary

What this does

Key design decisions

Testing

Files changed

Prerequisites for broker auth

Uh oh!

ChristopherJMiller Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

ChristopherJMiller Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

ChristopherJMiller Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

ChristopherJMiller Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

siddharthpaudwal Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants