Add generic webview session manager for enrollment and registration flows

[Copilot]

Overview

Implements extensible webview session management for enrollment flows (Intune, MDM, device registration). Enables code sharing between MSIDLocalInteractiveController (IdentityCore) and MSIDBrokerInteractiveController (broker repo) via composition.

Changes

Core Implementation

• MSIDWebviewSessionManager - Standalone manager class with all session logic
• MSIDWebviewSessionControlling - Protocol for controller integration
• Direct usage pattern (no category wrapper) - same code in local and broker contexts

Helper Types

• MSIDWebviewAction - Action object returned from async URL callbacks
• MSIDWebviewResponseEvent - Structured response events from webview navigation
• MSIDBRTAttemptTracker - Tracks BRT acquisition attempts (max 2 per session)
• MSIDResponseHeaderStore - Session-level header storage with case-insensitive lookup

Webview Extensions

• MSIDAADOAuthEmbeddedWebviewController - HTTP 302 response header capture, async action callbacks for msauth:// and browser:// URLs
• MSIDASWebAuthenticationSessionHandler - Additional header support (iOS 17.4+)
• MSIDSystemWebViewControllerFactory - Header injection plumbing

Configuration

• capturedHeaderKeys - Configurable header capture (defaults: x-ms-clitelem, x-install-url, authorization)
• customURLActionHandler - Pluggable block for custom URL handling
• Built-in handlers for common patterns: enroll, installProfile, profileInstalled

Usage

// In any controller (local or broker)
@interface YourController : MSIDBaseRequestController <MSIDWebviewSessionControlling>
@property (nonatomic, strong) MSIDWebviewSessionManager *webviewSessionManager;
@end

// Init
_webviewSessionManager = [[MSIDWebviewSessionManager alloc] initWithController:self];

// Configure webview
[self.webviewSessionManager configureWebview:webviewController];

// Optional: Custom headers
self.webviewSessionManager.capturedHeaderKeys = [NSSet setWithArray:@[@"x-custom-token"]];

// Optional: Custom URL handler
self.webviewSessionManager.customURLActionHandler = ^(NSURL *url, void(^completion)(MSIDWebviewAction *)) {
    // Custom logic with fallback to built-in handlers
};

// Access captured state
NSString *token = [self.webviewSessionManager.responseHeaderStore headerForKey:@"x-custom-token"];

Architecture

MSIDWebviewSessionManager (455 lines)
├── BRT attempt tracking (max 2 per session)
├── Header capture from HTTP 302 responses
├── Custom URL action routing
└── Webview callback wiring

Used directly by:
├── MSIDLocalInteractiveController
└── MSIDBrokerInteractiveController (broker repo)

Testing

• Unit tests for all helper types
• Manager independently testable
• Integration pattern validated

Documentation

• docs/intune-enrollment-webview-flow.md - Architecture and sequence diagrams
• MANAGER_USAGE_GUIDE.md - Integration guide
• FINAL_ARCHITECTURE.md - Design overview

Original prompt

Implement updates to support Intune enrollment flow requirements in embedded/system webviews:

Requirements:

1. Best-effort BRT acquisition attempts (non-broker context only):

   • Attempt BRT acquisition on the first redirect with scheme msauth:// or browser:// in a single token acquisition request session.
   • If that first attempt fails and another msauth:// or browser:// redirect happens in the same session, attempt BRT acquisition once more.
   • Total maximum 2 attempts per token acquisition session.
   • BRT acquisition failure must NOT block the flow; proceed regardless while recording telemetry/state.
   • BRT logic must be handled by InteractiveController (not webview controller).

2. Response header capture:

   • Capture selected headers across ALL WKWebView navigation responses throughout the flow: x-ms-clitelem, X-Intune-AuthToken, X-Install-Url.
   • Headers are present on HTTP 302 responses; store them in a session-level header store so they can be used later when custom-scheme redirects occur.
   • Webview controller should forward structured response events to InteractiveController; InteractiveController updates telemetry and stores headers.

3. Special URL semantics:

   • Intercept msauth:// and browser:// navigation actions in embedded WKWebView and delegate handling to InteractiveController via async callback that returns an action object.
   • Implement handlers for msauth://enroll?cpurl=..., msauth://installProfile (uses stored 302 headers for install URL + token), and msauth://profileInstalled (from ASWebAuthenticationSession).
   • For installProfile: open ASWebAuthenticationSession using URL from X-Install-Url and attach X-Intune-AuthToken as an additional header field.
   • For profileInstalled: if broker context is available, continue broker flow; otherwise retry token request in broker context (per existing architecture).

4. System webview headers:

   • Extend MSIDASWebAuthenticationSessionHandler and MSIDSystemWebViewControllerFactory plumbing to accept optional additional header fields and apply them to ASWebAuthenticationSession when supported by OS.

5. Add a comprehensive design document with:

   • High-level architecture diagrams (ASCII/mermaid)
   • Sequence/flow diagrams for token request, enrollment, install profile handoff, and profileInstalled continuation.
   • Wiring information: which callbacks, which classes own which state, session lifetime.
   • Notes on header capture across 302 responses and correlation strategy.
   • BRT attempt state machine.

Repository: AzureAD/microsoft-authentication-library-common-for-objc
Base branch: dev
Key files (existing):

• IdentityCore/src/webview/embeddedWebview/MSIDAADOAuthEmbeddedWebviewController.m
• IdentityCore/src/webview/systemWebview/session/MSIDASWebAuthenticationSessionHandler.h/.m
• IdentityCore/src/webview/systemWebview/session/MSIDSystemWebViewControllerFactory.m

Implement new helper types as needed:

• MSIDWebviewAction (+ additionalHeaders)
• MSIDWebviewResponseEvent
• MSIDBRTAttemptTracker
• MSIDResponseHeaderStore

Also update InteractiveControllers (MSIDLocalInteractiveController and broker interactive controller as applicable) to wire callbacks and implement logic.

Include a Markdown design doc under a suitable docs/ path (e.g., docs/intune-enrollment-webview-flow.md).

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.

[azure-pipelines]

This pull request does not update changelog.txt.

Please consider if this change would be noticeable to a partner or user and either update changelog.txt or resolve this conversation.