Overview

Both MicrosoftIdentityMessageHandler and DownstreamApi implement logic for handling WWW-Authenticate header challenges, which includes:

• Detecting a claims challenge from the response
• Cloning the original request for retry
• Creating new options with claim challenges
• Acquiring a new token and retrying the request

Currently, both have separate implementations that duplicate logic for claim extraction, request/content cloning, and retry handling. This makes maintenance more difficult, and future bug fixes or improvements must be duplicated.

Proposal

Extract the shared logic for handling WWW-Authenticate challenges into an internal helper (e.g., WwwAuthenticateChallengeHelper) in the TokenAcquisition project. Refactor both MicrosoftIdentityMessageHandler and DownstreamApi to use this helper, ensuring:

• Defensive cloning of HttpRequestMessage and HttpContent for retries (supporting non-seekable streams)
• Inline comments explaining why content is cloned and why ForceRefresh is not set when claims are present
• Consistency across both entry points

Key Details

• Do not set ForceRefresh when claims are present. MSAL.NET will bypass the cache automatically (see CacheRefreshReason.ForceRefreshOrClaims).
• Use inline comments in the helper and refactored code to explain design decisions for future maintainers.
• Base changes on the copilot/fix-82eb5023-e802-4c45-8341-57c618f136aa branch, where MicrosoftIdentityMessageHandler is implemented but not yet merged.
• Add unit tests for the helper covering claim extraction and content cloning.

Benefits

• Eliminates duplicate challenge-handling logic
• Ensures bug fixes and improvements apply to both entry points
• Improves maintainability and testability

Acceptance Criteria

• Shared helper is implemented and used by both MicrosoftIdentityMessageHandler and DownstreamApi
• Helper includes defensive content cloning and explanatory comments for claims handling
• Unit tests verify helper behavior for various header and content scenarios
• No API-breaking changes

Co-created by Jean-Marc and Copilot, per our collaborative process.