Add NativeAuthRequestInterceptor for custom per-request headers and UI Automation, Fixes AB#3600652 (#3112)

Implement custom HTTP headers request interceptor for native auth CIAM
requests

- Add NativeAuthHeaderValidator to enforce header naming rules
- Pass interceptor through the full config propagation chain:
OAuth2StrategyParameters → NativeAuthCIAMAuthority →
NativeAuthOAuth2Configuration → NativeAuthOAuth2StrategyFactory → all 4
interactors (SignIn, SignUp, ResetPassword, JIT)
- Add interceptor field to BaseNativeAuthCommandParameters
- Wire interceptor in NativeAuthMsalController.createOAuth2Strategy()
- Add unit tests for header validation
- Add integration tests for interceptor in all interactors

### UI Automation Test Support
- **`NativeAuthSampleApp.java`** — App model class for UI automation
(package name, APK filename constants, no-op
`handleFirstRun()`/`initialiseAppImpl()`)
- **`CopyFileRule.java`** — Added
`NativeAuthSampleApp.NATIVE_AUTH_SAMPLE_APK` to the list of APKs copied
from `/sdcard/` to `/data/local/tmp/` at test runtime
- **`LabConstants.java`** — Added `CIAM` user type constant
- **`UserType.java`** — Added `CIAM` enum value for lab queries

### API Change: NativeAuthRequestInterceptor moved to MSAL

The `NativeAuthRequestInterceptor` interface has been moved to the MSAL
module (`com.microsoft.identity.nativeauth` package) as it is a
public-facing type that customers implement. Common now uses the base
`OAuth2RequestInterceptor` type internally, which
`NativeAuthRequestInterceptor` extends. This follows the established
pattern where public nativeauth types live in MSAL.


