Add token binding

Microsoft.Identity.Web.sln

@@ -175,6 +175,12 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.Identity.Web.Side
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sidecar.Tests", "tests\E2E Tests\Sidecar.Tests\Sidecar.Tests.csproj", "{946E6BED-2A06-4FF4-3E39-22ACEB44A984}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "MtlsPop", "MtlsPop", "{06818CF6-16AD-4184-9264-B593B8F2AA25}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MtlsPopClient", "tests\DevApps\MtlsPop\MtlsPopClient\MtlsPopClient.csproj", "{3ECC1B78-A458-726F-D7B8-AB74733CCCDC}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MtlsPopWebApi", "tests\DevApps\MtlsPop\MtlsPopWebApi\MtlsPopWebApi.csproj", "{A61CEEDE-6F2C-0710-E008-B5F6F25D87D7}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -418,6 +424,14 @@ Global
 		{946E6BED-2A06-4FF4-3E39-22ACEB44A984}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{946E6BED-2A06-4FF4-3E39-22ACEB44A984}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{946E6BED-2A06-4FF4-3E39-22ACEB44A984}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3ECC1B78-A458-726F-D7B8-AB74733CCCDC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3ECC1B78-A458-726F-D7B8-AB74733CCCDC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3ECC1B78-A458-726F-D7B8-AB74733CCCDC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3ECC1B78-A458-726F-D7B8-AB74733CCCDC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A61CEEDE-6F2C-0710-E008-B5F6F25D87D7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A61CEEDE-6F2C-0710-E008-B5F6F25D87D7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A61CEEDE-6F2C-0710-E008-B5F6F25D87D7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A61CEEDE-6F2C-0710-E008-B5F6F25D87D7}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -497,6 +511,9 @@ Global
 		{A8181404-23E0-D38B-454C-D16ECDB18B9F} = {E37CDBC1-18F6-4C06-A3EE-532C9106721F}
 		{55C81F88-0FFA-491C-A1D7-0ACA7212B59C} = {1DDE1AAC-5AE6-4725-94B6-A26C58D3423F}
 		{946E6BED-2A06-4FF4-3E39-22ACEB44A984} = {45B20A78-91F8-4DD2-B9AD-F12D3A93536C}
+		{06818CF6-16AD-4184-9264-B593B8F2AA25} = {7786D2DD-9EE4-42E1-B587-740A2E15C41D}
+		{3ECC1B78-A458-726F-D7B8-AB74733CCCDC} = {06818CF6-16AD-4184-9264-B593B8F2AA25}
+		{A61CEEDE-6F2C-0710-E008-B5F6F25D87D7} = {06818CF6-16AD-4184-9264-B593B8F2AA25}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {104367F1-CE75-4F40-B32F-F14853973187}

src/Microsoft.Identity.Web.DownstreamApi/DownstreamApi.cs

@@ -1,22 +1,22 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-using System;
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using System.IO;
-using System.Linq;
-using System.Net.Http;
-using System.Runtime.CompilerServices;
-using System.Security.Claims;
-using System.Text;
-using System.Text.Json;
-using System.Text.Json.Serialization.Metadata;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Logging;
-using Microsoft.Extensions.Options;
-using Microsoft.Identity.Abstractions;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Linq;
+using System.Net.Http;
+using System.Runtime.CompilerServices;
+using System.Security.Claims;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Microsoft.Identity.Abstractions;
 using Microsoft.Identity.Client;
 
 namespace Microsoft.Identity.Web
