Add comprehensive authority configuration and precedence documentation by Copilot · Pull Request #3617 · AzureAD/microsoft-identity-web

Copilot · 2025-11-22T21:31:03Z

Authority Precedence Documentation Implementation

This PR implements comprehensive documentation for authority configuration and precedence in Microsoft.Identity.Web (Issue #3613), now synced with master.

Documentation Changes (this PR's unique contribution)

Create docs/authority-configuration.md - Main guide with decision tree Mermaid diagram, precedence table, configuration patterns
Create docs/b2c-authority-examples.md - B2C-specific patterns with /tfp/ normalization, policy paths, custom domains
Create docs/ciam-authority-examples.md - CIAM standard and custom domain configurations
Create docs/migration-authority-vs-instance.md - Migration guide from legacy mixed patterns
Create docs/faq-authority-precedence.md - FAQ addressing common misconfigurations
Update README.md - Add Authority Configuration section linking to new guides
Update changelog.md - Add entry documenting new authority precedence docs
Remove PreserveAuthority references (internal only, not developer-accessible)
Add sovereign cloud link to Instance terminology

Sync with master

Resolve conflicts in LoggingEventId.cs (AuthorityIgnored EventId 500)
Resolve conflicts in MergedOptionsLogging.cs
Resolve conflicts in MergedOptionsStore.cs (IServiceProvider constructor)
Resolve conflicts in MergedOptions.cs (pass logger to ParseAuthorityIfNecessary)
Resolve conflicts in InternalAPI.Shipped/Unshipped.txt (all TFMs)
Resolve conflicts in MergedOptionsAuthorityParsingTests.cs
Bring in all new files added to master since branch divergence

Original prompt

Implement Issue #3613: Add comprehensive documentation clarifying precedence between Authority, Instance, TenantId, Domain, PreserveAuthority, and policy settings (B2C, CIAM), following fixes (#3612) and diagnostics (#3611).

Scope
Create new documentation assets and update existing docs to help developers configure authentication correctly and interpret the new warning log message. Branch: jmprieur/docs-authority-precedence off jmprieur/fix-authority-parsing.

Goals

Provide a canonical source explaining how authority parsing works in Microsoft.Identity.Web.
Clarify precedence: When Authority is ignored in favor of Instance/TenantId; when PreserveAuthority applies; when policy paths are normalized.
Offer migration guidance from legacy patterns (mixed Authority + Instance/TenantId) to recommended configurations.
Include CIAM and B2C specifics with examples.
Introduce FAQ section addressing common misconfigurations.
Add Mermaid diagrams for parsing decision flow and configuration strategy.
Update CHANGELOG with Added docs entry.

Planned Files / Changes

docs/authority-configuration.md (NEW) – main guide.
docs/b2c-authority-examples.md (NEW) – focused B2C patterns (classic /tfp/, policy path variants, custom domains, migration tips).
docs/ciam-authority-examples.md (NEW) – CIAM scenarios and PreserveAuthority behavior.
docs/migration-authority-vs-instance.md (NEW) – upgrade path for existing apps using mixed patterns.
README.md – Add short section linking to new authority guide.
CHANGELOG.md – Add entry under Unreleased: "Added authority precedence and migration documentation (Update documentation/samples: Authority/Instance/TenantId precedence for AAD/B2C, warning logs #3613)."
docs/faq-authority-precedence.md (NEW) – Q&A addressing warnings, conflicts, and edge case behavior.

Content Outline (authority-configuration.md)

Title: Authority Configuration & Precedence in Microsoft.Identity.Web

Sections:

Overview
Terminology (Authority, Instance, TenantId, Domain, PreserveAuthority, Policy IDs)
Decision Tree (Mermaid diagram) for resolution order:
- If Instance & TenantId set -> they take precedence
- Else if Authority set -> parse Authority (AAD/B2C/CIAM)
- If PreserveAuthority true -> do not split for CIAM/B2C
- PrepareAuthorityInstanceForMsal normalization (/tfp/ removal, trailing slash)
Precedence Table (Markdown table): combinations and outcomes.
Recommended Configuration Patterns:
- AAD single tenant (Instance + TenantId)
- AAD multi-tenant (Authority with organizations/common or Instance + "common")
- B2C (Authority only recommended; avoid mixing Instance/TenantId/Policy separately)
- CIAM (Authority + PreserveAuthority true recommended; avoid mixing Instance/TenantId)
Warning Log Explanation (EventId 2101)
Migration Guidance (pointer to migration doc)
Edge Cases (scheme-less authority, query params, trailing slashes, missing v2.0 suffix)
FAQ link

Mermaid Diagram (planned in authority-configuration.md)

flowchart TD
  A[Config Provided] --> B{Instance & TenantId set?}
  B -- Yes --> C[Use Instance & TenantId; Ignore Authority]
  B -- No --> D{Authority Provided?}
  D -- No --> E[Configuration invalid / requires Instance+TenantId]
  D -- Yes --> F{PreserveAuthority True?}
  F -- Yes --> G[Use full Authority as Instance; TenantId=null]
  F -- No --> H[Parse Authority -> Instance + TenantId]
  H --> I{Is B2C?}
  I -- Yes --> J[Normalize /tfp/; Derive PreparedInstance]
  I -- No --> K[Derive PreparedInstance]
  C --> K
  G --> K
  K --> L[Pass PreparedInstance to MSAL]

FAQ (faq-authority-precedence.md) sample entries:
Q: Why do I see a warning "Both Authority and Instance/TenantId are set"?
A: You configured Authority along with Instance or TenantId. Instance/TenantId take precedence; remove Authority to suppress the warning.

Q: Should I use Authority or Instance/TenantId for B2C?
A: Prefer Authority including the policy path (e.g., https://///v2.0). Avoid mixing Instance/TenantId.

Q: How do I configure CIAM?
A: Use the CIAM Authority domain, set PreserveAuthority=true implicitly (by library defaults), do not specify TenantId.

Migration Doc (migration-authority-vs-instance.md)

Identify legacy configuration style example.
Show corrected style.
Provide diff block (before/after JSON).

CHANGELOG.md
Add under Unreleased:

Added: Documentation for authority precedence, B2C & CIAM patterns (Update documentation/samples: Authority/Instance/TenantId precedence for AAD/B2C, warning logs #3613)

Acceptance Criteria

New docs compile lint (if doc tooling exists).
README links resolve to added files.
Mermaid diagrams render in GitHub UI.
Clear cross-references between authority guide, FAQ, migration doc, and examples.
No behavioral changes.

Non-Goals

Code modifications to parsing logic.
Additional logging changes.
Multi-lingual docs (English only initial pass).

Risks / Mitigation

Risk: Confusion between B2C policy formatting and deprecated /tfp/ usage—Mitigation: include explicit examples and highlight normalization behavior.
Risk: CIAM vs AAD authority mixing—Mitig...

This pull request was created as a result of the following prompt from Copilot chat.

Implement Issue #3613: Add comprehensive documentation clarifying precedence between Authority, Instance, TenantId, Domain, PreserveAuthority, and policy settings (B2C, CIAM), following fixes (#3612) and diagnostics (#3611).

Scope
Create new documentation assets and update existing docs to help developers configure authentication correctly and interpret the new warning log message. Branch: jmprieur/docs-authority-precedence off jmprieur/fix-authority-parsing.

Goals

Provide a canonical source explaining how authority parsing works in Microsoft.Identity.Web.

Clarify precedence: When Authority is ignored in favor of Instance/TenantId; when PreserveAuthority applies; when policy paths are normalized.

Offer migration guidance from legacy patterns (mixed Authority + Instance/TenantId) to recommended configurations.

Include CIAM and B2C specifics with examples.

Introduce FAQ section addressing common misconfigurations.

Add Mermaid diagrams for parsing decision flow and configuration strategy.

Update CHANGELOG with Added docs entry.

Planned Files / Changes

docs/authority-configuration.md (NEW) – main guide.

docs/b2c-authority-examples.md (NEW) – focused B2C patterns (classic /tfp/, policy path variants, custom domains, migration tips).

docs/ciam-authority-examples.md (NEW) – CIAM scenarios and PreserveAuthority behavior.

docs/migration-authority-vs-instance.md (NEW) – upgrade path for existing apps using mixed patterns.

README.md – Add short section linking to new authority guide.

CHANGELOG.md – Add entry under Unreleased: "Added authority precedence and migration documentation (Update documentation/samples: Authority/Instance/TenantId precedence for AAD/B2C, warning logs #3613)."

docs/faq-authority-precedence.md (NEW) – Q&A addressing warnings, conflicts, and edge case behavior.

Content Outline (authority-configuration.md)

Title: Authority Configuration & Precedence in Microsoft.Identity.Web

Sections:

Overview

Terminology (Authority, Instance, TenantId, Domain, PreserveAuthority, Policy IDs)

Decision Tree (Mermaid diagram) for resolution order:

If Instance & TenantId set -> they take precedence

Else if Authority set -> parse Authority (AAD/B2C/CIAM)

If PreserveAuthority true -> do not split for CIAM/B2C

PrepareAuthorityInstanceForMsal normalization (/tfp/ removal, trailing slash)

Precedence Table (Markdown table): combinations and outcomes.

Recommended Configuration Patterns:

AAD single tenant (Instance + TenantId)

AAD multi-tenant (Authority with organizations/common or Instance + "common")

B2C (Authority only recommended; avoid mixing Instance/TenantId/Policy separately)

CIAM (Authority + PreserveAuthority true recommended; avoid mixing Instance/TenantId)

Warning Log Explanation (EventId 2101)

Migration Guidance (pointer to migration doc)

Edge Cases (scheme-less authority, query params, trailing slashes, missing v2.0 suffix)

FAQ link

Mermaid Diagram (planned in authority-configuration.md)
flowchart TD
  A[Config Provided] --> B{Instance & TenantId set?}
  B -- Yes --> C[Use Instance & TenantId; Ignore Authority]
  B -- No --> D{Authority Provided?}
  D -- No --> E[Configuration invalid / requires Instance+TenantId]
  D -- Yes --> F{PreserveAuthority True?}
  F -- Yes --> G[Use full Authority as Instance; TenantId=null]
  F -- No --> H[Parse Authority -> Instance + TenantId]
  H --> I{Is B2C?}
  I -- Yes --> J[Normalize /tfp/; Derive PreparedInstance]
  I -- No --> K[Derive PreparedInstance]
  C --> K
  G --> K
  K --> L[Pass PreparedInstance to MSAL]
Loading
FAQ (faq-authority-precedence.md) sample entries:
Q: Why do I see a warning "Both Authority and Instance/TenantId are set"?
A: You configured Authority along with Instance or TenantId. Instance/TenantId take precedence; remove Authority to suppress the warning.

Q: Should I use Authority or Instance/TenantId for B2C?
A: Prefer Authority including the policy path (e.g., https://///v2.0). Avoid mixing Instance/TenantId.

Q: How do I configure CIAM?
A: Use the CIAM Authority domain, set PreserveAuthority=true implicitly (by library defaults), do not specify TenantId.

Migration Doc (migration-authority-vs-instance.md)

Identify legacy configuration style example.

Show corrected style.

Provide diff block (before/after JSON).

CHANGELOG.md
Add under Unreleased:

Added: Documentation for authority precedence, B2C & CIAM patterns (Update documentation/samples: Authority/Instance/TenantId precedence for AAD/B2C, warning logs #3613)

Acceptance Criteria

New docs compile lint (if doc tooling exists).

README links resolve to added files.

Mermaid diagrams render in GitHub UI.

Clear cross-references between authority guide, FAQ, migration doc, and examples.

No behavioral changes.

Non-Goals

Code modifications to parsing logic.

Additional logging changes.

Multi-lingual docs (English only initial pass).

Risks / Mitigation

Risk: Confusion between B2C policy formatting and deprecated /tfp/ usage—Mitigation: include explicit examples and highlight normalization behavior.

Risk: CIAM vs AAD authority mixing—Mitigation: dedicated CIAM section + PreserveAuthority explanation.

Follow-Up

Localize docs (future issue)

Add samples folder cross-links

Potential automation to validate authority examples against parser

Please create branch jmprieur/docs-authority-precedence from jmprieur/fix-authority-parsing and open a PR referencing issue #3613. Populate the new markdown files with the outlined content skeletons and TODO markers where detailed examples will be added.

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

… CIAM, and B2C (#3614) * Initial plan * Implement authority-only configuration support for AAD, CIAM, and B2C - Move ParseAuthorityIfNecessary to start of UpdateConfidentialClientApplicationOptionsFromMergedOptions - Add defensive fallback parse in PrepareAuthorityInstanceForMsal - Add TODO comment for future warning logging (issue #3611) - Create new unit test file MergedOptionsAuthorityParsingTests.cs with 7 tests - Modify E2E test to use Authority-only configuration - Add new B2C authority-only E2E test All unit tests pass successfully Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> * Address code review feedback - Add explicit using statement for Microsoft.Identity.Web in test file - Improve defensive fallback to also check TenantId to avoid redundant parsing All tests still pass Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> * Restore original test and create new Authority-only test - Restore AcquireToken_WithMicrosoftIdentityApplicationOptions_ClientCredentialsAsync with Instance/TenantId - Create new AcquireToken_WithMicrosoftIdentityApplicationOptions_Authority_ClientCredentialsAsync for Authority-only scenario Both tests now exist to demonstrate both recommended (Instance/TenantId) and Authority-only approaches Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

…d conflicts (#3615) * Initial plan * Add authority conflict warning logging infrastructure Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> * Add comprehensive unit tests for authority conflict warnings Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> * Wire up logger factory to MergedOptionsStore for runtime logging Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> * Fix MergedOptionsStore constructor signature for DI compatibility Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> * Rename MsalLogger alias to IdWebLogger for clarity Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com> Co-authored-by: Jean-Marc Prieur <jmprieur@microsoft.com>

- Created docs/authority-configuration.md with decision tree, precedence table, and configuration patterns - Created docs/b2c-authority-examples.md with B2C-specific patterns and /tfp/ normalization details - Created docs/ciam-authority-examples.md with CIAM scenarios and PreserveAuthority guidance - Created docs/migration-authority-vs-instance.md with upgrade paths and migration examples - Created docs/faq-authority-precedence.md with Q&A addressing common misconfigurations - Updated README.md with Authority Configuration section linking to new guides - Updated changelog.md with documentation entry for issue #3613 Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

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.

docs/authority-configuration.md

jmprieur · 2025-11-22T22:14:39Z

docs/authority-configuration.md

+| ❌ | ✅ | ❌ | any | Instance used, tenant resolved at runtime | No* |
+| ❌ | ❌ | ✅ | any | Invalid configuration | Error |
+
+\* For single-tenant apps, this may cause issues. Always specify TenantId when using Instance.


Suggested change

\* For single-tenant apps, this may cause issues. Always specify TenantId when using Instance.

For single-tenant apps, this may cause issues. Always specify TenantId when using Instance.

Updated the footnote text as suggested in commit 4491701.

- Removed all references to PreserveAuthority as it's an internal property not accessible to developers - Added link to sovereign cloud instances documentation in Instance definition - Improved footnote text for single-tenant apps per review feedback - Updated Mermaid diagram to remove PreserveAuthority decision point - Updated all CIAM examples to show Authority-only configuration without PreserveAuthority - Clarified that the library automatically handles CIAM authorities correctly Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

Copilot · 2025-11-22T22:34:33Z

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

docs/authority-configuration.md

bgavrilMS

Let's discuss about deprecating Authority altoghter instead?

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.

bgavrilMS · 2026-01-20T16:40:13Z

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

bgavrilMS · 2026-01-21T11:00:05Z

@jmprieur - is this ready to be merged? It is marked as draft.

jmprieur · 2026-01-22T03:39:26Z

@jmprieur - is this ready to be merged? It is marked as draft.

yes, you had blocked it ...

bgavrilMS · 2026-02-24T10:44:01Z

@copilot - update this PR by rebasing it to master

Copilot · 2026-02-24T10:46:30Z

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

bgavrilMS · 2026-03-02T11:12:24Z

@copilot - resolve conflicts

- Updated all source code files to match master (commits d4c1360 and 64139f1 were already merged to master in improved form) - Synced LoggingEventId.cs: AuthorityConflict (EventId 408) -> AuthorityIgnored (EventId 500) - Synced MergedOptionsLogging.cs: use LoggingEventId.AuthorityIgnored - Synced MergedOptionsStore.cs: ILoggerFactory -> IServiceProvider constructor - Synced MergedOptions.cs: fix trailing whitespace; pass logger to ParseAuthorityIfNecessary - Synced InternalAPI.Shipped.txt for all TFMs: APIs now in Shipped.txt - Synced InternalAPI.Unshipped.txt for all TFMs: empty (APIs are shipped) - Synced MergedOptionsAuthorityParsingTests.cs: use id4slab1 test tenant name - Added all new files from master (MtlsPop, new test files, skills, docs) - Merged changelog.md: preserved our authority doc entry, added master's 4.4.0 entries - Preserved README.md with our authority configuration section - Preserved all documentation additions (docs/*.md files) Co-authored-by: bgavrilMS <12273384+bgavrilMS@users.noreply.github.com>

Copilot · 2026-03-02T11:25:48Z

@copilot - resolve conflicts

Resolved conflicts and synced with master in commit 0927e20. The branch now includes all master changes (4.4.0 release, new files) while preserving the documentation additions from this PR. Key conflict resolutions:

LoggingEventId.cs: AuthorityConflict (EventId 408) → AuthorityIgnored (EventId 500)
MergedOptionsStore.cs: ILoggerFactory constructor → IServiceProvider constructor
MergedOptions.cs: ParseAuthorityIfNecessary(this) → ParseAuthorityIfNecessary(this, this.Logger)
InternalAPI.Shipped/Unshipped.txt (all TFMs): synced with master's shipped API declarations

Copilot AI and others added 3 commits November 22, 2025 12:38

Initial plan

bab62bd

Copilot AI assigned Copilot and jmprieur Nov 22, 2025

Copilot started work on behalf of jmprieur November 22, 2025 21:31 View session

Copilot AI changed the title ~~[WIP] Add comprehensive documentation for authority precedence~~ Add comprehensive authority configuration and precedence documentation Nov 22, 2025

Copilot AI requested a review from jmprieur November 22, 2025 21:46

Copilot finished work on behalf of jmprieur November 22, 2025 21:46

jmprieur reviewed Nov 22, 2025

View reviewed changes

Copilot started work on behalf of jmprieur November 22, 2025 22:24 View session

Copilot AI requested a review from jmprieur November 22, 2025 22:36

Copilot finished work on behalf of jmprieur November 22, 2025 22:36

bgavrilMS reviewed Nov 24, 2025

View reviewed changes

docs/authority-configuration.md Show resolved Hide resolved

bgavrilMS requested changes Nov 24, 2025

View reviewed changes

Base automatically changed from jmprieur/fix-authority-parsing to master November 24, 2025 18:43

jmprieur changed the base branch from master to feature/doc-modernization December 3, 2025 21:17

jmprieur changed the base branch from feature/doc-modernization to master December 3, 2025 21:17

jmprieur mentioned this pull request Jan 20, 2026

Faulty log message for Authority configuration #3676

Open

bgavrilMS approved these changes Jan 20, 2026

View reviewed changes

bgavrilMS requested a review from trwalke January 20, 2026 16:39

bgavrilMS marked this pull request as ready for review February 24, 2026 10:43

bgavrilMS requested a review from a team as a code owner February 24, 2026 10:43

Copilot started work on behalf of bgavrilMS February 24, 2026 10:44 View session

Copilot AI requested a review from bgavrilMS February 24, 2026 10:47

Copilot finished work on behalf of bgavrilMS February 24, 2026 10:47

bgavrilMS approved these changes Mar 2, 2026

View reviewed changes

Copilot started work on behalf of bgavrilMS March 2, 2026 11:12 View session

Copilot AI requested a review from bgavrilMS March 2, 2026 11:26

Copilot finished work on behalf of bgavrilMS March 2, 2026 11:26

	\* For single-tenant apps, this may cause issues. Always specify TenantId when using Instance.
	For single-tenant apps, this may cause issues. Always specify TenantId when using Instance.

Conversation

Copilot AI commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Authority Precedence Documentation Implementation

Documentation Changes (this PR's unique contribution)

Sync with master

Title: Authority Configuration & Precedence in Microsoft.Identity.Web

Title: Authority Configuration & Precedence in Microsoft.Identity.Web

Uh oh!

jmprieur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmprieur Nov 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Nov 22, 2025

Uh oh!

Uh oh!

bgavrilMS left a comment

Choose a reason for hiding this comment

Uh oh!

bgavrilMS left a comment

Choose a reason for hiding this comment

Uh oh!

bgavrilMS commented Jan 20, 2026

Uh oh!

bgavrilMS commented Jan 21, 2026

Uh oh!

jmprieur commented Jan 22, 2026

Uh oh!

bgavrilMS commented Feb 24, 2026

Uh oh!

Copilot AI commented Feb 24, 2026

Uh oh!

bgavrilMS commented Mar 2, 2026

Uh oh!

Copilot AI commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Nov 22, 2025 •

edited

Loading