Update docs and add warning for strictMatching (#8388)

This PR adds `strictMatching` runtime warning and documentation for
`@azure/msal-angular`. When `strictMatching` is not explicitly
configured on `MsalInterceptorConfiguration`, `MsalInterceptor` now
emits a one-time warning via the MSAL logger. This helps developers
discover silent 401 failures caused by misconfigured
`protectedResourceMap` keys under the v5 default strict matching
behaviour.

#### Code Changes
- **`msal.interceptor.ts`** — Inline check in the constructor emits a
logger warning when `strictMatching === undefined`, linking to the
strict matching docs.
- **`msal.interceptor.spec.ts`** — 3 new warning tests (`undefined` →
warns, `true`/`false` → no warn). Existing tests updated to pass
`strictMatching: true` to suppress the warning.

#### Documentation Changes
- **`msal-interceptor.md`** — Common failure patterns table,
environment-driven configuration guidance, troubleshooting section with
fix options, and runtime warning explanation.
- **`v4-v5-upgrade-guide.md`** — Quick checklist, v5 minor upgrade
callout, and environment-driven `protectedResourceMap` code sample with
`// TODO` migration comment.
- **`known-issues.md`** — Concise entry linking to strict matching docs.
- **`configuration.md`** — `strictMatching: false` with comments in
dynamic config samples; guidance comments in static config samples.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: jo-arroyo

change/@azure-msal-angular-7198751c-a747-4b3e-bc7c-cfc69d4901fc.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Add strictMatching runtime warning when strictMatching is not explicitly configured [#8388](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/8388)",
+  "packageName": "@azure/msal-angular",
+  "email": "joarroyo@microsoft.com",
+  "dependentChangeType": "patch"
+}

lib/msal-angular/docs/configuration.md

@@ -115,6 +115,7 @@ export function MSALInstanceFactory(): IPublicClientApplication {
 
 export function MSALInterceptorConfigFactory(): MsalInterceptorConfiguration {
   const protectedResourceMap = new Map<string, Array<string>>();
+  // Use exact paths or wildcards so strict matching (the v5 default) works correctly
   protectedResourceMap.set("https://graph.microsoft.com/v1.0/me", ["user.read"]);
 
   return {
@@ -238,6 +239,10 @@ fetch("/assets/configuration.json")
         useValue: {
           interactionType: json.interceptor.interactionType,
           protectedResourceMap: new Map(json.interceptor.protectedResourceMap),
+          // Dynamic JSON configurations may use base URLs without wildcards.
+          // Set strictMatching: false if keys are not guaranteed to be exact
+          // paths or wildcard patterns. Remove once keys are migrated.
+          strictMatching: false,
         } as MsalInterceptorConfiguration,
       },
     ])
@@ -373,6 +378,10 @@ export function MSALInterceptorConfigFactory(config: ConfigService): MsalInterce
   return {
     interactionType: config.getSettings("interceptor").interactionType,
     protectedResourceMap,
+    // Dynamic configurations may use base URLs without wildcards.
+    // Set strictMatching: false if keys are not guaranteed to be exact
+    // paths or wildcard patterns. Remove once keys are migrated.
+    strictMatching: false,
   };
 }
 
