Add authorization header provider interface to return token with binding certificate (#223)

* Update create authorization header API to include binding certificate in result

* Extract credentials bound APIs into separated interface

* Change parent of auth header bound provider to generic auth header provider

* Reworded a comment for auth header bound provider

---------

Co-authored-by: Zhenya Polyvanyi <[email protected]>

Author: cpp11nullptr

README.md

@@ -185,6 +185,7 @@ namespace TokenAcquisition {
     }
 
         class IAuthorizationHeaderProvider { <<interface>> }
+        class IAuthorizationHeaderBoundProvider { <<interface>> }
         class IAuthorizationHeaderProvider_TResult_ { <<interface>> }
         class IDownstreamApi { <<interface>>
                +CallApiAsync(...)
@@ -422,6 +423,8 @@ It's also possible (and recommended) to use higher level APIs:
 - IAuthorizationHeaderProvider is the component that provides the authorization header, delegating to the ITokenAcquirer.
   Whereas ITokenAcquirer only knows about tokens, IAuthorizationHeaderProvider knows about protocols (for instance bearer,
   Pop, etc ...)
+- IAuthorizationHeaderBoundProvider extends IAuthorizationHeaderProvider to provide authorization headers along with
+  bound certificate information, useful for scenarios requiring certificate binding details.
 
  ```mermaid
  classDiagram
@@ -458,6 +461,11 @@ It's also possible (and recommended) to use higher level APIs:
     +Task&lt;string&gt; CreateAuthorizationHeaderForAppAsync(string scopes, AuthorizationHeaderProviderOptions downstreamApiOptions, CancellationToken cancellationToken)
     +Task&lt;string&gt; CreateAuthorizationHeaderAsync(IEnumerable&lt;string&gt; scopes, AuthorizationHeaderProviderOptions options, ClaimsPrincipal claimsPrincipal, CancellationToken cancellationToken)
     }
+    class IAuthorizationHeaderBoundProvider { <<interface>>
+    +Task&lt;AuthorizationHeaderInformation&gt; CreateAuthorizationHeaderBoundForUserAsync(IEnumerable&lt;string&gt; scopes, AuthorizationHeaderProviderOptions authorizationHeaderProviderOptions, ClaimsPrincipal claimsPrincipal, CancellationToken cancellationToken)
+    +Task&lt;AuthorizationHeaderInformation&gt; CreateAuthorizationHeaderBoundForAppAsync(string scopes, AuthorizationHeaderProviderOptions downstreamApiOptions, CancellationToken cancellationToken)
+    +Task&lt;AuthorizationHeaderInformation&gt; CreateAuthorizationHeaderBoundAsync(IEnumerable&lt;string&gt; scopes, AuthorizationHeaderProviderOptions options, ClaimsPrincipal claimsPrincipal, CancellationToken cancellationToken)
+    }
     class IDownstreamApi { <<interface>>
     +Task&lt;HttpResponseMessage&gt; CallApiAsync(DownstreamApiOptions downstreamApiOptions, ClaimsPrincipal user, HttpContent content, CancellationToken cancellationToken)
     +Task&lt;HttpResponseMessage&gt; CallApiAsync(string serviceName, Action&lt;DownstreamApiOptions&gt; downstreamApiOptionsOverride, ClaimsPrincipal user, HttpContent content, CancellationToken cancellationToken)
@@ -515,11 +523,13 @@ It's also possible (and recommended) to use higher level APIs:
 
     AuthorizationHeaderProviderOptions <|-- DownstreamApiOptions : Inherits
     DownstreamApiOptions <|-- DownstreamApiOptionsReadOnlyHttpMethod : Inherits
+    IAuthorizationHeaderProvider <|-- IAuthorizationHeaderBoundProvider : Inherits
     CredentialDescription --> "DecryptKeysAuthenticationOptions" AuthorizationHeaderProviderOptions : Has
     AuthorizationHeaderProviderOptions --> "AcquireTokenOptions" AcquireTokenOptions : Has
     AcquireTokenOptions --> "ManagedIdentity" ManagedIdentityOptions : Has
     IDownstreamApi ..> DownstreamApiOptions : Uses
     IAuthorizationHeaderProvider ..> AuthorizationHeaderProviderOptions : Uses
+    IAuthorizationHeaderBoundProvider ..> AuthorizationHeaderProviderOptions : Uses
 
 ```
 

agents.md

@@ -169,6 +169,7 @@ Through its well-designed abstractions and interfaces, Microsoft.Identity.Abstra
 - ITokenAcquirer - Core interface for token acquisition
 - ITokenAcquirerFactory - Factory of Token acquirers
 - IAuthorizationHeaderProvider - creates authorization headers (getting tokens and building the protocol string)
+- IAuthorizationHeaderBoundProvider - extends IAuthorizationHeaderProvider to provide authorization headers with bound certificate information
 - IDownstreamApi - call downstream APIs in an authenticated way.
 
 ### Development Guidelines
@@ -278,7 +279,7 @@ This document replaces the previous `.clinerules` directory structure and consol
 
 ### Original Files Migrated
 - `.clinerules/abstractions-guidelines.md` → Section: Microsoft.Identity.Abstractions Guidelines
-- `.clinerules/ai-guidelines.md` → Section: AI Assistant Guidelines  
+- `.clinerules/ai-guidelines.md` → Section: AI Assistant Guidelines
 - `.clinerules/cline-instructions.md` → Section: AI Assistant Guidelines (Cline-specific content)
 - `.clinerules/csharp-guidelines.md` → Section: C# Development Standards
 

src/Microsoft.Identity.Abstractions/DownstreamApi/IAuthorizationHeaderBoundProvider.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Microsoft.Identity.Abstractions
+{
+    /// <summary>
+    /// Creates an authorization header value that the caller can use to access a protected web API, which supports either unbound or
+    /// bound to a certificate (for example, in an mTLS PoP scenario) tokens.
+    /// </summary>
+    public interface IAuthorizationHeaderBoundProvider : IAuthorizationHeaderProvider<OperationResult<AuthorizationHeaderInformation, AuthorizationHeaderError>>
+    {
+    }
+}

src/Microsoft.Identity.Abstractions/DownstreamApi/IAuthorizationHeaderProvider.cs

@@ -28,7 +28,7 @@ public interface IAuthorizationHeaderProvider
         /// (for instance: "Bearer token", "PoP token", etc ...).
         /// </returns>
         Task<string> CreateAuthorizationHeaderForUserAsync(
-            IEnumerable<string> scopes, 
+            IEnumerable<string> scopes,
             AuthorizationHeaderProviderOptions? authorizationHeaderProviderOptions = null,
             ClaimsPrincipal? claimsPrincipal = default,
             CancellationToken cancellationToken = default);
@@ -53,7 +53,7 @@ Task<string> CreateAuthorizationHeaderForAppAsync(
         /// <summary>
         /// Creates an authorization header for calling a protected web API on behalf of a user or the application.
         /// </summary>
-        /// <param name="scopes">The scopes for which to request the authorization header. 
+        /// <param name="scopes">The scopes for which to request the authorization header.
         /// Provide a single scope if the header needs to be created on behalf of an application.</param>
         /// <param name="options">The <see cref="AuthorizationHeaderProviderOptions"/> containing information about the API
         /// to be called and token acquisition settings. If not provided, the header will be for a bearer token.</param>

src/Microsoft.Identity.Abstractions/PublicAPI/net10.0/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider.CreateAuthorizationHeaderBoundAsync(System.Collections.Generic.IEnumerable<string!>! scopes, Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions? options = null, System.Security.Claims.ClaimsPrincipal? claimsPrincipal = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Microsoft.Identity.Abstractions.AuthorizationHeaderInformation!>!
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider.CreateAuthorizationHeaderBoundForAppAsync(string! scopes, Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions? downstreamApiOptions = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Microsoft.Identity.Abstractions.AuthorizationHeaderInformation!>!
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider.CreateAuthorizationHeaderBoundForUserAsync(System.Collections.Generic.IEnumerable<string!>! scopes, Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions? authorizationHeaderProviderOptions = null, System.Security.Claims.ClaimsPrincipal? claimsPrincipal = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Microsoft.Identity.Abstractions.AuthorizationHeaderInformation!>!

src/Microsoft.Identity.Abstractions/PublicAPI/net462/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider

src/Microsoft.Identity.Abstractions/PublicAPI/net8.0/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider

src/Microsoft.Identity.Abstractions/PublicAPI/net9.0/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider

src/Microsoft.Identity.Abstractions/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider

src/Microsoft.Identity.Abstractions/PublicAPI/netstandard2.1/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.Identity.Abstractions.IAuthorizationHeaderBoundProvider