msauth: surface the authentication flow on the result

Two consumer needs the current result shape can't answer:

  - "Did MSAL prompt the user to acquire this token?" Useful for
    diagnostics, telemetry, and consumer policy: silent paths can
    be retried more aggressively, interactive paths cost the user
    real time.
  - "Which technique did MSAL use?" Same audiences plus the
    ability to distinguish broker-cached from MSAL-cached tokens
    (different revocation and tenant-switch behaviour), or to
    detect device-code use (often a fallback rather than the
    user's first preference).

Add a public `MicrosoftAuthenticationFlow` enum and a `Flow`
property on `IMicrosoftAuthenticationResult` so consumers can read
both signals. No consumer reads `Flow` today — surfacing it now is
preparation for picker policy, future telemetry, and trace
diagnostics that already had no good way to learn this without
re-deriving it from log scraping.

The enum collapses non-interactive paths into named buckets
(`ServicePrincipal`, `ManagedIdentity`, `WorkloadFederation`,
`Silent`, `BrokerSilent`) rather than a single `NonInteractive`
value: the distinction is cheap to populate and the names carry
useful diagnostic information for free. `Silent` vs `BrokerSilent`
is determined at the silent return site by inspecting MSAL's own
`AuthenticationResultMetadata.TokenSource` — tokens returned by
the broker carry `TokenSource.Broker`, everything else (MSAL's
own cache, or a refresh against the identity provider) does not.

The interactive bucket splits the same way the existing private
`InteractiveFlowType` enum already does: `BrokerInteractive`,
`EmbeddedWebView`, `SystemWebView`, `DeviceCode`. `BrokerInteractive`
(rather than just `Broker`) is named symmetrically with
`BrokerSilent` so a reader looking at one finds the other.

"Interactive" is exposed as an `IsInteractive()` extension method
on the enum, not as a property on the result. This keeps the
result interface minimal and works for callers that have a flow
value from elsewhere (e.g. an enum field on a stored request).
The OS-account-default flow does silent token acquisition
followed by a GCM-side "continue with current account?"
confirmation prompt — the token itself was acquired silently, so
the flow is `Silent` or `BrokerSilent`; the confirmation prompt
is GCM chrome that isn't reflected here.

Workload federation reports itself as `WorkloadFederation` even
though `GetTokenUsingWorkloadFederationAsync` internally calls
`GetTokenForManagedIdentityAsync`: the intermediate MI result is
private to the WIF path, and the surfaced result describes the
outer top-level call.

`MsalResult`'s constructor grows an optional
`MicrosoftAuthenticationFlow` parameter that defaults to `Unknown`.
Every in-tree call site supplies a real value, so the default is
purely an escape hatch for callers that don't classify (test
fakes that build a result without going through
`MicrosoftAuthentication`, or future call sites that want to
construct a result before the flow is decided).

The test fake `AzureReposHostProviderTests.MockMsAuthResult`
grows the property to satisfy the interface; nothing reads it.

Assisted-by: Claude Opus 4.7
Signed-off-by: Matthew John Cheetham <mjcheetham@outlook.com>

Author: mjcheetham

src/shared/Core/Authentication/MicrosoftAuthentication.cs

@@ -102,6 +102,64 @@ public interface IMicrosoftAuthenticationResult
     {
         string AccessToken { get; }
         IMicrosoftAccount Account { get; }
+
+        /// <summary>
+        /// How this token was acquired. Use <see cref="MicrosoftAuthenticationFlowExtensions.IsInteractive"/>
+        /// to fold this down to "did MSAL show the user UI".
+        /// </summary>
+        MicrosoftAuthenticationFlow Flow { get; }
+    }
+
+    /// <summary>
+    /// Identifies how a Microsoft authentication result was produced.
+    /// </summary>
+    public enum MicrosoftAuthenticationFlow
+    {
+        /// <summary>The flow was not classified by the implementation.</summary>
+        Unknown = 0,
+
+        /// <summary>Service principal client credentials grant.</summary>
+        ServicePrincipal,
+
+        /// <summary>Azure managed identity (system or user-assigned).</summary>
+        ManagedIdentity,
+
+        /// <summary>Workload federation (federated identity credentials).</summary>
+        WorkloadFederation,
+
+        /// <summary>User-flow token returned silently from MSAL's own cache.</summary>
+        Silent,
+
+        /// <summary>User-flow token returned silently from the OS broker.</summary>
+        BrokerSilent,
+
+        /// <summary>User-flow token acquired via interactive UI in the OS broker.</summary>
+        BrokerInteractive,
+
+        /// <summary>User-flow token acquired via an interactive embedded WebView (.NET Framework only).</summary>
+        EmbeddedWebView,
+
+        /// <summary>User-flow token acquired via the system default browser.</summary>
+        SystemWebView,
+
+        /// <summary>User-flow token acquired via the device code flow.</summary>
+        DeviceCode,
+    }
+
+    public static class MicrosoftAuthenticationFlowExtensions
+    {
+        /// <summary>
+        /// True when the flow showed UI to the user during token acquisition. The OS-account-default
+        /// confirmation prompt is GCM chrome around silent acquisition and is not reflected here.
+        /// </summary>
+        public static bool IsInteractive(this MicrosoftAuthenticationFlow flow) => flow switch
+        {
+            MicrosoftAuthenticationFlow.BrokerInteractive => true,
+            MicrosoftAuthenticationFlow.EmbeddedWebView   => true,
+            MicrosoftAuthenticationFlow.SystemWebView     => true,
+            MicrosoftAuthenticationFlow.DeviceCode        => true,
+            _ => false,
+        };
     }
 
     public interface IMicrosoftAccount : IEquatable<IMicrosoftAccount>
