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

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
-}
+}

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

@@ -0,0 +1,65 @@
+// 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.interactors
+
+import com.microsoft.identity.common.java.nativeauth.providers.NativeAuthHeaderValidator
+import com.microsoft.identity.common.java.providers.oauth2.OAuth2RequestInterceptor
+import java.net.URL
+
+/**
+ * Applies additional interceptor headers to the base request headers for native auth interactors.
+ *
+ * Interceptor headers replace matching base headers regardless of casing. Interceptor headers are
+ * first validated and normalized to lowercase by [NativeAuthHeaderValidator], which filters out
+ * any non-`x-` prefixed headers and reserved prefixes (`x-ms-`, `x-client-`, `x-broker-`, `x-app-`). 
+ * This ensures that mandatory SDK headers (e.g., `Content-Type`, `x-client-SKU`) cannot be 
+ * overwritten by the interceptor, since they either lack the `x-` prefix or use a reserved prefix.
+ *
+ * @param requestUrl The outbound request URL.
+ * @param headers The base request headers.
+ * @param requestInterceptor Optional interceptor providing additional headers.
+ * @return The merged headers map with interceptor values taking precedence for valid custom headers.
+ */
+internal fun applyInterceptorHeaders(
+    requestUrl: URL,
+    headers: Map<String, String?>,
+    requestInterceptor: OAuth2RequestInterceptor?
+): Map<String, String?> {
+    if (requestInterceptor == null) return headers
+
+    val additionalHeaders = requestInterceptor.additionalHeaders(requestUrl) ?: return headers
+    // For case-insensitive merge, the headers in RESERVED_PREFIXES are filtered out
+    val validHeaders = NativeAuthHeaderValidator.filterValidHeaders(additionalHeaders)
+    if (validHeaders.isEmpty()) return headers
+
+    val mergedHeaders = headers.toMutableMap()
+    for ((field, value) in validHeaders) {
+        val existingHeader = mergedHeaders.keys.firstOrNull { it.equals(field, ignoreCase = true) }
+        if (existingHeader != null) {
+            mergedHeaders.remove(existingHeader)
+        }
+        mergedHeaders[field] = value
+    }
+
+    return mergedHeaders
+}