Broker IPC plumbing for onboarding telemetry blob, Fixes AB#3568357 (#3111)

Adds the IPC plumbing for the onboarding telemetry blob to flow
client↔broker. Independent of PR #3088 (which adds the
recorder/store/constants); both are needed together for end-to-end
brokered onboarding telemetry.

Linked Feature:
[AB#3462876](https://identitydivision.visualstudio.com/fac9d424-53d2-45c0-91b5-ef6ba7a6bf26/_workitems/edit/3462876)
Linked PBI:
[AB#3568357](https://identitydivision.visualstudio.com/fac9d424-53d2-45c0-91b5-ef6ba7a6bf26/_workitems/edit/3568357)

| File | Change |
|---|---|
| `BrokerRequest.java` | Add `onboarding_seed_json` field (client →
broker) |
| `BrokerResult.java` | Add `onboarding_blob` field + builder + getter
(broker → client) |
| `InteractiveTokenCommandParameters.java` | Add `onboardingSeedJson`
field on the params builder |
| `AcquireTokenResult.java` | Add `onboardingBlob` field for carrying
the populated blob through the result chain |
| `MsalBrokerRequestAdapter.java` | Serialize `onboardingSeedJson` from
command parameters into `BrokerRequest` |
| `MsalBrokerResultAdapter.java` | Extract `onboardingBlob` from
`BrokerResult` into `AcquireTokenResult` |

All additions are pure data fields + adapter wiring. No behavior change
for existing callers (fields default to empty/null when not set).

- **Direction `client → broker`**: OneAuth/MSAL builds the seed JSON
(containing `sessionCorrelationId`, `onboardingMode`, `schema_version`)
and attaches it to the interactive request. The broker reads it via the
new field on `BrokerInteractiveTokenCommandParameters`, constructs its
own `OnboardingTelemetryRecorder` from the seed, and uses the same
correlation ID for its onboarding telemetry events.
- **Direction `broker → client`**: When the broker emits the populated
onboarding blob (after `finalizeBlob()`), it places it into
`BrokerResult.onboarding_blob`. The client extracts it into
`AcquireTokenResult.onboardingBlob`, where downstream OneAuth code reads
it and emits the blob through MATS.

See full design: [Mobile Onboarding Telemetry
Design](https://identitydivision.visualstudio.com/Engineering/_workitems/edit/3462876)
§6.6 (persistence and propagation) and §11.2 (broker → OneAuth blob
delivery).

- **Pairs with**: PR #3088 (`OnboardingTelemetryRecorder` +
`OnboardingTelemetryConstants` + `OnboardingSessionCorrelationStore`).
The recorder consumes the seed JSON read out of these IPC fields.
- **Consumers**:
- OneAuth:
[`shared/mobile-onboarding-android-fixes`](https://office.visualstudio.com/OneAuth/_git/OneAuth)
updates `BrokerRequestConverter` / `BrokerResultConverter` to read/write
these fields.
- Broker (`ad-accounts-for-android`):
`MsalAndroidBrokerCommandParameterAdapter` reads `onboardingSeedJson`;
broker error handler / SSO controller will write `onboarding_blob` once
the recorder lifecycle is wired (separate PBI,
[AB#3568359](https://identitydivision.visualstudio.com/fac9d424-53d2-45c0-91b5-ef6ba7a6bf26/_workitems/edit/3568359)).
- **No breaking changes**: all new optional fields, no modifications to
existing serialization order or field semantics.

- Round-trip serialization is exercised by existing `BrokerRequest` /
`BrokerResult` tests (Gson + Bundle); new fields default to empty/null
when not set, so no existing test should regress.
- E2E validated locally via OneAuth `local-only-onboarding-telemetry`
branch + a combined Common build (`mavenLocal` `0.0.0-zhipan-mot-7`):
seed JSON flows OneAuth → BrokerRequest → broker → BrokerResult →
OneAuth.

Author: wzhipan

changelog.txt

@@ -3,6 +3,7 @@ vNext
 
 Version 24.2.1-RC1
 ----------
+- [MINOR] Add onboarding telemetry blob fields to BrokerRequest/BrokerResult and command parameters for client↔broker IPC transport (#3111)
 - [MINOR] Add onboarding telemetry recorder, field keys, and session persistence for mobile onboarding flow (#3088)
 
 Version 24.2.0

common/src/main/java/com/microsoft/identity/common/internal/broker/BrokerRequest.java

@@ -87,6 +87,7 @@ private static final class SerializedNames {
         final static String TENANT_ID = "tenant_id";
         final static String REQUEST_TYPE = "request_type";
         final static String WEB_APPS_STATE = "web_apps_state";
+        final static String ONBOARDING_SEED_JSON = "onboarding_seed_json";
     }
 
     /**
@@ -295,4 +296,17 @@ private static final class SerializedNames {
     @Nullable
     @SerializedName(SerializedNames.REQUEST_TYPE)
     private String mRequestType;
+
+    /**
+     * Onboarding telemetry seed JSON blob.
+     * Direction: client → broker (input only). Contains sessionCorrelationId,
+     * onboarding_mode, and schema_version, supplied by the client (OneAuth/MSAL)
+     * so the broker can construct an OnboardingTelemetryRecorder using the same
+     * correlation id. The broker returns the populated blob (with steps and
+     * blocking errors) via {@link BrokerResult#getOnboardingBlob()}, not via
+     * this field.
+     */
+    @Nullable
+    @SerializedName(SerializedNames.ONBOARDING_SEED_JSON)
+    private String mOnboardingSeedJson;
 }

common/src/main/java/com/microsoft/identity/common/internal/broker/BrokerResult.java

@@ -97,6 +97,7 @@ private static class SerializedNames {
         static final String SPE_RING = "spe_ring";
         static final String CLI_TELEM_ERRORCODE = "cli_telem_error_code";
         static final String CLI_TELEM_SUB_ERROR_CODE = "cli_telem_suberror_code";
+        static final String ONBOARDING_BLOB = "onboarding_blob";
     }
 
     private static final long serialVersionUID = 8606631820514878489L;
@@ -327,6 +328,13 @@ private static class SerializedNames {
     @SerializedName(SerializedNames.BROKER_AAD_DEVICE_ID_RECORD)
     private final AadDeviceIdRecord mAadDeviceIdRecord;
 
+    /**
+     * Populated onboarding telemetry blob JSON returned by the broker.
+     */
+    @Nullable
+    @SerializedName(SerializedNames.ONBOARDING_BLOB)
+    private final String mOnboardingBlob;
+
     private BrokerResult(@NonNull final Builder builder) {
         mAccessToken = builder.mAccessToken;
         mIdToken = builder.mIdToken;
@@ -362,6 +370,7 @@ private BrokerResult(@NonNull final Builder builder) {
         mCliTelemSubErrorCode = builder.mCliTelemSubErrorCode;
         mExceptionType = builder.mExceptionType;
         mAadDeviceIdRecord = builder.mAadDeviceIdRecord;
+        mOnboardingBlob = builder.mOnboardingBlob;
     }
 
     public String getExceptionType() {
@@ -498,6 +507,11 @@ public AadDeviceIdRecord getAadDeviceIdRecord() {
         return mAadDeviceIdRecord;
     }
 
+    @Nullable
+    public String getOnboardingBlob() {
+        return mOnboardingBlob;
+    }
+
     public static class Builder {
         private String mAccessToken;
         private String mIdToken;
@@ -523,6 +537,7 @@ public static class Builder {
         private List<ICacheRecord> mTenantProfileData;
         private boolean mServicedFromCache;
         private AadDeviceIdRecord mAadDeviceIdRecord;
+        private String mOnboardingBlob;
 
         // Exception parameters
         private String mErrorCode;
@@ -535,7 +550,6 @@ public static class Builder {
         private String mCliTelemErrorCode;
         private String mCliTelemSubErrorCode;
         private String mExceptionType;
-
         public Builder accessToken(@Nullable final String accessToken) {
             this.mAccessToken = accessToken;
             return this;
@@ -712,6 +726,11 @@ public Builder exceptionType(String exceptionType) {
             this.mExceptionType = exceptionType;
             return this;
         }
+
+        public Builder onboardingBlob(@Nullable final String onboardingBlob) {
+            this.mOnboardingBlob = onboardingBlob;
+            return this;
+        }
     }
 
 }

common/src/main/java/com/microsoft/identity/common/internal/request/MsalBrokerRequestAdapter.java

@@ -139,7 +139,8 @@ public BrokerRequest brokerRequestFromAcquireTokenParameters(@NonNull final Inte
                 .preferredBrowser(parameters.getPreferredBrowser())
                 .preferredAuthMethod(parameters.getPreferredAuthMethod())
                 .accountTransferToken(parameters.getAccountTransferToken())
-                .suppressAccountPicker(parameters.isSuppressBrokerAccountPicker());
+                .suppressAccountPicker(parameters.isSuppressBrokerAccountPicker())
+                .onboardingSeedJson(parameters.getOnboardingSeedJson());
 
         if (parameters instanceof AndroidInteractiveTokenCommandParameters) {
             final AndroidInteractiveTokenCommandParameters androidInteractiveTokenCommandParameters = (AndroidInteractiveTokenCommandParameters) parameters;

common/src/main/java/com/microsoft/identity/common/internal/result/MsalBrokerResultAdapter.java

@@ -465,9 +465,16 @@ public Bundle bundleFromBaseExceptionForWebApps(@NonNull final BaseException exc
     @NonNull
     @Override
     public ILocalAuthenticationResult authenticationResultFromBundle(@NonNull final Bundle resultBundle) throws ClientException {
-        final String methodTag = TAG + ":authenticationResultFromBundle";
-        final BrokerResult brokerResult = brokerResultFromBundle(resultBundle);
+        return authenticationResultFromBrokerResult(brokerResultFromBundle(resultBundle));
+    }
 
+    /**
+     * Overload that builds the authentication result from an already-deserialized
+     * {@link BrokerResult}. Use this when the caller has the [BrokerResult] in hand
+     * to avoid a redundant deserialization of the result bundle.
+     */
+    public ILocalAuthenticationResult authenticationResultFromBrokerResult(@NonNull final BrokerResult brokerResult) throws ClientException {
+        final String methodTag = TAG + ":authenticationResultFromBrokerResult";
         Logger.info(methodTag, "Broker Result returned from Bundle, constructing authentication result");
 
         final List<ICacheRecord> tenantProfileCacheRecords = brokerResult.getTenantProfileData();
@@ -565,6 +572,39 @@ public BrokerPerformanceMetrics getBrokerPerformanceMetricsFromBundle(@NonNull f
         }
     }
 
+    /**
+     * Extracts the onboarding telemetry blob (JSON string) from the result bundle.
+     * Best-effort: returns null if the bundle cannot be deserialized into a BrokerResult
+     * or if no blob is present. Telemetry failures must never fail an otherwise-successful
+     * auth result. Blob contents are not logged (may carry sessionCorrelationId).
+     *
+     * If the caller has already deserialized the [BrokerResult], prefer the overload
+     * [getOnboardingBlobFromBundle(BrokerResult)] to avoid a second deserialization.
+     */
+    @Nullable
+    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+    public String getOnboardingBlobFromBundle(@NonNull final Bundle resultBundle) {
+        final String methodTag = TAG + ":getOnboardingBlobFromBundle";
+        try {
+            final BrokerResult brokerResult = brokerResultFromBundle(resultBundle);
+            return brokerResult.getOnboardingBlob();
+        } catch (final ClientException e) {
+            Logger.warn(methodTag, "Failed to extract onboarding blob from broker result: " + e.getErrorCode());
+            return null;
+        }
+    }
+
+    /**
+     * Overload that reads the onboarding telemetry blob from a {@link BrokerResult}
+     * that has already been deserialized by the caller. Use this when you already
+     * have a [BrokerResult] in hand to avoid a second deserialization of the bundle.
+     */
+    @Nullable
+    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+    public String getOnboardingBlobFromBundle(@NonNull final BrokerResult brokerResult) {
+        return brokerResult.getOnboardingBlob();
+    }
+
     @NonNull
     @Override
     public AcquirePrtSsoTokenResult getAcquirePrtSsoTokenResultFromBundle(Bundle resultBundle) {
@@ -1017,9 +1057,14 @@ public AcquireTokenResult getDeviceCodeFlowTokenResultFromResultBundle(@NonNull
     AcquireTokenResult getAcquireTokenResultFromResultBundle(@NonNull final Bundle resultBundle) throws BaseException {
         final MsalBrokerResultAdapter resultAdapter = new MsalBrokerResultAdapter();
         if (resultBundle.getBoolean(AuthenticationConstants.Broker.BROKER_REQUEST_V2_SUCCESS)) {
+            // Deserialize BrokerResult once and reuse for both the local authentication result
+            // and the onboarding telemetry blob, instead of letting authenticationResultFromBundle
+            // and getOnboardingBlobFromBundle each pay the deserialization cost.
+            final BrokerResult brokerResult = resultAdapter.brokerResultFromBundle(resultBundle);
+
             final AcquireTokenResult acquireTokenResult = new AcquireTokenResult();
             acquireTokenResult.setLocalAuthenticationResult(
-                    resultAdapter.authenticationResultFromBundle(resultBundle)
+                    resultAdapter.authenticationResultFromBrokerResult(brokerResult)
             );
             // Set broker performance metrics if available
             final BrokerPerformanceMetrics metrics = resultAdapter.getBrokerPerformanceMetricsFromBundle(resultBundle);
@@ -1038,6 +1083,13 @@ AcquireTokenResult getAcquireTokenResultFromResultBundle(@NonNull final Bundle r
                         resultBundle.getString(AuthenticationConstants.Broker.BROKER_PACKAGE_NAME)
                 );
             }
+
+            // Set onboarding telemetry blob if present (best-effort; never fails the result).
+            final String onboardingBlob = resultAdapter.getOnboardingBlobFromBundle(brokerResult);
+            if (onboardingBlob != null) {
+                acquireTokenResult.setOnboardingBlob(onboardingBlob);
+            }
+
             return acquireTokenResult;
         }
 

common/src/test/java/com/microsoft/identity/common/internal/request/MsalBrokerRequestAdapterTests.java

@@ -386,4 +386,73 @@ public void testGetRequestBundleForAadDeviceIdRequest() {
         assertEquals(mockRedirectUri, brokerRequest.getRedirect());
         assertEquals(mockTenantId, brokerRequest.getTenantId());
     }
+
+    /**
+     * Verify that {@code onboardingSeedJson} from {@link InteractiveTokenCommandParameters}
+     * is propagated into {@link BrokerRequest} by
+     * {@link MsalBrokerRequestAdapter#brokerRequestFromAcquireTokenParameters(InteractiveTokenCommandParameters)}.
+     */
+    @Test
+    public void test_brokerRequestFromAcquireTokenParameters_PropagatesOnboardingSeedJson() {
+        final String seedJson = "{\"schema_version\":\"1.0.0\","
+                + "\"session_correlation_id\":\"abc-123\","
+                + "\"onboarding_mode\":\"brokered\"}";
+        final Set<String> scopes = new HashSet<>();
+        scopes.add("user.read");
+
+        final IPlatformComponents components = MockPlatformComponentsFactory.getNonFunctionalBuilder().build();
+        final AndroidInteractiveTokenCommandParameters params = AndroidInteractiveTokenCommandParameters.builder()
+                .platformComponents(components)
+                .correlationId("987d8962-3f4d-4054-a852-ac0c4b6a602e")
+                .clientId("aClientId")
+                .redirectUri("msauth://com.example/foo")
+                .applicationName("com.example")
+                .applicationVersion("1.0.0")
+                .sdkType(SdkType.MSAL)
+                .sdkVersion("5.4.0")
+                .authority(new AzureActiveDirectoryAuthority())
+                .scopes(scopes)
+                .authenticationScheme(new BearerAuthenticationSchemeInternal())
+                .prompt(OpenIdConnectPromptParameter.LOGIN)
+                .requiredBrokerProtocolVersion("10.0")
+                .onboardingSeedJson(seedJson)
+                .build();
+
+        final BrokerRequest brokerRequest =
+                new MsalBrokerRequestAdapter().brokerRequestFromAcquireTokenParameters(params);
+
+        assertEquals(seedJson, brokerRequest.getOnboardingSeedJson());
+    }
+
+    /**
+     * Verify that when {@code onboardingSeedJson} is not set on the parameters,
+     * the resulting {@link BrokerRequest} carries a null seed (i.e. no accidental default value).
+     */
+    @Test
+    public void test_brokerRequestFromAcquireTokenParameters_NoSeedJson_IsNull() {
+        final Set<String> scopes = new HashSet<>();
+        scopes.add("user.read");
+
+        final IPlatformComponents components = MockPlatformComponentsFactory.getNonFunctionalBuilder().build();
+        final AndroidInteractiveTokenCommandParameters params = AndroidInteractiveTokenCommandParameters.builder()
+                .platformComponents(components)
+                .correlationId("987d8962-3f4d-4054-a852-ac0c4b6a602e")
+                .clientId("aClientId")
+                .redirectUri("msauth://com.example/foo")
+                .applicationName("com.example")
+                .applicationVersion("1.0.0")
+                .sdkType(SdkType.MSAL)
+                .sdkVersion("5.4.0")
+                .authority(new AzureActiveDirectoryAuthority())
+                .scopes(scopes)
+                .authenticationScheme(new BearerAuthenticationSchemeInternal())
+                .prompt(OpenIdConnectPromptParameter.LOGIN)
+                .requiredBrokerProtocolVersion("10.0")
+                .build();
+
+        final BrokerRequest brokerRequest =
+                new MsalBrokerRequestAdapter().brokerRequestFromAcquireTokenParameters(params);
+
+        assertNull(brokerRequest.getOnboardingSeedJson());
+    }
 }

common/src/test/java/com/microsoft/identity/common/internal/request/MsalBrokerResultAdapterTests.kt

@@ -658,4 +658,34 @@ class MsalBrokerResultAdapterTests {
             resultString.contains(SchemaUtil.MISSING_FROM_THE_TOKEN_RESPONSE)
         )
     }
+
+    @Test
+    fun testOnboardingBlob_RoundTripsThroughBundle() {
+        val blobJson = """{"schema_version":"1.0.0","session_correlation_id":"abc-123","onboarding_mode":"brokered","blocking_errors":["BROKER_INSTALLATION_TRIGGERED"]}"""
+        val brokerResult = BrokerResult.Builder()
+            .clientId("aClientId")
+            .correlationId("987d8962-3f4d-4054-a852-ac0c4b6a602e")
+            .onboardingBlob(blobJson)
+            .build()
+
+        val adapter = getInstance()
+        val resultBundle = adapter.bundleFromBrokerResult(brokerResult, "10.0")
+        val deserialized = adapter.brokerResultFromBundle(resultBundle)
+
+        assertEquals(blobJson, deserialized.onboardingBlob)
+    }
+
+    @Test
+    fun testOnboardingBlob_NotSet_DeserializesAsNull() {
+        val brokerResult = BrokerResult.Builder()
+            .clientId("aClientId")
+            .correlationId("987d8962-3f4d-4054-a852-ac0c4b6a602e")
+            .build()
+
+        val adapter = getInstance()
+        val resultBundle = adapter.bundleFromBrokerResult(brokerResult, "10.0")
+        val deserialized = adapter.brokerResultFromBundle(resultBundle)
+
+        assertNull(deserialized.onboardingBlob)
+    }
 }

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

@@ -38,6 +38,8 @@
 import lombok.Getter;
 import lombok.experimental.SuperBuilder;
 
+import edu.umd.cs.findbugs.annotations.Nullable;
+
 @Getter
 @EqualsAndHashCode(callSuper = true)
 @SuperBuilder(toBuilder = true)
@@ -85,6 +87,13 @@ public class InteractiveTokenCommandParameters extends TokenCommandParameters {
      */
     private final boolean suppressBrokerAccountPicker;
 
+    /**
+     * Onboarding telemetry seed JSON blob.
+     * Passed through IPC to the broker for step recording and blocking error tracking.
+     */
+    @Nullable
+    private final String onboardingSeedJson;
+
     public boolean getHandleNullTaskAffinity(){
         return handleNullTaskAffinity;
     }

common4j/src/main/com/microsoft/identity/common/java/result/AcquireTokenResult.java

@@ -49,6 +49,21 @@ public class AcquireTokenResult implements IBrokerPerformanceMetricsProvider, IB
 
     private BrokerPerformanceMetrics mBrokerPerformanceMetrics;
 
+    /**
+     * Populated onboarding telemetry blob JSON returned by the broker.
+     */
+    @Nullable
+    private String mOnboardingBlob;
+
+    public void setOnboardingBlob(@Nullable final String onboardingBlob) {
+        this.mOnboardingBlob = onboardingBlob;
+    }
+
+    @Nullable
+    public String getOnboardingBlob() {
+        return this.mOnboardingBlob;
+    }
+
     public void setLocalAuthenticationResult(ILocalAuthenticationResult result) {
         this.mLocalAuthenticationResult = result;
         this.mSucceeded = true;