microsoft-identity-web icon indicating copy to clipboard operation
microsoft-identity-web copied to clipboard
verified publisher icon AzureAD

Add comprehensive authority configuration and precedence documentation

Open Copilot opened this issue 3 months ago • 1 comments

Add comprehensive authority configuration and precedence documentation

  • [x] You've read the Contributor Guide and Code of Conduct.
  • [x] You've included unit or integration tests for your change, where applicable.
  • [x] You've included inline docs for your change, where applicable.
  • [x] There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Documentation for authority parsing precedence rules and configuration patterns

Description

Developers frequently misconfigure Authority, Instance, and TenantId properties, triggering EventId 408 warnings when Instance/TenantId silently override Authority. This documentation clarifies the precedence rules, parsing behavior, and platform-specific patterns (B2C policies, CIAM configurations).

New Documentation

Core Reference

  • docs/authority-configuration.md - Precedence rules, Mermaid decision flowchart, configuration matrix table, EventId 408 explanation, sovereign cloud instances

Platform-Specific Guides

  • docs/b2c-authority-examples.md - B2C policy paths, legacy /tfp/ normalization, runtime policy switching
  • docs/ciam-authority-examples.md - CIAM standard and custom domain configurations, CIAM vs AAD patterns

Migration & Troubleshooting

  • docs/migration-authority-vs-instance.md - EventId 408 resolution paths, government cloud configurations, rollback procedures
  • docs/faq-authority-precedence.md - 30+ Q&A covering common misconfigurations

Key Concepts Documented

Precedence Rule: Instance + TenantId always override Authority when both are set. Authority is parsed into Instance/TenantId only when those properties are null.

B2C Pattern: Always use complete Authority URL including policy path:

{
  "AzureAdB2C": {
    "Authority": "https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_susi",
    "ClientId": "...",
    "Domain": "contoso.onmicrosoft.com"
  }
}

CIAM Configuration: Use complete Authority URL; the library handles CIAM authorities automatically:

{
  "AzureAd": {
    "Authority": "https://contoso.ciamlogin.com/contoso.onmicrosoft.com",
    "ClientId": "..."
  }
}

Note: PreserveAuthority is an internal implementation detail and not accessible to developers through configuration.

Updates

  • README.md: Added Authority Configuration section with guide links
  • changelog.md: Added documentation entry under 4.1.0

Review Feedback Addressed

  • Removed PreserveAuthority references: Corrected all documentation to reflect that PreserveAuthority is an internal property not accessible to developers
  • Added sovereign cloud link: Instance definition now includes link to Azure AD authentication endpoints for sovereign clouds (Azure Government, Azure China)
  • Improved footnote clarity: Updated single-tenant app guidance for better readability

Fixes #3613

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

  1. docs/authority-configuration.md (NEW) – main guide.
  2. docs/b2c-authority-examples.md (NEW) – focused B2C patterns (classic /tfp/, policy path variants, custom domains, migration tips).
  3. docs/ciam-authority-examples.md (NEW) – CIAM scenarios and PreserveAuthority behavior.
  4. docs/migration-authority-vs-instance.md (NEW) – upgrade path for existing apps using mixed patterns.
  5. README.md – Add short section linking to new authority guide.
  6. CHANGELOG.md – Add entry under Unreleased: "Added authority precedence and migration documentation (#3613)."
  7. 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 (#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

  1. docs/authority-configuration.md (NEW) – main guide.
  2. docs/b2c-authority-examples.md (NEW) – focused B2C patterns (classic /tfp/, policy path variants, custom domains, migration tips).
  3. docs/ciam-authority-examples.md (NEW) – CIAM scenarios and PreserveAuthority behavior.
  4. docs/migration-authority-vs-instance.md (NEW) – upgrade path for existing apps using mixed patterns.
  5. README.md – Add short section linking to new authority guide.
  6. CHANGELOG.md – Add entry under Unreleased: "Added authority precedence and migration documentation (#3613)."
  7. 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 (#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.

Copilot avatar Nov 22 '25 21:11 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.

Copilot avatar Nov 22 '25 22:11 Copilot