MAM onboarding Phase 1: install-referrer redirect to the calling app (flight-gated), Fixes AB#3676213

[wzhipan]

Summary

Phase 1 of "Improve MAM onboarding on Android" (PBI AB#3686094, Feature AB#3676213).

When an interactive request is interrupted by a Conditional-Access "install Company Portal" response, tag the Play Store install link with the calling app's package as the Play install referrer. Company Portal reads it and, after install, sends the user back to the app they started in instead of stranding them in Company Portal.

Redirect-only. No park / auto-resume — that is Phase 2.

What changed

Everything is in Common and gated on CommonFlight.ENABLE_MAM_CA_INSTALL_REFERRER (default off).

common4j

• New MamCaRedirect — the single place that decides whether a broker-install redirect is the MAM-CA variety. Looks for the intuneAppProtection marker on the redirect, exposes getUsername(), and provides a PII-safe logRedirectParameterNames() — names only, never values, and only names that are actually shaped like parameter names (the query parser turns a trailing token with no = into a key, so a malformed redirect could otherwise put a UPN on the log).
• New MamInstallReferrerBuilder — two entry points:
  • decorateAppLinkForMamCaInstall(appLink, originPkg, redirectParameters) — flight-gated and scoped to MAM-CA redirects only, so a plain WPJ/device-registration install is untouched.
  • decorateAppLinkWithOriginReferrer(appLink, originPkg) — the ungated primitive.
    Allowlist-preserving, null-safe, idempotent (exactly one referrer param); on any parse problem it returns the original link so the existing install flow can never be broken.
• A referrer already on the link wins. The server derives the referrer from the package hosting the sign-in UI, which is the calling app in the no-broker case this targets but is the broker when one is installed and hosting the flow. Where the two disagree the server is right, so this is a fallback for links that arrive without a referrer, not an override.
• Flight: ENABLE_MAM_CA_INSTALL_REFERRER.

common

• The redirect's query parameters are now threaded to the point where the install link is launched (AuthorizationFragment, both browser fragments, and AzureActiveDirectoryWebViewClient#processInstallRequest), which is what lets the decoration be scoped to MAM-CA. originPkg is still sourced locally from the Android context — no cross-repo plumbing.

With the flight off the link is launched exactly as before.

Design alignment

Reworked to match the current phased design doc:

• Decoration is gated on the MAM-CA marker rather than applied to every broker-install redirect.
• Flight renamed ENABLE_BROKER_INSTALL_RESUME → ENABLE_MAM_CA_INSTALL_REFERRER. Safe: default-off, never merged, no ECS entry.
• Phase-2 surface removed from this PR.

Server contract

The gate is the intuneAppProtection=1 marker the server puts on the broker-install redirect (ESTS-Main PR 16454630, server-side flighted, not yet merged). Shape:

https://<redirect_uri>?wpj=1&username=<upn>&app_link=<encoded Play link>&intuneAppProtection=1

It is a top-level parameter on the redirect, appended after app_link — not nested inside the app_link value — so StringExtensions.getUrlParameters(url) already surfaces it. Only intuneAppProtection=1 counts; anything else is treated as an ordinary broker install and left alone.

Both sides are default-off, so the order they ramp in doesn't matter: until the server marker is live the client is a no-op, and until the client flight is on the marker is simply ignored.

Testing

• MamInstallReferrerBuilderTest — 15 tests, 0 failures.
• MamCaRedirectTest — 7 tests, 0 failures.
• Regression sweep across providers / flighting / controllers / commands — 242 tests, 0 failures.
• :common:compileLocalDebugJavaWithJavac — BUILD SUCCESSFUL.
• End-to-end on a physical device (OneAuthTestApp, MAM-CA account, no broker installed): sign-in → CA "install Company Portal" interstitial → "Get the app" → genuine Play Store install → Company Portal relaunched the calling app.
  • MamInstallReferrerBuilder:decorateAppLinkForMamCaInstall: Tagged the Company Portal install launch with the calling app as the install referrer.
  • Finsky: Capture referrer for com.microsoft.windowsintune.companyportal
  • START … cmp=…/OneAuthTestActivity from uid … (com.microsoft.windowsintune.companyportal)
  • The server marker was simulated client-side for this run, since the server side has not shipped yet.

Note for reviewers

MamCaRedirect.kt is added identically by #3195, and the two copies are kept byte-identical on purpose so the PRs can merge in either order. Whichever merges second will conflict in two purely additive spots — CommonFlight (adjacent enum constants) and AzureActiveDirectoryWebViewClient (imports + processInstallRequest). Both resolve by keeping both sides. Verified with git merge-tree: MamCaRedirect.kt itself is not in the conflict set.

All new files here are Kotlin, with @JvmStatic on everything the existing Java call sites use.

Rollout

Redirect-back also needs the Company Portal read-side (separate CP feature). Until that lands this is a flight-gated no-op and safe to merge.

Work item

PBI AB#3686094 · Feature AB#3676213

[github-actions]

✅ Work item link check complete. Description contains link AB#3676213 to an Azure Boards work item.

[github-actions]

❌ Invalid work item number: AB#3676213):. Work item number must be a valid integer.

Click here to learn more.

[github-actions]

✅ Work item link check complete. Description contains link AB#3686094 to an Azure Boards work item.

[Copilot]

Pull request overview

This PR introduces Phase 1 of improved MAM onboarding by (flight-gated) tagging the Company Portal Play Store install link with the calling app’s package as the Play install referrer, enabling Company Portal to redirect the user back to the originating app after install.

Changes:

• Added MamInstallReferrerBuilder (and unit tests) to decorate Play Store install links with a CP-compatible referrer=<originPkg> form behind CommonFlight.ENABLE_BROKER_INSTALL_RESUME.
• Added the ENABLE_BROKER_INSTALL_RESUME flight constant to CommonFlight.
• Wired the decoration into broker-install launches across the browser fragments and embedded WebView flow.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
common4j/src/main/com/microsoft/identity/common/java/providers/MamInstallReferrerBuilder.java	Adds referrer-building and flight-gated decoration helpers for Company Portal redirect-back.
common4j/src/test/com/microsoft/identity/common/java/providers/MamInstallReferrerBuilderTest.java	Adds unit coverage for decoration/idempotency/allowlist/round-trip parsing behavior.
common4j/src/main/com/microsoft/identity/common/java/flighting/CommonFlight.java	Introduces the ENABLE_BROKER_INSTALL_RESUME flight toggle.
common/src/main/java/com/microsoft/identity/common/internal/ui/webview/AzureActiveDirectoryWebViewClient.java	Decorates the broker install link launched from the embedded WebView flow.
common/src/main/java/com/microsoft/identity/common/internal/providers/oauth2/AuthorizationFragment.java	Centralizes install-link decoration for AuthorizationFragment subclasses.
common/src/main/java/com/microsoft/identity/common/internal/providers/oauth2/BrowserAuthorizationFragment.java	Uses the shared decoration helper before launching the broker install link.
common/src/main/java/com/microsoft/identity/common/internal/providers/oauth2/CurrentTaskBrowserAuthorizationFragment.java	Uses the shared decoration helper before launching the broker install link.

[Praveen Kumar (Prvnkmr337)]

A few review comments — thanks for the clean phased scoping and the marker-based gating.

[Praveen Kumar (Prvnkmr337)]

Follow-up on the latest changes.

[Praveen Kumar (Prvnkmr337)]

Should this emit a metric while the flight is on?

The only observability in this PR is Logger.info lines — no span attributes or events. Once we ramp the flight we won't be able to answer basic rollout questions from Kusto:

• Is the server actually marking redirects with intuneAppProtection=1 yet?
• Of marked redirects, how many got decorated vs. bailed out (missing originPkg, server already set a referrer, parse failure)?

processInstallRequest already calls recordOnboardingStep(STEP_BROKER_INSTALL_PROMPTED), so the plumbing is right there. A single attribute on that span (e.g. is_mam_ca_install_referrer_decorated, plus an outcome enum) would give us the ramp-safety signal.

Add one attribute in this PR, or defer to a follow-up that lands before we ramp past 0%?

[wzhipan]

Good call - done in 810bf9c rather than deferred, because it turned out to need no schema change.

OnboardingTelemetryRecorder.addUxFlowUsed(...) already exists for exactly this ("a phased rollout cohort like MobileOnboardingPhase1", per its KDoc) and had no production callers yet. Reusing it means the data lands in the onboarding blob that is already emitted, surfacing as mo_ux_flow_used.

MamInstallReferrerBuilder now returns an outcome alongside the link, and the WebView client reports it:

outcome	meaning
FLIGHT_OFF	not reported at all
MamCaInstallReferrer_NotMamCa	broker install, but no intuneAppProtection=1 marker
MamCaInstallReferrer_NoOriginPackage	marked, but we could not determine the calling package
MamCaInstallReferrer_NoAppLink	marked, but no app_link to decorate
MamCaInstallReferrer_ServerReferrer	the server already named a referrer, so we left it alone
MamCaInstallReferrer_LinkUnparseable	app_link failed to parse
MamCaInstallReferrer_Decorated	we added the referrer

That answers both ramp questions directly: Decorated vs ServerReferrer shows how much of the population the client-side fallback is actually carrying, and NotMamCa vs the rest shows how often the marker is arriving at all - which matters while the eSTS side is still ramping.

Two things worth flagging:

FLIGHT_OFF reports nothing, deliberately. finalizeBlob() omits ux_flow_used entirely when the list is empty, so with the flight off the feature still leaves zero trace - consistent with what we agreed earlier about logging, now extended to telemetry. There is a test that fails if that ever changes.

Only the embedded-WebView path has a recorder. AuthorizationFragment.decorateInstallLinkWithReferrer, used by the two browser fragments, has no OnboardingTelemetryRecorder attached, so those paths stay log-only. Acceptable for now because MAM-CA onboarding runs through the WebView (that is where STEP_BROKER_INSTALL_PROMPTED is recorded too), but it is a genuine gap rather than full coverage, so calling it out.

One behavioural note: the marker check now runs before the origin-package check. Both branches return the link unchanged, so this is reporting-only - it stops a missing package from being misreported as "not MAM-CA".

[Praveen Kumar (Prvnkmr337)]

Clarification on Outcome / Decoration after ce46c615

All three production call sites use the non-WithOutcome overload and drop the outcome; only tests read it. Three quick questions:

1. Is decorateAppLinkForMamCaInstallWithOutcome intended to have a production consumer later, or stay test-only?
2. Four of seven outcomes (FLIGHT_OFF, NOT_MAM_CA, NO_ORIGIN_PKG, NO_APP_LINK) emit no log, and the three that do don't carry the enum value. Intentional, or worth one uniform Logger.info per branch?
3. Are these outcomes expected to surface as OneAuth metrics (via the OneAuth telemetry pipeline consuming common's signals)?

[wzhipan]

1. Test-only, by design. Six of the seven outcomes return the app_link unchanged, so without the overload the flight gate, the MAM-CA gate and the server-referrer branch are indistinguishable in tests. No production consumer planned for Phase 1.

2. Partly intentional. FLIGHT_OFF is deliberate and documented on the enum: with the flight off this feature should be indistinguishable from its absence, log lines included. The other three had no such reason — each now logs, and the three that already logged carry the outcome value too. Added a test that reads the expected value off the enum, so the log and the enum cannot drift.

3. Not from these PRs. Mobile-onboarding telemetry is being handled as a separate follow-up project, and MAM-CA onboarding will be wired there. It is also not a small add here: at the OneAuth boundary a MAM-CA install currently arrives as plain BROKER_INSTALLATION_TRIGGERED, indistinguishable from a regular broker install, so it needs a common-side change first.

[Praveen Kumar (Prvnkmr337)]

LGTM

[wzhipan]

Pushed one more scoping change (18a19849b) after re-auditing how we decide to tag the install link.

The gap. The intuneAppProtection=1 marker tells us the redirect is a MAM-CA install, but not which app it installs. app_link is allowed to name any of the three destinations BrokerInstallLinkValidator permits, and only one of them can act on a Play install referrer:

app_link	before
Company Portal Play listing	tagged — intended
Authenticator Play listing	tagged — Authenticator honours no referrer contract
China CP go.microsoft.com fwlink	tagged — not a Play link, so the referrer is never delivered

Appending an inert parameter is harmless in itself, but rollout is read off these log lines, so both cases would have been reported as DECORATED and overstated how far the feature had actually reached. The China link is the likelier of the two.

The change. Decoration is now constrained to the Company Portal Play listing; anything else reports a new NOT_COMPANY_PORTAL outcome, keeping "skipped, wrong install target" separable from "tagged". Only the package id is matched — the allowlist upstream has already constrained the host, unflighted, on the path that produces BROKER_INSTALLATION_TRIGGERED. The check sits inside the existing parse rather than ahead of it, so an unparseable link is still reported as LINK_UNPARSEABLE rather than mislabelled.

MDM/device registration is unaffected — those share this redirect and are still identified solely by the absence of the marker, which this does not touch.

3 tests added, plus the new outcome wired into outcome_everyEvaluatedOutcomeNamesItselfInTheLog. Negative-tested both ways: removing the guard fails exactly the 3 tests that cover it; moving it ahead of the parse fails exactly the 3 that depend on LINK_UNPARSEABLE. MamInstallReferrerBuilder 23/0, MamCaRedirect 7/0, AzureActiveDirectoryWebViewClientTest 87/0, AuthorizationFragmentInstallReferrerTest 6/0.

Praveen Kumar (@Prvnkmr337) sorry — this invalidates your approval from earlier, would you mind taking another look?

[wzhipan]

Correction to my previous comment — that scoping change is reverted (1ac98e603). Please disregard it.

Confirmed with Veena: the server sets intuneAppProtection=1 only on MAM-CA flows, and the referrer should always be appended once the marker is present and the flight is on. Both premises I gated on were wrong:

• the marker does establish the flow on its own, so there was nothing left to narrow;
• the China go.microsoft.com/fwlink/?linkid=2134649 target is not a different app — it is Company Portal by another distribution channel, and BrokerInstallLinkValidator's own docs note the server may already set a referrer on it. So my "a referrer there is inert" claim was speculation, and contradicted.

The gate didn't tighten anything; it would have dropped the referrer on real MAM-CA installs in China.

Net effect against the state you last reviewed is a comment and a test — production behaviour is byte-for-byte identical to 2e996cee2. I kept a note on the class KDoc and gated_markedInstall_isDecoratedWhateverTheInstallTargetIs, which asserts all three allowed destinations are tagged, since re-adding this gate looks like a safe tightening and isn't. Re-introducing it fails that test and nothing else.

MamInstallReferrerBuilder 21/0, MamCaRedirect 7/0, AzureActiveDirectoryWebViewClientTest 87/0, AuthorizationFragmentInstallReferrerTest 6/0.

Praveen Kumar (@Prvnkmr337) apologies for the churn — your approval was never dismissed and still stands, so no action needed from you.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

common4j/src/main/com/microsoft/identity/common/java/providers/MamInstallReferrerBuilder.kt:264

• The success log message is overly specific to “Company Portal”, but the implementation explicitly decorates any install target on a marked redirect (including non-CP targets like Authenticator / fwlinks, per tests). Recommend making this message target-agnostic (e.g., “Tagged the broker-install launch…” or “Tagged the install link…”) to avoid misleading field diagnostics.

                Logger.info(
                    methodTag,
                    "Tagged the Company Portal install launch with the calling app as the install " +
                        "referrer. [outcome=${Outcome.DECORATED}]"
                )

common4j/src/main/com/microsoft/identity/common/java/providers/MamInstallReferrerBuilder.kt:231

• decorateWithOutcome(...) always uses the decorateAppLinkWithOriginReferrer method tag even when invoked from the gated MAM-CA entry point. This makes log correlation harder because some outcomes for the MAM-CA path will appear under a different method tag than others. Consider passing the caller’s method tag into decorateWithOutcome (or computing the tag at the call site) so logs consistently identify the entry point being evaluated.

    private fun decorateWithOutcome(appLink: String?, originPkg: String): Decoration {
        val methodTag = "$TAG:decorateAppLinkWithOriginReferrer"

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (1)

common/src/main/java/com/microsoft/identity/common/internal/providers/oauth2/AuthorizationFragment.java:242

• The new helper is intentionally null-tolerant (tests pass null appLink / redirectParameters and expect a null / unchanged result), and it delegates to a Kotlin API that returns a nullable String. Without @Nullable annotations here, Java/Kotlin callers lose the actual contract and static analysis can miss real null flows.

Recommendation: annotate the return value and both parameters as @Nullable to reflect the true behavior and improve interop.

    protected String decorateInstallLinkWithReferrer(final String appLink,
                                                     final Map<String, String> redirectParameters) {
        final Context context = getContext();
        return MamInstallReferrerBuilder.decorateAppLinkForMamCaInstall(
                appLink, context == null ? null : context.getPackageName(), redirectParameters);