[AB#3600652](https://identitydivision.visualstudio.com/Engineering/_workitems/edit/3600652)

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: fadidurah <fadidurah@microsoft.com>
Co-authored-by: fadidurah <88730756+fadidurah@users.noreply.github.com>

Author: 4 people

LabApiUtilities/src/main/com/microsoft/identity/labapi/utilities/constants/LabConstants.java

@@ -62,6 +62,7 @@ static final class UserType {
         public static final String ONPREM = "onprem";
         public static final String GUEST = "guest";
         public static final String B2C = "b2c";
+        public static final String CIAM = "ciam";
     }
 
     static final class UserRole {

LabApiUtilities/src/main/com/microsoft/identity/labapi/utilities/constants/UserType.java

@@ -52,7 +52,8 @@ public enum UserType {
     CLOUD(LabConstants.UserType.CLOUD),
     B2C(LabConstants.UserType.B2C),
     GUEST(LabConstants.UserType.GUEST),
-    ONPREM(LabConstants.UserType.ONPREM);
+    ONPREM(LabConstants.UserType.ONPREM),
+    CIAM(LabConstants.UserType.CIAM);
 
     final String value;
 

changelog.txt

@@ -15,6 +15,7 @@ vNext
 - [PATCH] Extend filter-then-clone optimization to load() and getIdTokensForAccountRecord() in MsalOAuth2TokenCache: when ENABLE_FILTER_THEN_CLONE_IN_MEMORY_CACHE flight is enabled, skip clone-all preload and call direct flight-gated overloads that clone only matching credentials; add new getCredentialsFilteredBy overload with kid support (#3100)
 - [MINOR] Add onboarding telemetry recorder, field keys, and session persistence for mobile onboarding flow (#3088)
 - [PATCH] Move Multiple Listening apps check to the authorization layer (#3070)
+- [MINOR] Add NativeAuthRequestInterceptor for custom per-request headers in native auth flows (#3112)
 - [PATCH] Edge TB: Fix lookup mode (#3108)
 
 Version 24.2.0

common/src/main/java/com/microsoft/identity/common/nativeauth/internal/controllers/NativeAuthMsalController.kt

@@ -2710,6 +2710,7 @@ class NativeAuthMsalController : BaseNativeAuthController() {
             .platformComponents(parameters.platformComponents)
             .challengeTypes(parameters.challengeType)
             .capabilities(parameters.capabilities)
+            .requestInterceptor(parameters.requestInterceptor)
             .build()
 
         return parameters

common4j/src/main/com/microsoft/identity/common/java/nativeauth/authorities/NativeAuthCIAMAuthority.kt

@@ -32,6 +32,7 @@ import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthConstan
 import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthOAuth2Configuration
 import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthOAuth2Strategy
 import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthOAuth2StrategyFactory
+import com.microsoft.identity.common.java.providers.oauth2.OAuth2RequestInterceptor
 import com.microsoft.identity.common.java.providers.oauth2.OAuth2StrategyParameters
 
 /**
@@ -76,7 +77,7 @@ class NativeAuthCIAMAuthority (
         mAuthorityUrlString = authorityUrl
     }
 
-    private fun createNativeAuthOAuth2Configuration(challengeTypes: List<String>?, capabilities: List<String>?): NativeAuthOAuth2Configuration {
+    private fun createNativeAuthOAuth2Configuration(challengeTypes: List<String>?, capabilities: List<String>?, requestInterceptor: OAuth2RequestInterceptor?): NativeAuthOAuth2Configuration {
        LogSession.logMethodCall(
            tag = TAG,
            correlationId = null,
@@ -86,7 +87,8 @@ class NativeAuthCIAMAuthority (
             authorityUrl = this.authorityURL,
             clientId = this.clientId,
             challengeType = getChallengeTypesWithDefault(challengeTypes),
-            capabilities = getCapabilities(capabilities)
+            capabilities = getCapabilities(capabilities),
+            requestInterceptor = requestInterceptor
         )
     }
 
@@ -123,7 +125,11 @@ class NativeAuthCIAMAuthority (
 
     @Throws(ClientException::class)
     override fun createOAuth2Strategy(parameters: OAuth2StrategyParameters): NativeAuthOAuth2Strategy {
-        val config = createNativeAuthOAuth2Configuration(parameters.mChallengeTypes, parameters.mCapabilities)
+        val config = createNativeAuthOAuth2Configuration(
+            parameters.mChallengeTypes,
+            parameters.mCapabilities,
+            parameters.mRequestInterceptor
+        )
 
         // CIAM Authorities can fetch endpoints from open id configuration. We disable this option.
         parameters.setUsingOpenIdConfiguration(NATIVE_AUTH_USE_OPENID_CONFIGURATION)

common4j/src/main/com/microsoft/identity/common/java/nativeauth/commands/parameters/BaseNativeAuthCommandParameters.java

@@ -26,6 +26,7 @@
 import com.microsoft.identity.common.java.commands.parameters.CommandParameters;
 import com.microsoft.identity.common.java.logging.Logger;
 import com.microsoft.identity.common.java.nativeauth.authorities.NativeAuthCIAMAuthority;
+import com.microsoft.identity.common.java.providers.oauth2.OAuth2RequestInterceptor;
 import com.microsoft.identity.common.java.nativeauth.util.ILoggable;
 
 import java.util.List;
@@ -62,6 +63,13 @@ public abstract class BaseNativeAuthCommandParameters extends CommandParameters
     @Nullable
     public final List<String> capabilities;
 
+    /**
+     * An optional interceptor for injecting custom HTTP headers into native auth requests.
+     */
+    @Nullable
+    @EqualsAndHashCode.Exclude
+    public final transient OAuth2RequestInterceptor requestInterceptor;
+
     @Override
     public void logParameters(String tag, String correlationId) {
         Logger.infoWithObject(tag, null, correlationId, this);

common4j/src/main/com/microsoft/identity/common/java/nativeauth/providers/NativeAuthHeaderValidator.kt

@@ -0,0 +1,77 @@
+//  Copyright (c) Microsoft Corporation.
+//  All rights reserved.
+//
+//  This code is licensed under the MIT License.
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files(the "Software"), to deal
+//  in the Software without restriction, including without limitation the rights
+//  to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+//  copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions :
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+package com.microsoft.identity.common.java.nativeauth.providers
+
+import com.microsoft.identity.common.java.logging.Logger
+
+/**
+ * Validates custom headers provided by an [OAuth2RequestInterceptor].
+ * Enforces that header names start with "x-" and do not use reserved prefixes.
+ */
+object NativeAuthHeaderValidator {
+
+    private val TAG = NativeAuthHeaderValidator::class.java.simpleName
+
+    private val RESERVED_PREFIXES = listOf("x-ms-", "x-client-", "x-broker-", "x-app-")
+
+    /**
+     * Filters a map of headers, returning only those that are valid per the interceptor contract.
+     * Invalid headers are logged as warnings and excluded from the result.
+     *
+     * @param headers The raw headers provided by the interceptor.
+     * @return A map containing only valid headers using lowercase field names, or an empty map if none are valid.
+     */
+    fun filterValidHeaders(headers: Map<String, String>): Map<String, String> {
+        val validHeaders = mutableMapOf<String, String>()
+
+        for ((field, value) in headers) {
+            val lowerField = field.lowercase()
+
+            if (!lowerField.startsWith("x-")) {
+                Logger.warn(
+                    TAG,
+                    "Additional header field \"$field\" must start with the \"x-\" prefix. Ignoring."
+                )
+                continue
+            }
+
+            var isReserved = false
+            for (reserved in RESERVED_PREFIXES) {
+                if (lowerField.startsWith(reserved)) {
+                    Logger.warn(
+                        TAG,
+                        "Additional header field \"$field\" uses reserved prefix \"$reserved\". Ignoring."
+                    )
+                    isReserved = true
+                    break
+                }
+            }
+
+            if (!isReserved) {
+                validHeaders[lowerField] = value
+            }
+        }
+
+        return validHeaders
+    }
+}

common4j/src/main/com/microsoft/identity/common/java/nativeauth/providers/NativeAuthOAuth2Configuration.kt

@@ -26,6 +26,7 @@ package com.microsoft.identity.common.java.nativeauth.providers
 import com.microsoft.identity.common.java.nativeauth.BuildValues
 import com.microsoft.identity.common.java.logging.Logger
 import com.microsoft.identity.common.java.providers.microsoft.microsoftsts.MicrosoftStsOAuth2Configuration
+import com.microsoft.identity.common.java.providers.oauth2.OAuth2RequestInterceptor
 import com.microsoft.identity.common.java.util.UrlUtil
 import java.net.MalformedURLException
 import java.net.URISyntaxException
@@ -41,6 +42,7 @@ class NativeAuthOAuth2Configuration(
     val clientId: String,
     val challengeType: String,
     val capabilities: String?,
+    val requestInterceptor: OAuth2RequestInterceptor? = null,
     // Need this to decide whether or not to return mock api authority or actual authority supplied in configuration
     // Turn this on if you plan to use web auth and/or open id configuration
     val useMockApiForNativeAuth: Boolean = BuildValues.shouldUseMockApiForNativeAuth(),

common4j/src/main/com/microsoft/identity/common/java/nativeauth/providers/NativeAuthOAuth2StrategyFactory.kt

@@ -39,28 +39,33 @@ class NativeAuthOAuth2StrategyFactory {
             config: NativeAuthOAuth2Configuration,
             strategyParameters: OAuth2StrategyParameters,
         ): NativeAuthOAuth2Strategy {
+            val requestInterceptor = config.requestInterceptor
             return NativeAuthOAuth2Strategy(
                 strategyParameters = strategyParameters,
                 config = config,
                 signInInteractor = SignInInteractor(
                     httpClient = UrlConnectionHttpClient.getDefaultInstance(),
                     nativeAuthRequestProvider = NativeAuthRequestProvider(config = config),
-                    nativeAuthResponseHandler = NativeAuthResponseHandler()
+                    nativeAuthResponseHandler = NativeAuthResponseHandler(),
+                    requestInterceptor = requestInterceptor
                 ),
                 signUpInteractor = SignUpInteractor(
                     httpClient = UrlConnectionHttpClient.getDefaultInstance(),
                     nativeAuthRequestProvider = NativeAuthRequestProvider(config = config),
-                    nativeAuthResponseHandler = NativeAuthResponseHandler()
+                    nativeAuthResponseHandler = NativeAuthResponseHandler(),
+                    requestInterceptor = requestInterceptor
                 ),
                 resetPasswordInteractor = ResetPasswordInteractor(
                     httpClient = UrlConnectionHttpClient.getDefaultInstance(),
                     nativeAuthRequestProvider = NativeAuthRequestProvider(config = config),
-                    nativeAuthResponseHandler = NativeAuthResponseHandler()
+                    nativeAuthResponseHandler = NativeAuthResponseHandler(),
+                    requestInterceptor = requestInterceptor
                 ),
                 jitInteractor = JITInteractor(
                     httpClient = UrlConnectionHttpClient.getDefaultInstance(),
                     nativeAuthRequestProvider = NativeAuthRequestProvider(config = config),
-                    nativeAuthResponseHandler = NativeAuthResponseHandler()
+                    nativeAuthResponseHandler = NativeAuthResponseHandler(),
+                    requestInterceptor = requestInterceptor
                 )
             )
         }

common4j/src/main/com/microsoft/identity/common/java/nativeauth/providers/interactors/JITInteractor.kt

@@ -27,6 +27,7 @@ import com.microsoft.identity.common.java.logging.Logger
 import com.microsoft.identity.common.java.nativeauth.commands.parameters.JITChallengeAuthMethodCommandParameters
 import com.microsoft.identity.common.java.nativeauth.commands.parameters.JITIntrospectCommandParameters
 import com.microsoft.identity.common.java.nativeauth.commands.parameters.JITContinueCommandParameters
+import com.microsoft.identity.common.java.providers.oauth2.OAuth2RequestInterceptor
 import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthRequestProvider
 import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthResponseHandler
 import com.microsoft.identity.common.java.nativeauth.providers.requests.jit.JITChallengeRequest
@@ -51,7 +52,8 @@ import com.microsoft.identity.common.java.util.ObjectMapper
 class JITInteractor(
     private val httpClient: UrlConnectionHttpClient,
     private val nativeAuthRequestProvider: NativeAuthRequestProvider,
-    private val nativeAuthResponseHandler: NativeAuthResponseHandler
+    private val nativeAuthResponseHandler: NativeAuthResponseHandler,
+    private val requestInterceptor: OAuth2RequestInterceptor? = null
 ) {
     private val TAG: String = this::class.java.simpleName
 
@@ -94,7 +96,7 @@ class JITInteractor(
         )
         val encodedRequest: String =
             ObjectMapper.serializeObjectToFormUrlEncoded(request.parameters)
-        val headers = request.headers
+        val headers = applyInterceptorHeaders(request.requestUrl, request.headers, requestInterceptor)
         val requestUrl = request.requestUrl
 
         val response = httpClient.post(
@@ -169,7 +171,7 @@ class JITInteractor(
         )
         val encodedRequest: String =
             ObjectMapper.serializeObjectToFormUrlEncoded(request.parameters)
-        val headers = request.headers
+        val headers = applyInterceptorHeaders(request.requestUrl, request.headers, requestInterceptor)
         val requestUrl = request.requestUrl
 
         val response = httpClient.post(
@@ -243,7 +245,7 @@ class JITInteractor(
         )
         val encodedRequest: String =
             ObjectMapper.serializeObjectToFormUrlEncoded(request.parameters)
-        val headers = request.headers
+        val headers = applyInterceptorHeaders(request.requestUrl, request.headers, requestInterceptor)
         val requestUrl = request.requestUrl
 
         val response = httpClient.post(
@@ -275,4 +277,4 @@ class JITInteractor(
         return result
     }
     //endregion
-}
+}