Surface token-acquisition failure metadata on MsalException

neha-bhargava · Copilot · neha-bhargava · commit 0289ce280951 · 2026-06-30T20:45:56.000-07:00
Adds a public AuthenticationResultMetadata property (getter public, setter
internal) to the base MsalException and populates it in RequestBase.RunAsync
for any in-request failure. Callers now get diagnostic metadata for failed
token attempts — total duration (always captured, useful for latency), plus
HTTP/cache durations, token endpoint, and region used when available —
mirroring the success-path AuthenticationResult.AuthenticationResultMetadata.

Only data actually captured is populated; RegionDetails is set only when a
region was used. TokenSource has no meaningful value on failure (documented).
The property is intentionally not part of the exception's JSON serialization.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/src/client/Microsoft.Identity.Client/Internal/Requests/RequestBase.cs b/src/client/Microsoft.Identity.Client/Internal/Requests/RequestBase.cs
@@ -14,6 +14,7 @@
 using Microsoft.Identity.Client.Cache.Items;
 using Microsoft.Identity.Client.Core;
 using Microsoft.Identity.Client.Instance.Discovery;
+using Microsoft.Identity.Client.Region;
 using Microsoft.Identity.Client.OAuth2;
 using Microsoft.Identity.Client.TelemetryCore.Internal.Events;
 using Microsoft.Identity.Client.Utils;
@@ -114,7 +115,15 @@ public async Task<AuthenticationResult> RunAsync(CancellationToken cancellationT
                 }
                 AuthenticationRequestParameters.RequestContext.Logger.ErrorPii(ex);
 
-                int httpStatusCode = ex is MsalServiceException serviceEx ? serviceEx.StatusCode : 0;
+                if (ex.AuthenticationResultMetadata == null)
+                {
+                    ex.AuthenticationResultMetadata = CreateFailureMetadata(
+                        apiEvent,
+                        requestStopwatch.ElapsedMilliseconds + measureTelemetryDurationResult.Milliseconds);
+                }
+
+                MsalServiceException serviceException = ex as MsalServiceException;
+                int httpStatusCode = serviceException?.StatusCode ?? 0;
 
                 LogFailureTelemetryToOtel(
                     ex.ErrorCode,
@@ -123,7 +132,7 @@ public async Task<AuthenticationResult> RunAsync(CancellationToken cancellationT
                     httpStatusCode,
                     requestStopwatch.ElapsedMilliseconds + measureTelemetryDurationResult.Milliseconds,
                     exception: ex,
-                    rawStsErrorCode: (ex as MsalServiceException)?.ErrorCodes?.FirstOrDefault());
+                    rawStsErrorCode: serviceException?.ErrorCodes?.FirstOrDefault());
                 throw;
             }
             catch (Exception ex)
@@ -277,6 +286,26 @@ private void UpdateTelemetry(long elapsedMilliseconds, ApiEvent apiEvent, Authen
             Metrics.IncrementTotalDurationInMs(authenticationResult.AuthenticationResultMetadata.DurationTotalInMs);
         }
 
