Merge branch 'main' into Update-MI-Test-MI-For-Region-Lock-SFI

RyAuld · web-flow · commit 891821845c43 · 2025-11-04T15:26:32.000-08:00
diff --git a/docs/msi_v2/msi_with_credential_design.md b/docs/msi_v2/msi_with_credential_design.md
@@ -16,6 +16,8 @@ The primary objective is to enable seamless token acquisition in MSI V2 for VM/V
 
 In **MSI V1**, IMDS or any other Managed Identity Resource Provider (MIRP) directly returns an **access token**. However, in **MSI V2**, the process involves few more steps:
 
+Conceptual diagram 
+
 ```mermaid
 sequenceDiagram
     participant App as Application
@@ -24,10 +26,31 @@ sequenceDiagram
     participant MAA as Azure MAA
     participant ESTS as Entra STS (mTLS)
 
-    App  ->> MSAL: AcquireTokenForManagedIdentity()
+    App  ->> MSAL: AcquireToken
+    MSAL -> MSAL: Detect that MSIv2 is available, otherwise bail
+    MSAL -> MSAL: Create the strongest key possible, e.g. in the TPM
+    MSAL ->> MAA: Acquire an attestation token, which proves the key strength
+    MSAL ->> IMDS: Certificate Signing Request with (key, attestation token)
+    IMDS -->> MSAL: Certificate associated with key
+    MSAL ->> ESTS: Open mTLS connection to ESTS with this certificate and acquire token
+    ESTS -->> MSAL: token with special claim xms_tb
+    MSAL -->> App: token and certificate    
+```
+
+Technical diagram 
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant MSAL
+    participant IMDS
+    participant MAA as Azure MAA
+    participant ESTS as Entra STS (mTLS)
+
+    App  ->> MSAL: AcquireToken
     MSAL ->> IMDS: GET /metadata/identity/getPlatformMetadata
     IMDS -->> MSAL: client_id, tenant_id, cuid, maa_endpoint
-
+    
     alt Attestable CU
         MSAL ->> MAA: POST /attest/keyguard (attestation info)
         MAA  -->> MSAL: attestation_token
diff --git a/src/client/Microsoft.Identity.Client/AppConfig/IMsalMtlsHttpClientFactory.cs b/src/client/Microsoft.Identity.Client/AppConfig/IMsalMtlsHttpClientFactory.cs
@@ -7,18 +7,18 @@
 namespace Microsoft.Identity.Client
 {
     /// <summary>
-    /// Internal factory responsible for creating HttpClient instances configured for mutual TLS (MTLS).
-    /// This factory is specifically intended for use within the MSAL library for secure communication with Azure AD using MTLS.
-    /// For more details on HttpClient instancing, see https://learn.microsoft.com/dotnet/api/system.net.http.httpclient?view=net-7.0#instancing.
+    /// A factory responsible for creating HttpClient instances configured for mutual TLS (mTLS).
+    /// This factory is intended for use to secure communication with Azure AD using mTLS.
+    /// For more details on HttpClient instancing, see https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient?view=net-8.0#instancing.
     /// </summary>
     /// <remarks>
     /// Implementations of this interface must be thread-safe.
     /// It is important to reuse HttpClient instances to avoid socket exhaustion.
     /// Do not create a new HttpClient for each call to <see cref="GetHttpClient(X509Certificate2)"/>.
     /// If your application requires Integrated Windows Authentication, set <see cref="HttpClientHandler.UseDefaultCredentials"/> to true.
-    /// This interface is intended for internal use by MSAL only and is designed to support MTLS scenarios.
+    /// This interface is designed to support mTLS scenarios.
     /// </remarks>
-    internal interface IMsalMtlsHttpClientFactory : IMsalHttpClientFactory
+    public interface IMsalMtlsHttpClientFactory : IMsalHttpClientFactory
     {
         /// <summary>
         /// Returns an HttpClient configured with a certificate for mutual TLS authentication.
diff --git a/src/client/Microsoft.Identity.Client/Internal/Requests/RequestBase.cs b/src/client/Microsoft.Identity.Client/Internal/Requests/RequestBase.cs
@@ -116,7 +116,7 @@ public async Task<AuthenticationResult> RunAsync(CancellationToken cancellationT
 
                 LogFailureTelemetryToOtel(ex.GetType().Name, apiEvent, apiEvent.CacheInfo);
                 throw;
-            }           
+            }
         }
 
         private void LogSuccessTelemetryToOtel(AuthenticationResult authenticationResult, ApiEvent apiEvent, long durationInUs)
@@ -140,7 +140,7 @@ private void LogFailureTelemetryToOtel(string errorCodeToLog, ApiEvent apiEvent,
                         ServiceBundle.PlatformProxy.GetProductName(),
                         errorCodeToLog,
                         apiEvent.ApiId,
-                        apiEvent.CallerSdkApiId, 
+                        apiEvent.CallerSdkApiId,
                         apiEvent.CallerSdkVersion,
                         cacheRefreshReason,
                         apiEvent.TokenType);
@@ -267,12 +267,12 @@ private void UpdateCallerSdkDetails(ApiEvent apiEvent)
             if (AuthenticationRequestParameters.ExtraQueryParameters.TryGetValue("caller-sdk-id", out callerSdkId))
             {
                 AuthenticationRequestParameters.ExtraQueryParameters.Remove("caller-sdk-id");
-            } 
+            }
             else
             {
                 callerSdkId = AuthenticationRequestParameters.RequestContext.ServiceBundle.Config.ClientName;
             }
