Improve error message for unconfigured MicrosoftIdentityApplicationOptions

[Copilot]

Problem

When MicrosoftIdentityApplicationOptions are not properly configured for an authentication scheme, developers encounter a misleading error message:

IDW10503: Cannot determine the cloud Instance. The provided authentication scheme was 'MyScheme'. Microsoft.Identity.Web inferred 'MyScheme' as the authentication scheme. Available authentication schemes are ''. See https://aka.ms/id-web/authSchemes.

This generic message suggests an authentication scheme problem when the real issue is missing or incomplete configuration of MicrosoftIdentityApplicationOptions.

Solution

Added intelligent error detection logic that differentiates between:

1. Missing/unconfigured options: Shows a clear, actionable error message
2. Authentication scheme mismatch: Shows the original error message (still relevant for scheme issues)

New Error Message

When MicrosoftIdentityApplicationOptions are not configured, developers now see:

IDW10503: Cannot determine the cloud Instance because MicrosoftIdentityApplicationOptions are not configured for the authentication scheme 'MyScheme'. Please ensure the MicrosoftIdentityApplicationOptions are properly configured in your application setup. See https://aka.ms/ms-id-web/configuration for details.

Implementation Details

• Smart Detection: Checks if MicrosoftIdentityApplicationOptions contain meaningful values (Instance, Authority, or ClientId)
• Default Value Handling: Excludes the default Authority value "//v2.0" when determining if options are configured
• Dual Host Support: Updated both TokenAcquisitionAspnetCoreHost and DefaultTokenAcquisitionHost
• Timing Fix: Ensures merged options are re-retrieved after the options merging process completes

Testing

Added comprehensive test coverage including:

• Unit tests with mocked dependencies
• Integration tests with real DI container setup
• Validation of both error scenarios (missing options vs. scheme mismatch)
• Verification that existing functionality remains intact

Backward Compatibility

✅ No breaking changes

• Original error message preserved for legitimate authentication scheme issues
• All existing tests continue to pass
• New error constant added to Internal API documentation

Developer Impact

This change significantly improves the debugging experience by providing clear, actionable guidance when MicrosoftIdentityApplicationOptions are not properly configured, reducing confusion and time spent troubleshooting configuration issues.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature Request] Provide clear error message in case when MicrosoftIdentityApplicationOptions are not configured</issue_title>
<issue_description>Is your feature request related to a problem? Please describe.
Error message raised if no options are configured is unclear.

Describe the solution you'd like
A clear and error message indicating the source of the issue.

Additional context
If MicrosoftIdentityApplicationOptions are not configured (for a given scheme), one might get an error/exceptions as the one below on GetAccessTokenForUserAsync calls.
Error: System.InvalidOperationException: IDW10503: Cannot determine the cloud Instance

This issue arises when an options object, resolved from an options monitor, is empty (with an empty cloud instance). Since the instance is evaluated first in the specific code path, the error IDW10503: Cannot determine the cloud Instance is triggered.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #3482

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.