@@ -297,6 +355,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                 IPublicClientApplication app = await CreatePublicClientApplicationAsync(authority, clientId, redirectUri, useBroker, msaPt, uiCts);
 
                 AuthenticationResult result = null;
+                MicrosoftAuthenticationFlow flow = MicrosoftAuthenticationFlow.Unknown;
 
                 // Resolve the account against the MSAL cache once (HomeAccountId-first, UPN-fallback,
                 // with trace warnings on mismatch/ambiguity).
@@ -316,6 +375,14 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                 if (hasExistingUser)
                 {
                     result = await GetAccessTokenSilentlyAsync(app, scopes, resolvedAccount, msaPt);
+                    if (result is not null)
+                    {
+                        // Tokens returned by the OS broker carry TokenSource.Broker; anything else
+                        // (MSAL's own cache, or a refresh against the identity provider) doesn't.
+                        flow = result.AuthenticationResultMetadata?.TokenSource == TokenSource.Broker
+                            ? MicrosoftAuthenticationFlow.BrokerSilent
+                            : MicrosoftAuthenticationFlow.Silent;
+                    }
                 }
 
                 //
@@ -359,6 +426,12 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                             {
                                 result = null;
                             }
+                            else
+                            {
+                                // This branch is broker-only by construction; a non-null result here
+                                // can only have come from the broker's cache.
+                                flow = MicrosoftAuthenticationFlow.BrokerSilent;
+                            }
                         }
 
                         if (result is null)
@@ -369,6 +442,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                                 // We must configure the system webview as a fallback
                                 .WithSystemWebViewOptions(GetSystemWebViewOptions())
                                 .ExecuteAsync();
+                            flow = MicrosoftAuthenticationFlow.BrokerInteractive;
                         }
                     }
                     else
@@ -395,6 +469,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                                     .WithUseEmbeddedWebView(true)
                                     .WithEmbeddedWebViewOptions(GetEmbeddedWebViewOptions())
                                     .ExecuteAsync();
+                                flow = MicrosoftAuthenticationFlow.EmbeddedWebView;
                                 break;
 
                             case InteractiveFlowType.SystemWebView:
@@ -404,6 +479,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                                     .WithPrompt(Prompt.SelectAccount)
                                     .WithSystemWebViewOptions(GetSystemWebViewOptions())
                                     .ExecuteAsync();
+                                flow = MicrosoftAuthenticationFlow.SystemWebView;
                                 break;
 
                             case InteractiveFlowType.DeviceCode:
@@ -412,6 +488,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                                 // TODO: introduce a small GUI window to show a code if no TTY exists
                                 ThrowIfTerminalPromptsDisabled();
                                 result = await app.AcquireTokenWithDeviceCode(scopes, ShowDeviceCodeInTty).ExecuteAsync();
+                                flow = MicrosoftAuthenticationFlow.DeviceCode;
                                 break;
 
                             default:
@@ -420,7 +497,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForUserAsync(
                     }
                 }
 
-                return new MsalResult(result);
+                return new MsalResult(result, flow);
             }
             finally
             {
@@ -438,7 +515,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForServicePrincipalAsy
                 Context.Trace.WriteLine($"Sending with X5C: '{sp.SendX5C}'.");
                 AuthenticationResult result = await app.AcquireTokenForClient(scopes).WithSendX5C(sp.SendX5C).ExecuteAsync();;
 
-                return new MsalResult(result);
+                return new MsalResult(result, MicrosoftAuthenticationFlow.ServicePrincipal);
             }
             catch (Exception ex)
             {
@@ -462,7 +539,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenForManagedIdentityAsyn
             try
             {
                 AuthenticationResult result = await app.AcquireTokenForManagedIdentity(resource).ExecuteAsync();
-                return new MsalResult(result);
+                return new MsalResult(result, MicrosoftAuthenticationFlow.ManagedIdentity);
             }
             catch (Exception ex)
             {
@@ -482,7 +559,7 @@ public async Task<IMicrosoftAuthenticationResult> GetTokenUsingWorkloadFederatio
               .ExecuteAsync()
               .ConfigureAwait(false);
 
-            return new MsalResult(result);
+            return new MsalResult(result, MicrosoftAuthenticationFlow.WorkloadFederation);
         }
 
         private async Task<string> GetClientAssertion(MicrosoftWorkloadFederationOptions fedOpts, AssertionRequestOptions _)
@@ -1173,14 +1250,16 @@ internal enum InteractiveFlowType
 
         private class MsalResult : IMicrosoftAuthenticationResult
         {
-            public MsalResult(AuthenticationResult msalResult)
+            public MsalResult(AuthenticationResult msalResult, MicrosoftAuthenticationFlow flow = MicrosoftAuthenticationFlow.Unknown)
             {
                 AccessToken = msalResult.AccessToken;
                 Account = MicrosoftAccount.FromMsalAccount(msalResult.Account);
+                Flow = flow;
             }
 
             public string AccessToken { get; }
             public IMicrosoftAccount Account { get; }
+            public MicrosoftAuthenticationFlow Flow { get; }
         }
     }
 }

src/shared/Microsoft.AzureRepos.Tests/AzureReposHostProviderTests.cs

@@ -1088,6 +1088,7 @@ private class MockMsAuthResult : IMicrosoftAuthenticationResult
         {
             public string AccessToken { get; set; }
             public IMicrosoftAccount Account { get; set; }
+            public MicrosoftAuthenticationFlow Flow { get; set; }
         }
     }
 }