Implement simplified E2E special URL handling for Intune MDM enrollment

[Copilot]

Overview

Adds special URL handling (msauth://, browser://) during interactive authentication to support Intune MDM enrollment flows. Implements simplified architecture with direct handler delegation (no state machine), iOS 17.4+ header support, and clean separation between business logic and UI layers.

Key Changes

Architecture

• Handler protocol pattern: MSIDLocalInteractiveController implements MSIDInteractiveWebviewHandler (13 methods) for special URL processing
• 3-property session state: brtAttemptCount, brtAcquired, responseHeaders (simplified from original 11-property design)
• Direct synchronous calls: Handler returns view actions immediately, no async state machine
• Option 3 separation: Controller creates system webviews via openSystemWebviewWithURL:, embedded webview delegates

Special URL Detection & Processing

Webview layer (MSIDOAuth2EmbeddedWebviewController):

// Detect special URLs in navigation decisions
if ([scheme isEqualToString:@"msauth"] || [scheme isEqualToString:@"browser"]) {
    self.sessionState.responseHeaders = self.lastResponseHeaders;
    MSIDWebviewAction *action = [self.handler viewActionForSpecialURL:url state:self.sessionState];
    [self executeViewAction:action];
}

Controller layer (MSIDLocalInteractiveController):

- (MSIDWebviewAction *)viewActionForSpecialURL:(NSURL *)url state:(MSIDInteractiveWebviewState *)state {
    // BRT acquisition check: NOT in broker + not acquired + < 2 attempts
    if ([self shouldAcquireBRTForSpecialURL:url state:state]) {
        [self acquireBRTTokenWithCompletion:^(BOOL success, NSError *error) {
            state.brtAttemptCount++;
            if (success) state.brtAcquired = YES;
        }];
    }
    return [self.urlResolver viewActionForSpecialURL:url state:state];
}

BRT (Broker Redirect Token) Logic

• Only acquires when NOT in broker context (isRunningInBrokerContext returns NO for local controller)
• Max 2 attempts per session (retry once on failure)
• Checks session state before each acquisition
• On failure, continues flow (doesn't block enrollment)

Intune MDM Enrollment Flow

URL sequence:

1. msauth://enroll?cpurl=... → BRT check → LoadRequest action
2. msauth://installProfile (with headers: X-Install-Url, X-Intune-AuthToken) → OpenASWebAuthSession action
3. msauth://profileInstalled → CompleteWithURL action

Header handling:

• Captured from all HTTP responses via responseHeaderHandler
• Transferred to sessionState.responseHeaders on special URL detection
• Extracted by resolver for action creation
• Applied to ASWebAuth via additionalHeaderFields (iOS 17.4+)

System Webview Delegation (Option 3)

Controller creates ASWebAuth, not embedded webview:

// MSIDLocalInteractiveController
- (void)openSystemWebviewWithURL:(NSURL *)url
                         headers:(NSDictionary *)headers
                         purpose:(MSIDSystemWebviewPurpose)purpose
                      completion:(void (^)(NSURL *, NSError *))completion {
    MSIDASWebAuthenticationSessionHandler *handler = 
        [[MSIDASWebAuthenticationSessionHandler alloc] 
            initWithParentController:self.parentController
                            startURL:url
                      callbackScheme:@"msauth"
                  useEmpheralSession:YES
                  additionalHeaders:headers];
    [handler startWithCompletionHandler:completion];
}

Webview delegates:

// MSIDOAuth2EmbeddedWebviewController
case MSIDWebviewActionTypeOpenASWebAuthSession:
    [self.handler openSystemWebviewWithURL:action.url
                                   headers:action.additionalHeaders
                                   purpose:action.purpose
                                completion:^(NSURL *callback, NSError *error) { ... }];

View Actions

Four action types executed by webview:

• LoadRequest: Load URL in WKWebView (e.g., cpurl for enrollment)
• OpenASWebAuthSession: Delegate to controller for system webview
• CompleteWithURL: Complete authentication flow
• DismissWebview: Dismiss current webview

iOS 17.4+ Header Support

Extended MSIDASWebAuthenticationSessionHandler to accept and apply additional headers:

if (@available(iOS 17.4, macOS 14.4, tvOS 17.4, watchOS 10.4, *)) {
    self.webAuthSession.additionalHeaderFields = self.additionalHeaders;
}

Enables X-Intune-AuthToken authentication during enrollment.

Testing

Added MSIDLocalInteractiveControllerSpecialURLTests.m with 31 tests covering:

• Design verification (3 properties, no state machine, handler protocol)
• BRT policy logic (broker context, session state, max attempts)
• Broker retry policy (platform-specific)
• View action resolution (URL → action mapping)
• Header capture and extraction
• E2E flows (enroll → installProfile → profileInstalled)
• Ground rules compliance (4 rules)
• Architecture verification (Option 3 separation)

Feature Flag

Controlled by specialURLHandlingEnabled property (default OFF). Enable before use:

interactiveController.specialURLHandlingEnabled = YES;
[interactiveController configureWebviewController:webviewController];

Files Changed

Implementation: 7 code files (~450 lines)

• MSIDInteractiveWebviewHandler.h (protocol)
• MSIDInteractiveWebviewState.h/m (session state)
• MSIDLocalInteractiveController.h/m (handler implementation)
• MSIDOAuth2EmbeddedWebviewController.m (detection & delegation)
• MSIDASWebAuthenticationSessionHandler.h/m (header support)

Framework: 4 files (~600 lines)

• MSIDSpecialURLViewActionResolver.h/m (URL → action mapping)
• MSIDWebviewAction.h/m (action model)

Tests: 3 files (~1000 lines)

• MSIDLocalInteractiveControllerSpecialURLTests.m (31 E2E tests)
• MSIDSpecialURLViewActionResolverTests.m (resolver tests)
• MSIDWebviewActionTests.m (action model tests)

Documentation: SIMPLIFIED_IMPLEMENTATION_GUIDE.md (1900+ lines with diagrams)

Status

92% complete (12/13 components). Remaining: BRT token acquisition implementation (~50-100 lines).

Original prompt

Add placeholder framework for special URL handling in embedded WKWebView using a controller-action state machine and MSIDWebviewAction view actions.

Repository: AzureAD/microsoft-authentication-library-common-for-objc
Base branch: dev

Background / Motivation

We need a scaffolding (placeholders) for a new architecture to handle msauth:// and browser:// redirects in embedded WKWebView. This design separates:

• Controller actions (state-machine-driven async operations such as AcquireBRTOnce, RetryInBroker)
• View actions (MSIDWebviewAction) that the embedded webview controller executes

No production behavior changes are required in this PR; it should compile and be safe to land without enabling the new flow.

Deliverables

1) Add MSIDWebviewAction placeholder (new)

Create a minimal view-action model:

• MSIDWebviewActionType enum (at least: Noop, LoadRequestInWebview, OpenASWebAuthenticationSession, OpenExternalBrowser, CompleteWithURL, FailWithError)
• MSIDSystemWebviewPurpose enum including at least MSIDSystemWebviewPurposeInstallProfile and MSIDSystemWebviewPurposeUnknown
• MSIDWebviewAction class with readonly properties: type, request, url, purpose, error
• Convenience constructors:
  • +noopAction
  • +loadRequestAction:(NSURLRequest *)request
  • +openASWebAuthSessionAction:(NSURL *)url purpose:(MSIDSystemWebviewPurpose)purpose
  • +openExternalBrowserAction:(NSURL *)url
  • +completeWithURLAction:(NSURL *)url
  • +failWithErrorAction:(NSError *)error
• Documentation comment: ephemeral ASWebAuthenticationSession behavior is implied by purpose (InstallProfile => ephemeral) and will be enforced by system webview handoff handler.

2) Add controller-action state machine placeholders (new)