@@ -26,11 +26,20 @@ internal partial class DownstreamApi : IDownstreamApi
     {
         private readonly IAuthorizationHeaderProvider _authorizationHeaderProvider;
         private readonly IHttpClientFactory _httpClientFactory;
+
+        // This MSAL HTTP client factory is used to create HTTP clients with mTLS binding certificate.
+        // Note, that it doesn't replace _httpClientFactory to keep backward compatibility and ability
+        // to create named HTTP clients for non-mTLS scenarios.
+        private readonly IMsalHttpClientFactory? _msalHttpClientFactory;
+
         private readonly IOptionsMonitor<DownstreamApiOptions> _namedDownstreamApiOptions;
+
         private const string Authorization = "Authorization";
-        protected readonly ILogger<DownstreamApi> _logger;
+        private const string TokenBindingProtocolScheme = "MTLS_POP";
         private const string AuthSchemeDstsSamlBearer = "http://schemas.microsoft.com/dsts/saml2-bearer";
 
+        protected readonly ILogger<DownstreamApi> _logger;
+
         /// <summary>
         /// Constructor.
         /// </summary>
@@ -43,10 +52,33 @@ public DownstreamApi(
             IOptionsMonitor<DownstreamApiOptions> namedDownstreamApiOptions,
             IHttpClientFactory httpClientFactory,
             ILogger<DownstreamApi> logger)
+            : this(authorizationHeaderProvider,
+                  namedDownstreamApiOptions,
+                  httpClientFactory,
+                  logger,
+                  msalHttpClientFactory: null)
+        {
+        }
+
+        /// <summary>
+        /// Constructor which accepts optional MSAL HTTP client factory.
+        /// </summary>
+        /// <param name="authorizationHeaderProvider">Authorization header provider.</param>
+        /// <param name="namedDownstreamApiOptions">Named options provider.</param>
+        /// <param name="httpClientFactory">HTTP client factory.</param>
+        /// <param name="logger">Logger.</param>
+        /// <param name="msalHttpClientFactory">The MSAL HTTP client factory for mTLS PoP scenarios.</param>
+        public DownstreamApi(
+            IAuthorizationHeaderProvider authorizationHeaderProvider,
+            IOptionsMonitor<DownstreamApiOptions> namedDownstreamApiOptions,
+            IHttpClientFactory httpClientFactory,
+            ILogger<DownstreamApi> logger,
+            IMsalHttpClientFactory? msalHttpClientFactory)
         {
             _authorizationHeaderProvider = authorizationHeaderProvider;
             _namedDownstreamApiOptions = namedDownstreamApiOptions;
             _httpClientFactory = httpClientFactory;
+            _msalHttpClientFactory = msalHttpClientFactory ?? new MsalMtlsHttpClientFactory(httpClientFactory);
             _logger = logger;
         }
 
@@ -436,7 +468,7 @@ public Task<HttpResponseMessage> CallApiForAppAsync(
                 string stringContent = await content.ReadAsStringAsync();
                 if (mediaType == "application/json")
                 {
-                    return JsonSerializer.Deserialize<TOutput>(stringContent, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });                    
+                    return JsonSerializer.Deserialize<TOutput>(stringContent, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
                 }
                 if (mediaType != null && !mediaType.StartsWith("text/", StringComparison.OrdinalIgnoreCase))
                 {
@@ -514,11 +546,17 @@ public Task<HttpResponseMessage> CallApiForAppAsync(
                 new HttpMethod(effectiveOptions.HttpMethod),
                 apiUrl);
 
-            await UpdateRequestAsync(httpRequestMessage, content, effectiveOptions, appToken, user, cancellationToken);
+            // Request result will contain authorization header and potentially binding certificate for mTLS
+            var requestResult = await UpdateRequestAsync(httpRequestMessage, content, effectiveOptions, appToken, user, cancellationToken);
 
-            using HttpClient client = string.IsNullOrEmpty(serviceName) ? _httpClientFactory.CreateClient() : _httpClientFactory.CreateClient(serviceName);
+            // If a binding certificate is specified (which means mTLS is required) and MSAL mTLS HTTP factory is present
+            // then create an HttpClient with the certificate by using IMsalMtlsHttpClientFactory.
+            // Otherwise use the default HttpClientFactory with optional named client.
+            HttpClient client = requestResult?.BindingCertificate != null && _msalHttpClientFactory != null && _msalHttpClientFactory is IMsalMtlsHttpClientFactory msalMtlsHttpClientFactory
+                ? msalMtlsHttpClientFactory.GetHttpClient(requestResult.BindingCertificate)
+                : (string.IsNullOrEmpty(serviceName) ? _httpClientFactory.CreateClient() : _httpClientFactory.CreateClient(serviceName));
 
-            // Send the HTTP message           
+            // Send the HTTP message
             var downstreamApiResult = await client.SendAsync(httpRequestMessage, cancellationToken).ConfigureAwait(false);
 
             // Retry only if the resource sent 401 Unauthorized with WWW-Authenticate header and claims
@@ -541,7 +579,7 @@ public Task<HttpResponseMessage> CallApiForAppAsync(
             return downstreamApiResult;
         }
 
-        internal /* internal for test */ async Task UpdateRequestAsync(
+        internal /* internal for test */ async Task<AuthorizationHeaderInformation?> UpdateRequestAsync(
             HttpRequestMessage httpRequestMessage,
             HttpContent? content,
             DownstreamApiOptions effectiveOptions,
@@ -558,15 +596,42 @@ public Task<HttpResponseMessage> CallApiForAppAsync(
 
             effectiveOptions.RequestAppToken = appToken;
 
+            AuthorizationHeaderInformation? authorizationHeaderInformation = null;
+
             // Obtention of the authorization header (except when calling an anonymous endpoint
             // which is done by not specifying any scopes
             if (effectiveOptions.Scopes != null && effectiveOptions.Scopes.Any())
             {
-                string authorizationHeader = await _authorizationHeaderProvider.CreateAuthorizationHeaderAsync(
-                       effectiveOptions.Scopes,
-                       effectiveOptions,
-                       user,
-                       cancellationToken).ConfigureAwait(false);
+                string authorizationHeader = string.Empty;
+
+                // Firstly check if it's token binding scenario so authorization header provider returns
+                // a binding certificate along with acquired authorization header.
+                if (_authorizationHeaderProvider is IBoundAuthorizationHeaderProvider boundAuthorizationHeaderBoundProvider
+                    && string.Equals(effectiveOptions.ProtocolScheme, TokenBindingProtocolScheme, StringComparison.OrdinalIgnoreCase))
+                {
+                    var authorizationHeaderResult = await boundAuthorizationHeaderBoundProvider.CreateBoundAuthorizationHeaderAsync(
+                        effectiveOptions,
+                        user,
+                        cancellationToken).ConfigureAwait(false);
+
+                    if (!authorizationHeaderResult.Succeeded)
+                    {
+                        // in theory it shouldn't happen because in case of error during token acquisition
+                        // there will be thrown corresponding exception, so it's more a safeguard
+                        throw new InvalidOperationException("Cannot acquire bound authorization header.");
+                    }
+
+                    authorizationHeaderInformation = authorizationHeaderResult.Result;
+                    authorizationHeader = authorizationHeaderInformation?.AuthorizationHeaderValue!;
+                }
+                else
+                {
+                    authorizationHeader = await _authorizationHeaderProvider.CreateAuthorizationHeaderAsync(
+                        effectiveOptions.Scopes,
+                        effectiveOptions,
+                        user,
+                        cancellationToken).ConfigureAwait(false);
+                }
 
                 if (authorizationHeader.StartsWith(AuthSchemeDstsSamlBearer, StringComparison.OrdinalIgnoreCase))
                 {
@@ -582,54 +647,56 @@ public Task<HttpResponseMessage> CallApiForAppAsync(
             {
                 Logger.UnauthenticatedApiCall(_logger, null);
             }
-            if (!string.IsNullOrEmpty(effectiveOptions.AcceptHeader))
-            {
-                httpRequestMessage.Headers.Accept.ParseAdd(effectiveOptions.AcceptHeader);
-            }
-
-            // Add extra headers if specified directly on DownstreamApiOptions
-            if (effectiveOptions.ExtraHeaderParameters != null)
-            {
-                foreach (var header in effectiveOptions.ExtraHeaderParameters)
-                {
-                    httpRequestMessage.Headers.TryAddWithoutValidation(header.Key, header.Value);
-                }
-            }
-
-            // Add extra query parameters if specified directly on DownstreamApiOptions
-            if (effectiveOptions.ExtraQueryParameters != null && effectiveOptions.ExtraQueryParameters.Count > 0)
-            {
-                var uriBuilder = new UriBuilder(httpRequestMessage.RequestUri!);
-                var existingQuery = uriBuilder.Query;
-                var queryString = new StringBuilder(existingQuery);
-                
-                foreach (var queryParam in effectiveOptions.ExtraQueryParameters)
-                {
-                    if (queryString.Length > 1) // if there are existing query parameters
-                    {
-                        queryString.Append('&');
-                    }
-                    else if (queryString.Length == 0)
-                    {
-                        queryString.Append('?');
-                    }
-                    
-                    queryString.Append(Uri.EscapeDataString(queryParam.Key));
-                    queryString.Append('=');
-                    queryString.Append(Uri.EscapeDataString(queryParam.Value));
-                }
-                
-                uriBuilder.Query = queryString.ToString().TrimStart('?');
-                httpRequestMessage.RequestUri = uriBuilder.Uri;
-            }
-
-            // Opportunity to change the request message
+            if (!string.IsNullOrEmpty(effectiveOptions.AcceptHeader))
+            {
+                httpRequestMessage.Headers.Accept.ParseAdd(effectiveOptions.AcceptHeader);
+            }
+
+            // Add extra headers if specified directly on DownstreamApiOptions
+            if (effectiveOptions.ExtraHeaderParameters != null)
+            {
+                foreach (var header in effectiveOptions.ExtraHeaderParameters)
+                {
+                    httpRequestMessage.Headers.TryAddWithoutValidation(header.Key, header.Value);
+                }
+            }
+
+            // Add extra query parameters if specified directly on DownstreamApiOptions
+            if (effectiveOptions.ExtraQueryParameters != null && effectiveOptions.ExtraQueryParameters.Count > 0)
+            {
+                var uriBuilder = new UriBuilder(httpRequestMessage.RequestUri!);
+                var existingQuery = uriBuilder.Query;
+                var queryString = new StringBuilder(existingQuery);
+
+                foreach (var queryParam in effectiveOptions.ExtraQueryParameters)
+                {
+                    if (queryString.Length > 1) // if there are existing query parameters
+                    {
+                        queryString.Append('&');
+                    }
+                    else if (queryString.Length == 0)
+                    {
+                        queryString.Append('?');
+                    }
+
+                    queryString.Append(Uri.EscapeDataString(queryParam.Key));
+                    queryString.Append('=');
+                    queryString.Append(Uri.EscapeDataString(queryParam.Value));
+                }
+
+                uriBuilder.Query = queryString.ToString().TrimStart('?');
+                httpRequestMessage.RequestUri = uriBuilder.Uri;
+            }
+
+            // Opportunity to change the request message
             effectiveOptions.CustomizeHttpRequestMessage?.Invoke(httpRequestMessage);
+
+            return authorizationHeaderInformation;
         }
 
         internal /* for test */ static Dictionary<string, string> CallerSDKDetails { get; } = new()
           {
-              { "caller-sdk-id", "IdWeb_1" },  
+              { "caller-sdk-id", "IdWeb_1" },
               { "caller-sdk-ver", IdHelper.GetIdWebVersion() }
           };
 
@@ -657,33 +724,33 @@ private static void AddCallerSDKTelemetry(DownstreamApiOptions effectiveOptions)
         internal static async Task<string> ReadErrorResponseContentAsync(HttpResponseMessage response, CancellationToken cancellationToken = default)
         {
             const int maxErrorContentLength = 4096;
-            
+
             long? contentLength = response.Content.Headers.ContentLength;
-            
+
             if (contentLength.HasValue && contentLength.Value > maxErrorContentLength)
             {
                 return $"[Error response too large: {contentLength.Value} bytes, not captured]";
             }
-            
+
             // Use streaming to read only up to maxErrorContentLength to avoid loading entire response into memory
 #if NET5_0_OR_GREATER
             using var stream = await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false);
 #else
             using var stream = await response.Content.ReadAsStreamAsync().ConfigureAwait(false);
 #endif
             using var reader = new StreamReader(stream);
-            
+
             char[] buffer = new char[maxErrorContentLength];
             int readCount = await reader.ReadBlockAsync(buffer, 0, maxErrorContentLength).ConfigureAwait(false);
-            
+
             string errorResponseContent = new string(buffer, 0, readCount);
-            
+
             // Check if there's more content that was truncated
             if (readCount == maxErrorContentLength && reader.Peek() != -1)
             {
                 errorResponseContent += "... (truncated)";
             }
-            
+
             return errorResponseContent;
         }
     }