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

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

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

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

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.

Pinned [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) at 4.11.0. <details> <summary>Release notes</summary> _Sourced from [Microsoft.Identity.Web's releases](https://github.com/AzureAD/microsoft-identity-web/releases)._ ## 4.11.0 ## What's Changed * Bump vitest from 3.2.4 to 4.1.0 in /tests/DevApps/SidecarAdapter/typescript by @dependabot[bot] in AzureAD/microsoft-identity-web#3836 * Bump MSAL.NET to 4.84.2 and align OWIN binding redirects by @gladjohn with @Copilot in AzureAD/microsoft-identity-web#3844 * docs(design): devex proposal for mTLS PoP on Managed Identity and FIC by @gladjohn in AzureAD/microsoft-identity-web#3832 * Prevent OpenIdConnectMiddlewareDiagnostics from logging sensitive values by @iarekk in AzureAD/microsoft-identity-web#3850 * Add MSI mTLS PoP support: pure MI + FIC-with-MI (impl for devex #3832) by @gladjohn in AzureAD/microsoft-identity-web#3839 * docs(design): devex proposal for Bearer tokens with bound credentials by @gladjohn in AzureAD/microsoft-identity-web#3833 * Add bound-credential support for Bearer tokens (cert + mTLS) by @gladjohn in AzureAD/microsoft-identity-web#3835 * Upgrade IdWeb Sidecar to .NET 10 (LTS) by @soodt in AzureAD/microsoft-identity-web#3841 * MTLS Without Tokens Support - MicrosoftIdentityMessageHandler Support by @tlupes in AzureAD/microsoft-identity-web#3815 * fix: include isTokenBinding in CCA cache key to prevent bearer/PoP collision by @gladjohn in AzureAD/microsoft-identity-web#3867 * Test + doc: x-ms-tokenboundauth header for AKV mTLS PoP via ExtraHeaderParameters by @gladjohn in AzureAD/microsoft-identity-web#3864 * Add mTLS PoP Copilot skill (certificate, MSI, FIC) by @gladjohn in AzureAD/microsoft-identity-web#3872 * Fix CVE-2026-48109: Pin MessagePack to patched version 2.5.301 by @soodt in AzureAD/microsoft-identity-web#3865 * Sidecar: gate agent identity parameters behind AllowOverrides by @iNinja in AzureAD/microsoft-identity-web#3871 * Bump System.Formats.Asn1 base version to 10.0.2 by @iarekk in AzureAD/microsoft-identity-web#3875 * Bump Microsoft.IdentityModel.* from 8.18.0 to 8.19.1 by @iarekk in AzureAD/microsoft-identity-web#3879 * Use IIdentityLogger for MSAL logging in TokenAcquisition and ManagedIdentityClientAssertion (#3820) by @neha-bhargava in AzureAD/microsoft-identity-web#3880 * Update Microsoft.Identity.Abstractions to 12.2.0 and MSAL to 4.85.0 by @neha-bhargava in AzureAD/microsoft-identity-web#3881 * Surface MSAL AuthenticationResultMetadata + exception details on AcquireTokenResult by @neha-bhargava in AzureAD/microsoft-identity-web#3856 * Flow outgoing request to header providers via AcquireTokenOptions by @neha-bhargava in AzureAD/microsoft-identity-web#3876 * Throw on Authority vs Instance/TenantId conflict (OIDC + MSAL parity) by @iarekk in AzureAD/microsoft-identity-web#3873 * Delete .github/workflows/evergreen.yml by @bgavrilMS in AzureAD/microsoft-identity-web#3803 * Add comprehensive authority configuration and precedence documentation by @jmprieur with @Copilot in AzureAD/microsoft-identity-web#3617 * Bump js-yaml from 4.1.1 to 4.2.0 in /tests/DevApps/SidecarAdapter/typescript by @dependabot[bot] in AzureAD/microsoft-identity-web#3862 * Move authority docs into docs/authority-configuration/ subfolder by @iarekk in AzureAD/microsoft-identity-web#3885 * Revert "Throw on Authority vs Instance/TenantId conflict (#3873)" by @iarekk in AzureAD/microsoft-identity-web#3888 * Update Microsoft.Identity.Client to 4.85.1 by @neha-bhargava in AzureAD/microsoft-identity-web#3889 * Enable E2E test coverage on internal Azure DevOps pipelines by @gladjohn in AzureAD/microsoft-identity-web#3883 * Bump esbuild and tsx in /tests/DevApps/SidecarAdapter/typescript by @dependabot[bot] in AzureAD/microsoft-identity-web#3859 * Skip AcquireTokenWithMtlsPop test: AAD westus3 test slice returns Bearer by @neha-bhargava in AzureAD/microsoft-identity-web#3892 ## New Contributors * @iarekk made their first contribution in AzureAD/microsoft-identity-web#3850 * @soodt made their first contribution in AzureAD/microsoft-identity-web#3841 **Full Changelog**: AzureAD/microsoft-identity-web@4.10.0...4.11.0 Commits viewable in [compare view](AzureAD/microsoft-identity-web@4.10.0...4.11.0). </details> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

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

Comment thread docs/authority-configuration.md

Comment thread docs/authority-configuration.md Outdated

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

Comment thread docs/authority-configuration.md

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add comprehensive authority configuration and precedence documentation#3617

Add comprehensive authority configuration and precedence documentation#3617
iarekk merged 6 commits into
masterfrom
copilot/update-docs-for-authority-precedence

Copilot AI commented Nov 22, 2025 •

edited by iarekk

Loading

Uh oh!

jmprieur left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Nov 22, 2025

Uh oh!

Uh oh!

bgavrilMS left a comment

Uh oh!

bgavrilMS left a 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Uh oh!

Conversation

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

Uh oh!

Authority Configuration Documentation

Documentation added/updated

Key points reflected in docs

Uh oh!

jmprieur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Copilot AI commented Nov 22, 2025 •

edited by iarekk

Loading