Custom Auth: add requestInterceptor for custom x-* request headers (#8587)

## Summary

Adds a new `requestInterceptor` option to `CustomAuthOptions` that lets
applications attach additional `x-*` headers to every custom-auth
backend request (sign-in, sign-up, reset-password, register).

The primary use case is integrating with third-party fraud /
bot-detection SDKs that require vendor-supplied headers on the auth
endpoints.

## API

```ts
import { CustomAuthRequestInterceptor } from "@azure/msal-browser/custom-auth";

const interceptor: CustomAuthRequestInterceptor = {
    addAdditionalHeaderFields(requestUrl: URL) {
        if (requestUrl.pathname.includes("/oauth2/v2.0/initiate")) {
            return {
                value_1: "customer_header_1",          // Ignored: no "x-" prefix
                "x-client-header": "customer_header_2",  // Ignored: reserved prefix
                "X-my-custom-header": "my data",         // Sent
            };
        }
        return null;
    },
};

const config: CustomAuthConfiguration = {
    auth: { clientId, authority },
    customAuth: {
        authApiProxyUrl,
        requestInterceptor: interceptor,
    },
};
```

The interceptor may return either a synchronous record or a `Promise`.

## Filter rules (same as iOS doc)

* Names must start with `x-` (case-insensitive); others are dropped.
* Reserved prefixes are dropped: `x-client-`, `x-ms-`, `x-broker-`,
`x-app-`.
* User headers that pass the filter take precedence over MSAL's common
headers.
* Exceptions thrown by the interceptor are captured and logged via
`Logger.warningPii`; the request still goes through so user-supplied
code cannot break authentication.

## Scope

* Filtering applied only to custom-auth backend requests (anything
routed through `BaseApiClient.request`).
* Wiring: `CustomAuthStandardController` → `CustomAuthApiClient` → each
sub-client (`SignInApiClient`, `SignupApiClient`,
`ResetPasswordApiClient`, `RegisterApiClient`) → `BaseApiClient`.
* No cache schema impact.

## Tests

* `CustomHeaderUtils.spec.ts` — 16 cases covering each filter rule,
casing, and edge cases.
* `BaseApiClientInterceptor.spec.ts` — 8 cases covering: no-interceptor,
URL passed to interceptor, filtering, precedence, sync return, async
return, null return, sync throw, async rejection (all swallowed).
* `CustomAuthApiClient.spec.ts` extended with 2 construction cases.
* Full `lib/msal-browser` suite: **1643 tests pass**; lint, format,
build, and api-extractor all clean.

## Changefile

`change/@azure-msal-browser-ec2f3299-….json` — `minor` (new public
option).

---------

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

Author: shenj

change/@azure-msal-browser-ec2f3299-3059-4820-b675-ab278d78e0ae.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Custom Auth: add `requestInterceptor` configuration option that lets apps attach additional `x-*` headers to custom-auth backend requests (e.g., for fraud/bot-detection vendors). Headers without the `x-` prefix and headers starting with reserved prefixes (`x-client-`, `x-ms-`, `x-broker-`, `x-app-`) are filtered out. [#8587](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/8587)",
+  "packageName": "@azure/msal-browser",
+  "email": "shen.jian@live.com",
+  "dependentChangeType": "patch"
+}

lib/msal-browser/src/custom_auth/CustomAuthConstants.ts

@@ -33,6 +33,16 @@ export const HttpHeaderKeys = {
     X_MS_REQUEST_ID: "x-ms-request-id",
 } as const;
 
+export const CustomHeaderConstants = {
+    REQUIRED_PREFIX: "x-",
+    RESERVED_PREFIXES: [
+        "x-client-",
+        "x-ms-",
+        "x-broker-",
+        "x-app-",
+    ] as ReadonlyArray<string>,
+} as const;
+
 export const DefaultPackageInfo = {
     SKU: "msal.browser",
     VERSION: version,

lib/msal-browser/src/custom_auth/configuration/CustomAuthConfiguration.ts

@@ -7,12 +7,14 @@ import {
     BrowserConfiguration,
     Configuration,
 } from "../../config/Configuration.js";
+import { CustomAuthRequestInterceptor } from "./CustomAuthRequestInterceptor.js";
 
 export type CustomAuthOptions = {
     challengeTypes?: Array<string>;
     authApiProxyUrl: string;
     customAuthApiQueryParams?: Record<string, string>;
     capabilities?: Array<string>;
+    requestInterceptor?: CustomAuthRequestInterceptor;
 };
 
 export type CustomAuthConfiguration = Configuration & {

lib/msal-browser/src/custom_auth/configuration/CustomAuthRequestInterceptor.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Result type returned by {@link CustomAuthRequestInterceptor.addAdditionalHeaderFields}.
+ *
+ * Implementations may return either a synchronous value or a `Promise` resolving to one of
+ * the following:
+ * - A `Record<string, string>` of additional headers to add to the outgoing request.
+ * - `null` (or `undefined`) when no additional headers should be added for the request.
+ */
+export type CustomAuthAdditionalHeaderFieldsResult =
+    | Record<string, string>
+    | null
+    | undefined;
+
+/**
+ * Interface for intercepting custom auth network requests in order to attach additional
+ * headers to outgoing requests.
+ *
+ * Implementations are invoked by MSAL before each backend request used by custom auth
+ * (sign-in, sign-up, reset-password, and register endpoints). Use this hook to integrate
+ * with third-party fraud and bot-detection SDKs that require custom `x-*` headers.
+ *
+ * MSAL applies the following rules when evaluating the headers you provide:
+ * - Headers must start with `x-` (case-insensitive). Headers that don't start with `x-`
+ *   are ignored.
+ * - Headers that start with any of the following reserved prefixes are ignored:
+ *   `x-client-`, `x-ms-`, `x-broker-`, `x-app-`.
+ * - Headers that pass both rules are added to the network request. If a header you
+ *   provide has the same name as one of MSAL's own internal headers, your value takes
+ *   precedence.
+ */
+export interface CustomAuthRequestInterceptor {
+    /**
+     * Returns additional headers to add to a custom-auth network request.
+     *
+     * Scope your headers to specific endpoints by inspecting `requestUrl`. Sending
+     * headers to unrelated endpoints can degrade signal quality and increase false
+     * positives for fraud/bot-detection vendors.
+     *
+     * @param requestUrl - The full URL of the outgoing custom-auth request.
+     * @returns A record of headers to add (or `null`/`undefined` if no extra headers
+     *          are needed for the request). May be returned synchronously or as a
+     *          `Promise`.
+     */
+    addAdditionalHeaderFields(
+        requestUrl: URL
+    ):
+        | CustomAuthAdditionalHeaderFieldsResult
+        | Promise<CustomAuthAdditionalHeaderFieldsResult>;
+}

lib/msal-browser/src/custom_auth/controller/CustomAuthStandardController.ts

@@ -125,7 +125,9 @@ export class CustomAuthStandardController
                     this.customAuthConfig.auth.clientId,
                     new FetchHttpClient(this.logger),
                     this.customAuthConfig.customAuth?.capabilities?.join(" "),
-                    this.customAuthConfig.customAuth?.customAuthApiQueryParams
+                    this.customAuthConfig.customAuth?.customAuthApiQueryParams,
+                    this.customAuthConfig.customAuth?.requestInterceptor,
+                    this.logger
                 ),
             this.authority
         );

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/BaseApiClient.ts

@@ -17,9 +17,12 @@ import {
 } from "../../error/CustomAuthApiError.js";
 import {
     AADServerParamKeys,
+    Logger,
     ServerTelemetryManager,
 } from "@azure/msal-common/browser";
 import { ApiErrorResponse } from "./types/ApiErrorResponseTypes.js";
+import { CustomAuthRequestInterceptor } from "../../../configuration/CustomAuthRequestInterceptor.js";
+import { filterCustomHeaders } from "../../utils/CustomHeaderUtils.js";
 
 export abstract class BaseApiClient {
     private readonly baseRequestUrl: URL;
@@ -28,7 +31,9 @@ export abstract class BaseApiClient {
         baseUrl: string,
         private readonly clientId: string,
         private httpClient: IHttpClient,
-        private customAuthApiQueryParams?: Record<string, string>
+        private customAuthApiQueryParams?: Record<string, string>,
+        private requestInterceptor?: CustomAuthRequestInterceptor,
+        private logger?: Logger
     ) {
         this.baseRequestUrl = parseUrl(
             !baseUrl.endsWith("/") ? `${baseUrl}/` : baseUrl
@@ -45,13 +50,23 @@ export abstract class BaseApiClient {
             client_id: this.clientId,
             ...data,
         });
-        const headers = this.getCommonHeaders(correlationId, telemetryManager);
+        const commonHeaders = this.getCommonHeaders(
+            correlationId,
+            telemetryManager
+        );
         const url = buildUrl(
             this.baseRequestUrl.href,
             endpoint,
             this.customAuthApiQueryParams
         );
 
+        const additionalHeaders = await this.getAdditionalHeaders(
+            url,
+            correlationId
+        );
+
+        const headers = { ...commonHeaders, ...additionalHeaders };
+
         let response: Response;
 
         try {
@@ -173,4 +188,28 @@ export abstract class BaseApiClient {
             responseError.timestamp
         );
     }
+
+    private async getAdditionalHeaders(
+        url: URL,
+        correlationId: string
+    ): Promise<Record<string, string>> {
+        if (!this.requestInterceptor) {
+            return {};
+        }
+
+        try {
+            const result = await Promise.resolve(
+                this.requestInterceptor.addAdditionalHeaderFields(url)
+            );
+
+            return filterCustomHeaders(result, this.logger, correlationId);
+        } catch (e) {
+            this.logger?.warningPii(
+                `CustomAuthRequestInterceptor.addAdditionalHeaderFields threw an error; continuing without additional headers: ${e}`,
+                correlationId
+            );
+
+            return {};
+        }
+    }
 }

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/CustomAuthApiClient.ts

@@ -9,6 +9,8 @@ import { SignInApiClient } from "./SignInApiClient.js";
 import { RegisterApiClient } from "./RegisterApiClient.js";
 import { ICustomAuthApiClient } from "./ICustomAuthApiClient.js";
 import { IHttpClient } from "../http_client/IHttpClient.js";
+import { Logger } from "@azure/msal-common/browser";
+import { CustomAuthRequestInterceptor } from "../../../configuration/CustomAuthRequestInterceptor.js";
 
 export class CustomAuthApiClient implements ICustomAuthApiClient {
     signInApi: SignInApiClient;
@@ -21,34 +23,44 @@ export class CustomAuthApiClient implements ICustomAuthApiClient {
         clientId: string,
         httpClient: IHttpClient,
         capabilities?: string,
-        customAuthApiQueryParams?: Record<string, string>
+        customAuthApiQueryParams?: Record<string, string>,
+        requestInterceptor?: CustomAuthRequestInterceptor,
+        logger?: Logger
     ) {
         this.signInApi = new SignInApiClient(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
             capabilities,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
         this.signUpApi = new SignupApiClient(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
             capabilities,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
         this.resetPasswordApi = new ResetPasswordApiClient(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
             capabilities,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
         this.registerApi = new RegisterApiClient(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
     }
 }

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/ResetPasswordApiClient.ts

@@ -10,6 +10,7 @@ import {
 import { CustomAuthApiError } from "../../error/CustomAuthApiError.js";
 import { BaseApiClient } from "./BaseApiClient.js";
 import { IHttpClient } from "../http_client/IHttpClient.js";
+import { Logger } from "@azure/msal-common/browser";
 import * as CustomAuthApiEndpoint from "./CustomAuthApiEndpoint.js";
 import * as CustomAuthApiErrorCode from "./types/ApiErrorCodes.js";
 import {
@@ -26,6 +27,7 @@ import {
     ResetPasswordStartResponse,
     ResetPasswordSubmitResponse,
 } from "./types/ApiResponseTypes.js";
+import { CustomAuthRequestInterceptor } from "../../../configuration/CustomAuthRequestInterceptor.js";
 
 export class ResetPasswordApiClient extends BaseApiClient {
     private readonly capabilities?: string;
@@ -35,13 +37,17 @@ export class ResetPasswordApiClient extends BaseApiClient {
         clientId: string,
         httpClient: IHttpClient,
         capabilities?: string,
-        customAuthApiQueryParams?: Record<string, string>
+        customAuthApiQueryParams?: Record<string, string>,
+        requestInterceptor?: CustomAuthRequestInterceptor,
+        logger?: Logger
     ) {
         super(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
         this.capabilities = capabilities;
     }

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/SignInApiClient.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ServerTelemetryManager } from "@azure/msal-common/browser";
+import { Logger, ServerTelemetryManager } from "@azure/msal-common/browser";
 import { GrantType } from "../../../CustomAuthConstants.js";
 import { CustomAuthApiError } from "../../error/CustomAuthApiError.js";
 import { BaseApiClient } from "./BaseApiClient.js";
@@ -24,6 +24,7 @@ import {
     SignInIntrospectResponse,
     SignInTokenResponse,
 } from "./types/ApiResponseTypes.js";
+import { CustomAuthRequestInterceptor } from "../../../configuration/CustomAuthRequestInterceptor.js";
 
 export class SignInApiClient extends BaseApiClient {
     private readonly capabilities?: string;
@@ -33,13 +34,17 @@ export class SignInApiClient extends BaseApiClient {
         clientId: string,
         httpClient: IHttpClient,
         capabilities?: string,
-        customAuthApiQueryParams?: Record<string, string>
+        customAuthApiQueryParams?: Record<string, string>,
+        requestInterceptor?: CustomAuthRequestInterceptor,
+        logger?: Logger
     ) {
         super(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
         this.capabilities = capabilities;
     }

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/SignupApiClient.ts

@@ -6,6 +6,7 @@
 import { GrantType } from "../../../CustomAuthConstants.js";
 import { BaseApiClient } from "./BaseApiClient.js";
 import { IHttpClient } from "../http_client/IHttpClient.js";
+import { Logger } from "@azure/msal-common/browser";
 import * as CustomAuthApiEndpoint from "./CustomAuthApiEndpoint.js";
 import {
     SignUpChallengeRequest,
@@ -19,6 +20,7 @@ import {
     SignUpContinueResponse,
     SignUpStartResponse,
 } from "./types/ApiResponseTypes.js";
+import { CustomAuthRequestInterceptor } from "../../../configuration/CustomAuthRequestInterceptor.js";
 
 export class SignupApiClient extends BaseApiClient {
     private readonly capabilities?: string;
@@ -28,13 +30,17 @@ export class SignupApiClient extends BaseApiClient {
         clientId: string,
         httpClient: IHttpClient,
         capabilities?: string,
-        customAuthApiQueryParams?: Record<string, string>
+        customAuthApiQueryParams?: Record<string, string>,
+        requestInterceptor?: CustomAuthRequestInterceptor,
+        logger?: Logger
     ) {
         super(
             customAuthApiBaseUrl,
             clientId,
             httpClient,
-            customAuthApiQueryParams
+            customAuthApiQueryParams,
+            requestInterceptor,
+            logger
         );
         this.capabilities = capabilities;
     }