-            
+
             if (AuthenticationRequestParameters.ExtraQueryParameters.TryGetValue("caller-sdk-ver", out callerSdkVer))
             {
                 AuthenticationRequestParameters.ExtraQueryParameters.Remove("caller-sdk-ver");
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt
@@ -2,6 +2,8 @@ const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPrev
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
 const Microsoft.Identity.Client.MsalError.MtlsPopTokenNotSupportedinImdsV1 = "mtls_pop_token_not_supported_in_imds_v1" -> string
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Security.Cryptography.X509Certificates.X509Certificate2 x509Certificate2) -> System.Net.Http.HttpClient
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
diff --git a/src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt b/src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt
@@ -2,6 +2,8 @@ const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPrev
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
 const Microsoft.Identity.Client.MsalError.MtlsPopTokenNotSupportedinImdsV1 = "mtls_pop_token_not_supported_in_imds_v1" -> string
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Security.Cryptography.X509Certificates.X509Certificate2 x509Certificate2) -> System.Net.Http.HttpClient
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
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
@@ -2,6 +2,8 @@ const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPrev
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
 const Microsoft.Identity.Client.MsalError.MtlsPopTokenNotSupportedinImdsV1 = "mtls_pop_token_not_supported_in_imds_v1" -> string
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Security.Cryptography.X509Certificates.X509Certificate2 x509Certificate2) -> System.Net.Http.HttpClient
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
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
@@ -2,6 +2,8 @@ const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPrev
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
 const Microsoft.Identity.Client.MsalError.MtlsPopTokenNotSupportedinImdsV1 = "mtls_pop_token_not_supported_in_imds_v1" -> string
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Security.Cryptography.X509Certificates.X509Certificate2 x509Certificate2) -> System.Net.Http.HttpClient
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
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
@@ -2,6 +2,8 @@ const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPrev
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
 const Microsoft.Identity.Client.MsalError.MtlsPopTokenNotSupportedinImdsV1 = "mtls_pop_token_not_supported_in_imds_v1" -> string
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Security.Cryptography.X509Certificates.X509Certificate2 x509Certificate2) -> System.Net.Http.HttpClient
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder
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
@@ -2,6 +2,8 @@ const Microsoft.Identity.Client.MsalError.CannotSwitchBetweenImdsVersionsForPrev
 const Microsoft.Identity.Client.MsalError.InvalidCertificate = "invalid_certificate" -> string
 const Microsoft.Identity.Client.MsalError.MtlsNotSupportedForManagedIdentity = "mtls_not_supported_for_managed_identity" -> string
 const Microsoft.Identity.Client.MsalError.MtlsPopTokenNotSupportedinImdsV1 = "mtls_pop_token_not_supported_in_imds_v1" -> string
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory
+Microsoft.Identity.Client.IMsalMtlsHttpClientFactory.GetHttpClient(System.Security.Cryptography.X509Certificates.X509Certificate2 x509Certificate2) -> System.Net.Http.HttpClient
 Microsoft.Identity.Client.ManagedIdentityApplication.GetManagedIdentitySourceAsync() -> System.Threading.Tasks.Task<Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource>
 Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource.ImdsV2 = 8 -> Microsoft.Identity.Client.ManagedIdentity.ManagedIdentitySource
 Microsoft.Identity.Client.ManagedIdentityApplicationBuilder.WithExtraQueryParameters(System.Collections.Generic.IDictionary<string, string> extraQueryParameters) -> Microsoft.Identity.Client.ManagedIdentityApplicationBuilder

Original file line number	Diff line number	Diff line change
`@@ -116,7 +116,7 @@ public async Task<AuthenticationResult> RunAsync(CancellationToken cancellationT`
`116`	`116`
`117`	`117`	`LogFailureTelemetryToOtel(ex.GetType().Name, apiEvent, apiEvent.CacheInfo);`
`118`	`118`	`throw;`
`119`		`- }`
	`119`	`+ }`
`120`	`120`	`}`
`121`	`121`
`122`	`122`	`private void LogSuccessTelemetryToOtel(AuthenticationResult authenticationResult, ApiEvent apiEvent, long durationInUs)`
`@@ -140,7 +140,7 @@ private void LogFailureTelemetryToOtel(string errorCodeToLog, ApiEvent apiEvent,`
`140`	`140`	`ServiceBundle.PlatformProxy.GetProductName(),`
`141`	`141`	`errorCodeToLog,`
`142`	`142`	`apiEvent.ApiId,`
`143`		`- apiEvent.CallerSdkApiId,`
	`143`	`+ apiEvent.CallerSdkApiId,`
`144`	`144`	`apiEvent.CallerSdkVersion,`
`145`	`145`	`cacheRefreshReason,`
`146`	`146`	`apiEvent.TokenType);`
`@@ -267,12 +267,12 @@ private void UpdateCallerSdkDetails(ApiEvent apiEvent)`
`267`	`267`	`if (AuthenticationRequestParameters.ExtraQueryParameters.TryGetValue("caller-sdk-id", out callerSdkId))`
`268`	`268`	`{`
`269`	`269`	`AuthenticationRequestParameters.ExtraQueryParameters.Remove("caller-sdk-id");`
`270`		`- }`
	`270`	`+ }`
`271`	`271`	`else`
`272`	`272`	`{`
`273`	`273`	`callerSdkId = AuthenticationRequestParameters.RequestContext.ServiceBundle.Config.ClientName;`
`274`	`274`	`}`
`275`		`-`
	`275`	`+`
`276`	`276`	`if (AuthenticationRequestParameters.ExtraQueryParameters.TryGetValue("caller-sdk-ver", out callerSdkVer))`
`277`	`277`	`{`
`278`	`278`	`AuthenticationRequestParameters.ExtraQueryParameters.Remove("caller-sdk-ver");`