Add these new types (placeholders with documentation and minimal logic):

• MSIDInteractiveWebviewState
  • session flags for BRT gate: brtGateEncountered, brtAttempted, brtAcquired
  • per-intercept: pendingURL, queryParams, isGateScheme, isRunningInBrokerContext
  • policy: brtFailurePolicy enum (Continue/Fail)
  • transition: transferredToBroker
• MSIDInteractiveWebviewHandler protocol
  • -isRunningInBrokerContext
  • policy hooks:
    • -shouldAcquireBRTForSpecialURL:state:
    • -brtFailurePolicyForSpecialURL:state:
    • -shouldRetryInBrokerForSpecialURL:state:
  • action implementations:
    • -acquireBRTTokenWithCompletion:
    • -genericBrtError
    • -retryInteractiveRequestInBrokerContextForURL:completion:
    • -dismissEmbeddedWebviewIfPresent
  • view resolver hook:
    • -viewActionForSpecialURL:state:
  • telemetry:
    • -handleWebviewResponseForTelemetry:
• MSIDInteractiveWebviewStateMachine
  • -initWithHandler:
  • -handleSpecialURL:navigationAction:completion: returning MSIDWebviewAction *
  • Implements broker-style nextControllerActionForState: selection and runUntilStable loop.
  • Must be safe and minimal: default behavior should return CompleteWithURL or Noop via handler/resolver; no wiring into production code.

3) Add controller action placeholders (new)

• Base class or protocol for controller actions (minimal)
• MSIDAcquireBRTOnceControllerAction
  • calls handler acquireBRTTokenWithCompletion: once; sets state flags
• MSIDRetryInBrokerControllerAction
  • calls handler retryInteractiveRequestInBrokerContextForURL:completion:
  • on success sets state.transferredToBroker = YES and calls dismissEmbeddedWebviewIfPresent

4) Add MSIDSpecialURLViewActionResolver placeholder (new)

Add a helper that maps special URLs to MSIDWebviewAction (placeholder semantics):

• msauth://enroll?cpurl=... -> LoadRequestInWebview (construct request from cpurl; placeholder for headers/params)
• msauth://compliance?cpurl=... -> LoadRequestInWebview
• msauth://installProfile?url=...&requireASWebAuthenticationSession=true -> OpenASWebAuthenticationSession with purpose InstallProfile
• msauth://profileComplete -> CompleteWithURL (retry handled by controller action policy)
• browser://... -> CompleteWithURL
  Include TODO comments for:
• adding extra headers/query params for enroll/compliance
• telemetry header parsing
• enforcing ephemeral by purpose in system webview handoff handler

5) Safety / Non-breaking

• Do NOT change existing behavior paths; do not wire the embedded WKWebView controller to use the new state machine by default.
• Keep the new framework self-contained and compile-able.

6) Tests (if feasible)

If the repo has an existing unit test target, add minimal tests validating:

• MSIDWebviewAction constructors
• resolver mapping for installProfile URL produces OpenASWebAuthenticationSession + InstallProfile purpose

Notes

• Keep Objective-C style consistent with repo.
• Add header docs for intended end-to-end invocation.
• Ensure everything builds on iOS targets.

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.