Microsoft Entra ID
Authentication

Tutorial Native Authentication Android Custom Headers

In brief

The documentation page explaining how Android apps can add custom x-* headers to native authentication requests using MSAL was deleted.

What Entra admins need to know

No administrator action is stated. Teams supporting this External ID integration should note that the tutorial is no longer available.

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 Android (Kotlin) description: Learn how to attach custom x-* headers to native authentication network requests in an Android (Kotlin) app to integrate fraud-detection SDKs with Microsoft Entra External ID. ms.service: identity-platform ms.subservice: external ms.topic: tutorial ms.custom: msecd-doc-authoring-105 ms.date: 05/15/2026 ai-usage: ai-assisted #Customer intent: As an Android developer, I want to attach custom headers to native authentication network requests so that I can integrate fraud and bot-detection SDKs with my Microsoft Entra External ID app.

Tutorial: Add custom headers to native authentication network requests in Android (Kotlin)

[!INCLUDE applies-to-external-only]

This tutorial demonstrates how to attach custom x-* headers to native authentication network requests in your Android (Kotlin) app using the Microsoft Authentication Library (MSAL) NativeAuthRequestInterceptor interface, enabling integration with third-party fraud and bot-detection SDKs.

In this tutorial, you:

[!div class="checklist"]

  • Understand the header naming rules enforced by MSAL.
  • Implement the NativeAuthRequestInterceptor interface.
  • Register the interceptor with your app configuration.

Prerequisites

Understand header naming rules

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-
  • Valid headers are normalized to lowercase before being added to the request.
  • MSAL adds headers that pass both rules 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.

Use these rules to verify your vendor-required header names before implementing the interceptor.

Implement the request interceptor

The NativeAuthRequestInterceptor interface declares a single method that MSAL calls synchronously before it sends each network request. Your implementation receives the request URL and returns a map of headers to add, or null if no headers are needed for that request.

Create a class that implements NativeAuthRequestInterceptor:

import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthRequestInterceptor
import java.net.URL

class CustomHeaderInterceptor : NativeAuthRequestInterceptor {

    override fun additionalHeaders(requestUrl: URL): Map<String, String>? {
        // Scope headers to specific endpoints only.
        if (requestUrl.path.contains("oauth2/v2.0/initiate")) {
            return mapOf(
                "value_1" to "customer_header_1",          // Ignored: doesn't start with "x-"
                "x-client-header" to "customer_header_2",  // Ignored: starts with reserved prefix "x-client-"
                "X-my-custom-header" to "my data"          // Added to the network request (lowercased to "x-my-custom-header").
            )
        }

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

The method receives the full URL of the outgoing request in requestUrl. Use this URL to scope your headers to the specific endpoints 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 implementing the interface, set the requestInterceptor property on your app's NativeAuthPublicClientApplicationConfiguration. If your app initializes the auth client with a JSON configuration file (such as app/src/main/res/raw/native_auth_sample_app_config.json), set the interceptor on the configuration after creating the client:

import com.microsoft.identity.client.PublicClientApplication
import com.microsoft.identity.nativeauth.INativeAuthPublicClientApplication
import com.microsoft.identity.nativeauth.NativeAuthPublicClientApplicationConfiguration

val authClient: INativeAuthPublicClientApplication =
    PublicClientApplication.createNativeAuthPublicClientApplication(
        context,
        R.raw.native_auth_sample_app_config
    )

(authClient as? PublicClientApplication)?.let { app ->
    (app.configuration as? NativeAuthPublicClientApplicationConfiguration)?.requestInterceptor =
        CustomHeaderInterceptor()
}

If your app uses programmatic configuration, set the requestInterceptor property on your NativeAuthPublicClientApplicationParameters instance before creating the application:

import com.microsoft.identity.client.PublicClientApplication
import com.microsoft.identity.nativeauth.INativeAuthPublicClientApplication
import com.microsoft.identity.nativeauth.NativeAuthPublicClientApplicationParameters

val parameters = NativeAuthPublicClientApplicationParameters(
    clientId = "Enter_the_Application_Id_Here",
    authorityUrl = "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/",
    challengeTypes = listOf("oob", "password")
)
parameters.requestInterceptor = CustomHeaderInterceptor()

val authClient: INativeAuthPublicClientApplication =
    PublicClientApplication.createNativeAuthPublicClientApplication(
        context,
        parameters
    )

Verify headers are applied

To confirm that your headers reach the intended endpoints, inspect the outgoing network traffic using a network proxy tool such as Charles Proxy or the Android Studio Network Inspector. Check that:

  • Headers starting with x- and without reserved prefixes appear in the request.
  • Headers with reserved prefixes (x-client-, x-ms-, x-broker-, x-app-) don't appear in the request.
  • Headers are sent only to the endpoints you scoped them to.
  • Valid header names are lowercased in the outgoing request.

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…