Add design documentation for Mobile MDM Onboarding & In-App Enrollment Flow

[Copilot]

Documents the architecture and implementation details of PR #1689's in-app MDM profile installation and enrollment support for MSAL Objective-C.

Added

• Design document at docs/design/mobile-mdm-onboarding-design.md covering:
  • Architecture flow for embedded WKWebView → ASWebAuthenticationSession transitions
  • New components: navigation action resolver, transition coordinator, MDM response models
  • Modified components: local interactive controller, AAD webview controller, request/response pipeline
  • msauth:// URL scheme routing for profile installation and enrollment completion
  • Broker Refresh Token (BRT) acquisition strategy
  • Post-enrollment handoff to SSO Extension
  • Risk assessment and known incomplete items (BRT placeholder, dual transition paths, no tests)

Structure

docs/
└── design/
    └── mobile-mdm-onboarding-design.md  # 266 lines, 11 sections

Document includes flow diagrams, component tables, and files changed summary for the 38-file, +2,814/-37 line change in PR #1689.

Original prompt

Add a comprehensive design document as a markdown file to the repository that documents the changes introduced in PR #1689 (veena/mob_onb2 branch). The design doc should be placed at docs/design/mobile-mdm-onboarding-design.md and contain the following content exactly:

---

Design Document: Mobile MDM Onboarding & In-App Enrollment Flow

PR: #1689 – Veena/mob onb2
Branch: veena/mob_onb2 → dev
Repository: AzureAD/microsoft-authentication-library-common-for-objc
Author: @swasti29
Status: Draft, Open
Stats: +2,814 additions, -37 deletions across 38 files

---

1. Executive Summary

This change introduces in-app MDM (Mobile Device Management) profile installation and enrollment support into the MSAL common library for Objective-C. It enables an interactive authentication flow where, when the AAD server signals that an Intune management profile must be installed, the embedded webview (WKWebView) seamlessly transitions to an ASWebAuthenticationSession for profile installation, then returns to the embedded webview to complete the original authentication. Additionally, it introduces Broker Refresh Token (BRT) acquisition logic triggered on special msauth:// and browser:// redirects.

---

2. Problem Statement

Currently, when AAD determines that a device requires MDM enrollment (Intune profile installation) before authentication can complete, the library lacks the ability to:

1. Detect an MDM profile installation trigger (msauth://installProfile) from the server.
2. Orchestrate a seamless transition from the embedded webview to ASWebAuthenticationSession for profile download (which requires system-level handling).
3. Resume the embedded webview after profile installation completes (msauth://in_app_enrollment_complete).
4. Acquire a Broker Refresh Token (BRT) opportunistically on special redirect schemes.
5. Hand off to the broker (SSO Extension) after successful enrollment for final token acquisition.

---

3. Architecture Overview

3.1 High-Level Flow

┌──────────────┐     ┌─────────────────────┐     ┌──────────────────────────┐
│  App calls   │────▶│ LocalInteractive     │────▶│ Embedded WKWebview       │
│ acquireToken │     │ Controller           │     │ (AAD login page)         │
└──────────────┘     └─────────────────────┘     └──────────┬───────────────┘
                                                            │
                         ┌──────────────────────────────────┤
                         │ Server returns msauth://          │
                         │ installProfile redirect           │
                         ▼                                   │
              ┌──────────────────────┐                       │
              │ SpecialNavigation    │ Delegate intercepts   │
              │ Delegate callback    │◀──────────────────────┘
              └──────┬───────────────┘
                     │ 1. Acquire BRT (first time only)
                     │ 2. Resolve navigation action
                     ▼
              ┌──────────────────────┐
              │ NavigationActionUtil │  Parses msauth:// URL
              │ resolves action      │  + HTTP response headers
              └──────┬───────────────┘
                     │ Returns: OpenInASWebAuthSession
                     ▼
              ┌──────────────────────┐     ┌─────────────────────────┐
              │ TransitionCoordinator│────▶│ ASWebAuthenticationSession│
              │ - Suspend WKWebview  │     │ (Profile installation)   │
              │ - Launch ASWebAuth   │     └──────────┬──────────────┘
              └──────────────────────┘                │
                                                      │ Callback:
                                                      │ msauth://in_app_enrollment_complete
                                                      ▼
              ┌──────────────────────┐     ┌──────────────────────────┐
              │ TransitionCoordinator│────▶│ Resume WKWebview         │
              │ - Resume webview     │     │ Load enrollment callback │
              │ - Clean up ASWebAuth │     └──────────┬───────────────┘
              └──────────────────────┘                │
                                                      │ WKWebview processes
                                                      │ enrollment completion
                                                      ▼
              ┌──────────────────────────────────────────────────────┐
              │ Controller handles MDMEnrollmentCompletionResponse   │
              │ → Creates BrokerInteractiveController               │
              │ → Delegates to SSO Extension for final token        │
              └─────────────────────────────────────────────────────┘

---

4. New Components

4.1 New Classes

Class	Location	Purpose
**`...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[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.