Add comprehensive authority configuration and precedence documentation

[Copilot]

Authority Configuration Documentation

Comprehensive documentation for authority configuration in Microsoft.Identity.Web (Issue #3613), rebased on master which includes the throwing behavior from PR #3873.

Documentation added/updated

• docs/authority-configuration.md - Main guide with accurate Mermaid decision tree showing the three MSAL builder paths (WithAuthority, WithB2CAuthority, WithOidcAuthority), configuration rules table, and recommended patterns
• docs/b2c-authority-examples.md - B2C-specific patterns: /tfp/ normalization, policy paths, custom domains, ChallengeAsync-based profile edit flow
• docs/ciam-authority-examples.md - CIAM standard and custom domain configurations
• docs/migration-authority-vs-instance.md - Migration guide from legacy mixed patterns (now throws instead of silently ignoring)
• docs/faq-authority-precedence.md - FAQ addressing common misconfigurations and upgrade path from older versions
• README.md - Authority Configuration section linking to new guides
• changelog.md - Entry documenting new docs

Key points reflected in docs

• Mixing Authority with Instance/TenantId now throws InvalidOperationException at startup (PR Throw on Authority vs Instance/TenantId conflict (OIDC + MSAL parity) #3873)
• Authority alone routes through WithOidcAuthority() (generic OIDC) -- lacks AAD-specific security/resilience. Instance + TenantId is strongly recommended for AAD.
• PreserveAuthority is internal-only, not developer-accessible -- removed from docs
• Decision tree accurately shows code paths through AuthorityHelpers.BuildCiamAuthorityIfNeeded and TokenAcquisition

Fixes #3613

[Jean-Marc Prieur (jmprieur)]

Copilot. I left 2 comments.
There is also one meta-point (applying everywhere in this doc). "PreserveAuthority" is a MergedOptions property. It's not accessible to developers, nor settable through the configuration.

[Copilot]

Copilot. I left 2 comments.
There is also one meta-point (applying everywhere in this doc). "PreserveAuthority" is a MergedOptions property. It's not accessible to developers, nor settable through ...

Removed all references to PreserveAuthority in commit 4491701. You're correct - it's an internal MergedOptions property not accessible to developers. Updated all documentation to clarify that the library automatically handles CIAM authorities correctly without requiring any special configuration from developers.

[Bogdan Gavril (bgavrilMS)]

Let's discuss about deprecating Authority altoghter instead?

[Bogdan Gavril (bgavrilMS)]

I think we should not advise ppl to use Authority for AAD authorities, because they risk disabling defenses like authority validation and other AAD specific logic.

[Bogdan Gavril (bgavrilMS)]

Travis Walker (@trwalke) - you worked on CIAM before. Can you please take over this PR from Jean-Marc and get it merged?

[Bogdan Gavril (bgavrilMS)]

Jean-Marc Prieur (@jmprieur) - is this ready to be merged? It is marked as draft.

[Jean-Marc Prieur (jmprieur)]

Jean-Marc Prieur (@jmprieur) - is this ready to be merged? It is marked as draft.

yes, you had blocked it ...

[Bogdan Gavril (bgavrilMS)]

Copilot - update this PR by rebasing it to master

[Copilot]

Copilot - update this PR by rebasing it to master

I can't rebase this PR because the environment doesn't support force-push. The merge also reveals conflicts in source files (MergedOptions.cs, MergedOptionsLogging.cs, LoggingEventId.cs, and several InternalAPI.Unshipped.txt) that originate from commits d4c1360 and 64139f1 that predate my documentation changes. These conflicts need to be resolved and the rebase/merge done manually by the branch owner.