@@ -548,6 +557,7 @@ export function MSALInstanceFactory(): IPublicClientApplication {
 
 export function MSALInterceptorConfigFactory(): MsalInterceptorConfiguration {
   const protectedResourceMap = new Map<string, Array<string>>();
+  // Use exact paths or wildcards so strict matching (the v5 default) works correctly
   protectedResourceMap.set("https://graph.microsoft.com/v1.0/me", ["user.read"]);
 
   return {

lib/msal-angular/docs/known-issues.md

@@ -1,5 +1,11 @@
 # Known issues for MSAL Angular
 
+## 5.x
+
+### Strict matching may silently drop `Authorization` headers
+
+`protectedResourceMap` uses strict URL matching by default in v5, which can silently prevent the `Authorization` header from being attached (resulting in **401 Unauthorized** errors). See the [strict matching documentation](./msal-interceptor.md#strict-matching-strictmatching) for details, common failure patterns, and fix options.
+
 ## 2.0.0
 * MSAL Guard's `CanLoad` does not interactively prompt for login. This will be addressed in a future release.
 

lib/msal-angular/docs/msal-interceptor.md

@@ -151,6 +151,8 @@ Other things to note regarding the `protectedResourceMap`:
 
 In msal-angular v5, URL component pattern matching for `protectedResourceMap` entries uses strict matching semantics by default. The `strictMatching` field on `MsalInterceptorConfiguration` controls this behaviour.
 
+> **⚠️ Important:** If your application sets `protectedResourceMap` keys dynamically (e.g. from environment files, `APP_INITIALIZER`, or JSON configuration) and those keys are base URLs without sub-paths or wildcards, strict matching can silently prevent the `Authorization` header from being attached, resulting in **401 errors with no build-time error and no per-request warning — only a one-time initialization warning if `strictMatching` is left unconfigured**. See [Troubleshooting strict matching](#troubleshooting-strict-matching) below.
+
 #### What strict matching changes
 
 | Behaviour | Legacy (`strictMatching: false`) | Strict (default in v5) |
@@ -165,6 +167,16 @@ With strict matching (the v5 default):
 - A pattern like `*.contoso.com` matches `app.contoso.com` but **not** `a.b.contoso.com` (wildcard cannot span dot separators).
 - A pattern like `https://graph.microsoft.com/v1.0/me` matches only that exact URL.
 
+#### Common failure patterns
+
+The following `protectedResourceMap` key patterns work under legacy matching but silently fail with strict matching:
+
+| Key pattern | Outgoing request URL | Result under strict matching | Fix |
+|---|---|---|---|
+| `https://api.example.com` | `https://api.example.com/v1/users` | ❌ No match — key resolves to path `/`, request has path `/v1/users` | `https://api.example.com/*` |
+| `https://api.example.com/` | `https://api.example.com/v1/users` | ❌ No match — trailing slash anchors the pattern to exactly `/` | `https://api.example.com/*` |
+| `environment.apiConfig.uri` (e.g. `https://api.example.com`) | `https://api.example.com/v1/users` | ❌ No match — same as above | `` `${environment.apiConfig.uri}/*` `` |
+
 #### Default behaviour in v5 (no configuration needed)
 
 Strict matching is enabled by default. No additional configuration is required:
@@ -173,7 +185,8 @@ Strict matching is enabled by default. No additional configuration is required:
 {
     interactionType: InteractionType.Redirect,
     protectedResourceMap: new Map([
-        ["https://*.contoso.com/api", ["contoso.scope"]],
+        // Use wildcards or exact paths so strict matching works correctly
+        ["https://*.contoso.com/api/*", ["contoso.scope"]],
         ["https://graph.microsoft.com/v1.0/me", ["user.read"]]
     ])
     // strictMatching defaults to true in v5
@@ -197,6 +210,84 @@ If your patterns rely on the looser matching from v4, you can set `strictMatchin
 }
 ```
 
+#### Guidance for environment-driven configurations
+
+If your `protectedResourceMap` keys reference Angular `environment` values (e.g. `environment.apiConfig.uri`), check whether those values are **exact paths** (e.g. `https://graph.microsoft.com/v1.0/me`) or **bare base URLs** (e.g. `https://api.example.com`). Exact paths work correctly with strict matching and need no special handling:
+
+```javascript
+export function MSALInterceptorConfigFactory(): MsalInterceptorConfiguration {
+  const protectedResourceMap = new Map<string, Array<string>>();
+  // environment.apiConfig.uri is an exact path (e.g. "https://graph.microsoft.com/v1.0/me")
+  // — strict matching works correctly
+  protectedResourceMap.set(environment.apiConfig.uri, environment.apiConfig.scopes);
+
+  return {
+    interactionType: InteractionType.Redirect,
+    protectedResourceMap,
+  };
+}
+```
+
+If the environment value is a bare base URL and you need to match sub-paths, append a `/*` wildcard:
+
+```javascript
+  // environment.apiConfig.uri is a base URL (e.g. "https://api.example.com")
+  // Append /* to match all sub-paths
+  protectedResourceMap.set(`${environment.apiConfig.uri}/*`, environment.apiConfig.scopes);
+```
+
+For truly **dynamic** configurations where the key shape is unknown at build time (e.g. `APP_INITIALIZER`, JSON loaded via `fetch`, or `platformBrowserDynamic`), set `strictMatching: false` as a temporary safe default. See [Fix options → Option B](#fix-options) below for a code example.
+
+#### Troubleshooting strict matching
+
+##### Symptoms
+
+- API requests return **401 Unauthorized** after upgrading to `@azure/msal-angular` v5 (or between v5 minor versions such as 5.0.x → 5.1.x).
+- The `Authorization: Bearer <token>` header is **missing** from outgoing HTTP requests.
+- No build-time or runtime errors are reported — the failure is **silent**.
+- The issue may only appear in certain environments (e.g. staging/production) where the API base URL differs from development.
+
+##### Fix options
+
+**Option A: Update keys to work with strict matching (recommended)**
+
+Update your `protectedResourceMap` keys to use exact paths or wildcards that match under strict matching rules. This is the preferred approach because strict matching is safer and more predictable:
+
+```javascript
+{
+    interactionType: InteractionType.Redirect,
+    protectedResourceMap: new Map([
+        // Exact path — matches only this URL
+        ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
+        // Wildcard — matches all sub-paths of the API
+        ["https://api.example.com/v1/*", ["api.scope"]]
+    ])
+    // strictMatching defaults to true — no need to set it
+}
+```
+
+**Option B: Set `strictMatching: false` (fallback for dynamic configurations)**
+
+If your `protectedResourceMap` keys are loaded dynamically at runtime (e.g. from `APP_INITIALIZER`, JSON config, or `platformBrowserDynamic`) and you cannot guarantee they contain exact paths or wildcards, set `strictMatching: false` as a temporary safe default:
+
+```javascript
+{
+    interactionType: InteractionType.Redirect,
+    protectedResourceMap: new Map([
+        [config.apiUri, config.apiScopes]
+    ]),
+    // Dynamic keys may be base URLs without wildcards.
+    // Remove once keys are migrated to exact paths or wildcard patterns.
+    strictMatching: false
+}
+```
+
+> **Note:** Legacy matching (`strictMatching: false`) is provided for backwards compatibility and may be removed in a future major version.
+
+##### Runtime warning
+
+`MsalInterceptor` emits a **one-time runtime warning** via the MSAL logger during initialization when `strictMatching` is not explicitly configured. If you see this warning, follow the fix options above.
+
 ### Optional authRequest
 
 For more information on the optional `authRequest` that can be set in the `MsalInterceptorConfiguration`, please see our [multi-tenant doc here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/docs/multi-tenant.md#dynamic-auth-request).

lib/msal-angular/docs/v4-v5-upgrade-guide.md

@@ -10,6 +10,35 @@ Please see the [MSAL Browser v4-v5 migration guide](https://github.com/AzureAD/m
 
 In msal-angular v5, URL pattern matching for protectedResourceMap entries uses strict matching semantics by default. Strict matching treats pattern metacharacters as literals, anchors matches to the full URL component, and applies host wildcard rules that do not span dot separators. If your v4 configuration relied on looser matching behavior, update your protectedResourceMap patterns to align with strict matching, or set strictMatching to false to retain legacy behavior temporarily. See [MSAL Interceptor docs](./msal-interceptor.md#strict-matching-strictmatching) for more details.
 
+> **⚠️ This change can also affect v5 minor upgrades.** If strict matching was not yet the default in the v5 minor version you originally adopted (e.g. 5.0.x), upgrading to a later v5 minor (e.g. 5.1.x) where strict matching is the default can silently break token attachment. The primary symptom is identical: **401 errors** — a runtime warning is now emitted when `strictMatching` is not explicitly configured, but the match failure itself remains silent and the `Authorization` header is no longer attached.
+
+#### Quick checklist
+
+1. **Review your `protectedResourceMap` keys.** Keys that are bare base URLs (e.g. `https://api.example.com`) without wildcards or sub-paths will no longer match requests to sub-paths of that URL. See [common failure patterns](./msal-interceptor.md#common-failure-patterns).
+2. **Update keys to use exact paths or wildcards.** Each key should either match the exact URL your application requests, or use a `/*` wildcard suffix to match sub-paths. See [fix options](./msal-interceptor.md#fix-options).
+3. **If your keys are loaded dynamically at runtime**, set `strictMatching: false` as a temporary safe default. See [guidance for environment-driven configurations](./msal-interceptor.md#guidance-for-environment-driven-configurations).
+
+#### Environment-driven `protectedResourceMap`
+
+If your `protectedResourceMap` keys come from Angular `environment` files, `APP_INITIALIZER`, JSON configuration, or `platformBrowserDynamic`, set `strictMatching: false` as a safe default during migration:
+
+```javascript
+export function MSALInterceptorConfigFactory(): MsalInterceptorConfiguration {
+  const protectedResourceMap = new Map<string, Array<string>>();
+  protectedResourceMap.set(environment.apiConfig.uri, environment.apiConfig.scopes);
+
+  return {
+    interactionType: InteractionType.Redirect,
+    protectedResourceMap,
+    // TODO: Remove once protectedResourceMap keys are updated to use
+    // exact paths or wildcard patterns (e.g. "https://api.example.com/*").
+    strictMatching: false,
+  };
+}
+```
+
+Once all keys are migrated to exact paths or wildcards, remove `strictMatching: false` (or set it to `true`) to benefit from the stricter, safer matching behaviour. See [guidance for environment-driven configurations](./msal-interceptor.md#guidance-for-environment-driven-configurations) for more details.
+
 ## Other changes in `@azure/msal-angular@5`
 
 ### `inject(TOKEN)` syntax

lib/msal-angular/src/msal.interceptor.spec.ts

@@ -1176,6 +1176,65 @@ describe("MsalInterceptor", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// strictMatching warning tests
+// ---------------------------------------------------------------------------
+
+describe("MsalInterceptor - strict matching warning", () => {
+  const emptyMap = new Map<
+    string,
+    Array<string | ProtectedResourceScopes> | null
+  >();
+
+  function initializeAndSpyOnWarning(strict?: boolean): jasmine.Spy {
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({
+      imports: [
+        MsalModule.forRoot(
+          MSALInstanceFactory(),
+          null,
+          MSALStrictInterceptorFactory(emptyMap, strict)
+        ),
+      ],
+      providers: [
+        MsalInterceptor,
+        MsalService,
+        MsalBroadcastService,
+        {
+          provide: HTTP_INTERCEPTORS,
+          useClass: MsalInterceptor,
+          multi: true,
+        },
+        Location,
+        provideHttpClient(withInterceptorsFromDi()),
+        provideHttpClientTesting(),
+        provideRouter([]),
+      ],
+      teardown: { destroyAfterEach: false },
+    });
+
+    const spy = spyOn(TestBed.inject(MsalService).getLogger(), "warning");
+    interceptor = TestBed.inject(MsalInterceptor);
+    return spy;
+  }
+
+  it("warns when strictMatching is undefined", () => {
+    const spy = initializeAndSpyOnWarning(undefined);
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.calls.first().args[0]).toContain(
+      "[MSAL] strictMatching is enabled by default"
+    );
+  });
+
+  it("does not warn when strictMatching is true", () => {
+    expect(initializeAndSpyOnWarning(true)).not.toHaveBeenCalled();
+  });
+
+  it("does not warn when strictMatching is false", () => {
+    expect(initializeAndSpyOnWarning(false)).not.toHaveBeenCalled();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // matchPatternStrict / matchPattern helper tests
 // ---------------------------------------------------------------------------
@@ -1245,7 +1304,7 @@ describe("matchPatternStrict unit tests", () => {
       string,
       Array<string | ProtectedResourceScopes> | null
     >();
-    initializeMsalStrict(emptyMap);
+    initializeMsalStrict(emptyMap, true);
     match = (interceptor as any).matchPatternStrict.bind(interceptor);
   });
 
@@ -1412,7 +1471,7 @@ describe("msal.interceptor matchPatternStrict", () => {
 
   describe("host wildcard matching", () => {
     beforeEach(() => {
-      initializeMsalStrict(hostwildcardMap);
+      initializeMsalStrict(hostwildcardMap, true);
     });
 
     it("msal.interceptor matchPatternStrict: host wildcard matches a single-label subdomain", (done) => {
@@ -1501,7 +1560,7 @@ describe("msal.interceptor matchPatternStrict", () => {
     >([["https://myapplication.com/user/*", ["customscope.read"]]]);
 
     beforeEach(() => {
-      initializeMsalStrict(pathMap);
+      initializeMsalStrict(pathMap, true);
     });
 
     it("msal.interceptor matchPatternStrict: pathname wildcard matches expected segments", (done) => {
@@ -1630,8 +1689,7 @@ describe("MsalInterceptor - strictMatching option", () => {
     ]);
 
     beforeEach(() => {
-      // No strictMatching field set — should default to strict (v5)
-      initializeMsalStrict(defaultStrictMap);
+      initializeMsalStrict(defaultStrictMap, true);
     });
 
     it("MsalInterceptor: attaches authorization header only when URL components match configured pattern", (done) => {
@@ -1719,7 +1777,7 @@ describe("MsalInterceptor - strictMatching option", () => {
     >([["https://*.microsoft.com", ["microsoft.scope"]]]);
 
     beforeEach(() => {
-      initializeMsalStrict(microsoftResourceMap);
+      initializeMsalStrict(microsoftResourceMap, true);
     });
 
     it("does not attach authorization header when the matched hostname appears only in the query string", (done) => {

lib/msal-angular/src/msal.interceptor.ts

@@ -43,6 +43,15 @@ export class MsalInterceptor implements HttpInterceptor {
     @Inject(DOCUMENT) document?: any
   ) {
     this._document = document as Document;
+
+    if (this.msalInterceptorConfig.strictMatching === undefined) {
+      this.authService
+        .getLogger()
+        .warning(
+          `[MSAL] strictMatching is enabled by default. See: https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/docs/msal-interceptor.md#strict-matching-strictmatching`,
+          ""
+        );
+    }
   }
 
   intercept(