+        /// <summary>
+        /// Builds the subset of <see cref="AuthenticationResultMetadata"/> that is available when a
+        /// token request fails. Only values that were actually captured are populated; everything else
+        /// is left at its default (0 / null). <see cref="AuthenticationResultMetadata.TokenSource"/> has
+        /// no meaningful value on failure, so it stays at the constructor default and should not be relied on.
+        /// </summary>
+        private static AuthenticationResultMetadata CreateFailureMetadata(ApiEvent apiEvent, long totalDurationInMs)
+        {
+            return new AuthenticationResultMetadata(TokenSource.IdentityProvider)
+            {
+                DurationTotalInMs = totalDurationInMs,
+                DurationInHttpInMs = apiEvent.DurationInHttpInMs,
+                DurationInCacheInMs = apiEvent.DurationInCacheInMs,
+                CachedAccessTokenCount = apiEvent.CachedAccessTokenCount,
+                CacheRefreshReason = apiEvent.CacheInfo,
+                TokenEndpoint = apiEvent.TokenEndpoint,
+                RegionDetails = apiEvent.RegionOutcome == RegionOutcome.None ? null : CreateRegionDetails(apiEvent),
+            };
+        }
+
         protected virtual void EnrichTelemetryApiEvent(ApiEvent apiEvent)
         {
             // In base classes have them override this to add their properties/fields to the event.
diff --git a/src/client/Microsoft.Identity.Client/MsalException.cs b/src/client/Microsoft.Identity.Client/MsalException.cs
@@ -148,6 +148,22 @@ private set
         public IReadOnlyDictionary<string, string> AdditionalExceptionData { get; set; }
             = CollectionHelpers.GetEmptyDictionary<string, string>();
 
+        /// <summary>
+        /// Diagnostic metadata for the failed token-acquisition attempt — the total duration and, when the
+        /// relevant stage ran, HTTP/cache durations, token endpoint, and region used — or <see langword="null"/>
+        /// when MSAL threw before any metadata was collected. Only values actually captured are populated;
+        /// in particular the total duration is always available (useful for latency measurement) while other
+        /// fields may be 0/null when the corresponding stage did not run. On a failure
+        /// <see cref="AuthenticationResultMetadata.TokenSource"/> has no meaningful value and should not be
+        /// relied on. Reuses the type returned by <see cref="AuthenticationResult.AuthenticationResultMetadata"/>
+        /// on the success path.
+        /// </summary>
+        /// <remarks>
+        /// Populated in-process after the request completes; it is intentionally not part of the exception's
+        /// JSON serialization, so it is not preserved if the exception is marshaled across a process boundary.
+        /// </remarks>
+        public AuthenticationResultMetadata AuthenticationResultMetadata { get; internal set; }
+
         /// <summary>
         /// Creates and returns a string representation of the current exception.
         /// </summary>
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt
@@ -5,3 +5,4 @@ Microsoft.Identity.Client.AppConfig.PoPOptions.MinStrength.set -> void
 Microsoft.Identity.Client.AppConfig.PoPOptions.PoPOptions() -> void
 static Microsoft.Identity.Client.Extensibility.AcquireTokenParameterBuilderExtensions.WithCachePartitionKey<T>(this Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T> builder, string key, string value, bool partitionRefreshToken) -> T
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder, Microsoft.Identity.Client.AppConfig.PoPOptions options) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
+Microsoft.Identity.Client.MsalException.AuthenticationResultMetadata.get -> Microsoft.Identity.Client.AuthenticationResultMetadata
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt
@@ -5,3 +5,4 @@ Microsoft.Identity.Client.AppConfig.PoPOptions.MinStrength.set -> void
 Microsoft.Identity.Client.AppConfig.PoPOptions.PoPOptions() -> void
 static Microsoft.Identity.Client.Extensibility.AcquireTokenParameterBuilderExtensions.WithCachePartitionKey<T>(this Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T> builder, string key, string value, bool partitionRefreshToken) -> T
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder, Microsoft.Identity.Client.AppConfig.PoPOptions options) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
+Microsoft.Identity.Client.MsalException.AuthenticationResultMetadata.get -> Microsoft.Identity.Client.AuthenticationResultMetadata
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net8.0-android/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net8.0-android/PublicAPI.Unshipped.txt
@@ -5,3 +5,4 @@ Microsoft.Identity.Client.AppConfig.PoPOptions.MinStrength.set -> void
 Microsoft.Identity.Client.AppConfig.PoPOptions.PoPOptions() -> void
 static Microsoft.Identity.Client.Extensibility.AcquireTokenParameterBuilderExtensions.WithCachePartitionKey<T>(this Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T> builder, string key, string value, bool partitionRefreshToken) -> T
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder, Microsoft.Identity.Client.AppConfig.PoPOptions options) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
+Microsoft.Identity.Client.MsalException.AuthenticationResultMetadata.get -> Microsoft.Identity.Client.AuthenticationResultMetadata
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net8.0-ios/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net8.0-ios/PublicAPI.Unshipped.txt
@@ -5,3 +5,4 @@ Microsoft.Identity.Client.AppConfig.PoPOptions.MinStrength.set -> void
 Microsoft.Identity.Client.AppConfig.PoPOptions.PoPOptions() -> void
 static Microsoft.Identity.Client.Extensibility.AcquireTokenParameterBuilderExtensions.WithCachePartitionKey<T>(this Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T> builder, string key, string value, bool partitionRefreshToken) -> T
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder, Microsoft.Identity.Client.AppConfig.PoPOptions options) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
+Microsoft.Identity.Client.MsalException.AuthenticationResultMetadata.get -> Microsoft.Identity.Client.AuthenticationResultMetadata
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net8.0/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net8.0/PublicAPI.Unshipped.txt
@@ -5,3 +5,4 @@ Microsoft.Identity.Client.AppConfig.PoPOptions.MinStrength.set -> void
 Microsoft.Identity.Client.AppConfig.PoPOptions.PoPOptions() -> void
 static Microsoft.Identity.Client.Extensibility.AcquireTokenParameterBuilderExtensions.WithCachePartitionKey<T>(this Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T> builder, string key, string value, bool partitionRefreshToken) -> T
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder, Microsoft.Identity.Client.AppConfig.PoPOptions options) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
+Microsoft.Identity.Client.MsalException.AuthenticationResultMetadata.get -> Microsoft.Identity.Client.AuthenticationResultMetadata
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/netstandard2.0/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/netstandard2.0/PublicAPI.Unshipped.txt
@@ -5,3 +5,4 @@ Microsoft.Identity.Client.AppConfig.PoPOptions.MinStrength.set -> void
 Microsoft.Identity.Client.AppConfig.PoPOptions.PoPOptions() -> void
 static Microsoft.Identity.Client.Extensibility.AcquireTokenParameterBuilderExtensions.WithCachePartitionKey<T>(this Microsoft.Identity.Client.BaseAbstractAcquireTokenParameterBuilder<T> builder, string key, string value, bool partitionRefreshToken) -> T
 static Microsoft.Identity.Client.ManagedIdentityPopExtensions.WithMtlsProofOfPossession(this Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder builder, Microsoft.Identity.Client.AppConfig.PoPOptions options) -> Microsoft.Identity.Client.AcquireTokenForManagedIdentityParameterBuilder
