Microsoft Entra ID
Authentication

Tutorial Native Authentication Single Page App Javascript Custom Headers

In brief

The JavaScript SPA tutorial for adding custom headers to Microsoft Entra External ID native authentication requests was deleted.

What Entra admins need to know

Administrators relying on this tutorial will no longer find it at the documented URL. No action is specified.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

deleted file mode 100644

title: Add custom headers to native authentication requests in JavaScript SPAs description: Learn how to attach custom x-* headers to native authentication requests in a React or Angular SPA to integrate fraud-detection SDKs with Microsoft Entra External ID. manager: dougeby ms.service: identity-platform ms.subservice: external ms.topic: tutorial ms.date: 05/20/2026 ms.custom: msecd-doc-authoring-1012 ai-usage: ai-assisted #Customer intent: As a JavaScript SPA developer using native authentication JavaScript SDK, I want to attach custom headers to network requests so that I can integrate fraud and bot-detection SDKs with my Microsoft Entra External ID app.

Tutorial: Add custom headers to network requests using native authentication JavaScript SDK

[!INCLUDE applies-to-external-only]

This tutorial shows you how to add custom x-* headers to native authentication network requests in a React or Angular single-page app (SPA). Use the CustomAuthRequestInterceptor from the native authentication JavaScript SDK to integrate with third-party fraud and bot-detection providers.

In this tutorial, you:

[!div class="checklist"]

  • Learn the header naming rules that our SDK enforces.
  • Register the interceptor on your app configuration.
  • Verify that your headers reach the intended endpoints.

Prerequisites

A React or Angular SPA that uses native authentication JavaScript SDK. If you don't have one, complete one of the following tutorials first:

Understand header naming rules

The Microsoft Authentication Library (MSAL) applies the following rules when it evaluates the headers that you provide. Use these rules to verify your vendor-required header names before you implement the interceptor:

  • Headers must start with x- (case-insensitive). MSAL ignores headers that don't start with x-.
  • MSAL ignores headers that start with any of the following reserved prefixes, because they're owned by the SDK:
    • x-client-
    • x-ms-
    • x-broker-
    • x-app-

MSAL adds any header that passes both rules to the network request. If a header name you provide conflicts with one the SDK would set, your value takes precedence.

Implement the request interceptor

The CustomAuthRequestInterceptor interface declares a single method, addAdditionalHeaderFields, that our SDK calls before it sends each native authentication network request. Your implementation receives the request URL and returns a dictionary of headers to add, or null if no headers are needed for that request.

  1. Open your app configuration file such as:

    • src/app/config/auth-config.ts for Angular.
    • src/config/auth-config.ts for React.
  2. Add the following interceptor above your existing customAuthConfig definition:

import { CustomAuthConfiguration, LogLevel } from "@azure/msal-browser/custom-auth";
import type { CustomAuthRequestInterceptor } from "@azure/msal-browser/custom-auth";

const requestInterceptor: CustomAuthRequestInterceptor = {
    addAdditionalHeaderFields(requestUrl: URL) {
        // Scope headers to specific endpoints only.
        if (requestUrl.pathname.endsWith("/oauth2/v2.0/initiate")) {
            return {
                value_1: "customer_header_1",            // Ignored: doesn't start with "x-".
                "x-client-header": "customer_header_2",  // Ignored: starts with reserved prefix "x-client-".
                "X-my-custom-header": "my data",         // Added to the network request.
            };
        }

        // Return null for all other requests to avoid over-sending signals.
        return null;
    },
};

The addAdditionalHeaderFields method receives the full URL of the outgoing request in requestUrl. Use the URL to scope your headers to the specific endpoints that your fraud or bot-detection vendor requires, such as sign-in or sign-up initiation endpoints. Sending headers to unrelated endpoints can degrade signal quality and increase false positives.

Register the interceptor

After you implement the interceptor, assign it to the requestInterceptor property on the customAuth block of your CustomAuthConfiguration:

export const customAuthConfig: CustomAuthConfiguration = {
    customAuth: {
        challengeTypes: ["password", "oob", "redirect"],
        authApiProxyUrl: "http://localhost:3001/api",
        requestInterceptor: requestInterceptor,
    },
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        // ...
    },
};

The configuration is identical for both React and Angular.

Verify headers are applied

To confirm that your headers reach the intended endpoints, inspect the outgoing network traffic by using your browser's developer tools (Network tab) or a network proxy tool such as Fiddler. Check that:

  • Headers that start with x- and don't use a reserved prefix appear in the request.
  • Headers that use reserved prefixes (x-client-, x-ms-, x-broker-, x-app-) don't appear in the request.
  • Headers appear only on the endpoints you targeted in your interceptor.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…