+Microsoft.Identity.Client.MsalException.AuthenticationResultMetadata.get -> Microsoft.Identity.Client.AuthenticationResultMetadata
diff --git a/tests/Microsoft.Identity.Test.Unit/PublicApiTests/AuthenticationOperationTests.cs b/tests/Microsoft.Identity.Test.Unit/PublicApiTests/AuthenticationOperationTests.cs
@@ -189,6 +189,14 @@ public async Task WrongTokenType_Async()
                      .ExecuteAsync()).ConfigureAwait(false);
 
                 Assert.AreEqual(MsalError.TokenTypeMismatch, ex.ErrorCode);
+
+                // This MsalClientException is raised while processing the token response (inside the
+                // request), so the failed attempt still carries diagnostic metadata even though it is not
+                // a MsalServiceException — e.g. the token endpoint that was contacted. This is the value of
+                // exposing AuthenticationResultMetadata on the base MsalException (total duration is always
+                // captured for latency measurement).
+                Assert.IsNotNull(ex.AuthenticationResultMetadata);
+                Assert.IsNotNull(ex.AuthenticationResultMetadata.TokenEndpoint);
             }
         }
 
diff --git a/tests/Microsoft.Identity.Test.Unit/PublicApiTests/ClientCredentialWithRegionTests.cs b/tests/Microsoft.Identity.Test.Unit/PublicApiTests/ClientCredentialWithRegionTests.cs
@@ -594,6 +594,36 @@ public async Task WithAzureRegionWithValidFormatRoutesRegionallyAsync()
             }
         }
 
+        [TestMethod]
+        public async Task FailedTokenRequest_SurfacesMetadataOnMsalServiceException_Async()
+        {
+            // Arrange - a regional client-credentials request whose token endpoint returns a service error.
+            using (var harness = base.CreateTestHarness())
+            {
+                var httpManager = harness.HttpManager;
+                httpManager.AddRegionDiscoveryMockHandler(TestConstants.Region);
+                httpManager.AddMockHandler(new MockHttpMessageHandler()
+                {
+                    ExpectedUrl = $"https://{TestConstants.Region}.login.microsoft.com/common/oauth2/v2.0/token",
+                    ExpectedMethod = HttpMethod.Post,
+                    ResponseMessage = MockHelpers.CreateInvalidClientResponseMessage()
+                });
+
+                IConfidentialClientApplication cca = CreateCca(httpManager, TestConstants.Region);
+
+                // Act
+                MsalServiceException ex = await AssertException.TaskThrowsAsync<MsalServiceException>(() => cca
+                    .AcquireTokenForClient(TestConstants.s_scope)
+                    .ExecuteAsync())
+                    .ConfigureAwait(false);
+
+                // Assert - failure-path metadata is surfaced on the exception, including the region that was used.
+                Assert.IsNotNull(ex.AuthenticationResultMetadata);
+                Assert.IsNotNull(ex.AuthenticationResultMetadata.RegionDetails);
+                Assert.AreEqual(TestConstants.Region, ex.AuthenticationResultMetadata.RegionDetails.RegionUsed);
+            }
+        }
+
         [TestMethod]
         // regression: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/2686
         public async Task OtherCloudWithAuthorityValidationAsync()
diff --git a/tests/Microsoft.Identity.Test.Unit/PublicApiTests/ConfidentialClientApplicationTests.cs b/tests/Microsoft.Identity.Test.Unit/PublicApiTests/ConfidentialClientApplicationTests.cs
@@ -466,6 +466,38 @@ public async Task ClientCreds_And_AAD_LogRequestUri_OnServerError_Async()
             }
         }
 
+        [TestMethod]
+        public async Task ClientCreds_FailedRequest_CarriesFailureMetadata_Async()
+        {
+            using (var httpManager = new MockHttpManager())
+            {
+                var cca = ConfidentialClientApplicationBuilder.Create(TestConstants.ClientId)
+                                                              .WithAuthority(new Uri(ClientApplicationBase.DefaultAuthority), true)
+                                                              .WithClientSecret(TestConstants.ClientSecret)
+                                                              .WithHttpManager(httpManager)
+                                                              .BuildConcrete();
+
+                httpManager.AddInstanceDiscoveryMockHandler();
+                httpManager.AddMockHandler(new MockHttpMessageHandler
+                {
+                    ExpectedMethod = HttpMethod.Post,
+                    ResponseMessage = MockHelpers.CreateInvalidClientResponseMessage()
+                });
+
+                // Act
+                var ex = await AssertException.TaskThrowsAsync<MsalServiceException>(
+                    () => cca.AcquireTokenForClient(TestConstants.s_scope.ToArray()).ExecuteAsync())
+                    .ConfigureAwait(false);
+
+                // Assert - the failed attempt still surfaces metadata on the exception. Only data that was
+                // actually captured is populated: the token endpoint was resolved, but no region was
+                // configured so RegionDetails is left null.
+                Assert.IsNotNull(ex.AuthenticationResultMetadata);
+                Assert.IsNotNull(ex.AuthenticationResultMetadata.TokenEndpoint);
+                Assert.IsNull(ex.AuthenticationResultMetadata.RegionDetails);
+            }
+        }
+
         [TestMethod]
         public async Task ClientCreds_And_ADFS_LogRequestUri_OnServerError_Async()
         {

Original file line number	Diff line number	Diff line change
`@@ -189,6 +189,14 @@ public async Task WrongTokenType_Async()`
`189`	`189`	`.ExecuteAsync()).ConfigureAwait(false);`
`190`	`190`
`191`	`191`	`Assert.AreEqual(MsalError.TokenTypeMismatch, ex.ErrorCode);`
	`192`	`+`
	`193`	`+ // This MsalClientException is raised while processing the token response (inside the`
	`194`	`+ // request), so the failed attempt still carries diagnostic metadata even though it is not`
	`195`	`+ // a MsalServiceException — e.g. the token endpoint that was contacted. This is the value of`
	`196`	`+ // exposing AuthenticationResultMetadata on the base MsalException (total duration is always`
	`197`	`+ // captured for latency measurement).`
	`198`	`+ Assert.IsNotNull(ex.AuthenticationResultMetadata);`
	`199`	`+ Assert.IsNotNull(ex.AuthenticationResultMetadata.TokenEndpoint);`
`192`	`200`	`}`
`193`	`201`	`}`
`194`	`202`