Skip to content

Conversation

@cpp11nullptr
Copy link

@cpp11nullptr cpp11nullptr commented Nov 10, 2025

Purpose

Introduce a “token binding scenario” for confidential client (app-only) token acquisition and downstream API calls:

  • Bind access tokens to a client certificate (expected cnf claim – thumbprint / key reference).
  • Use mutual TLS (mTLS) when calling downstream APIs.
  • Support Bearer / PoP / mTLS protocol selection via AuthorizationHeaderProviderOptions.ProtocolScheme.
  • Provide a service collection extension (one-line enablement) wiring token acquisition + binding + downstream calls.

High-level scenario

  1. Developer enables token binding scenario via new service collection extension (PR states: “add service collection extension to enable token binding”).
  2. A binding certificate is sourced from ClientCredentials (direct cert or via Managed Identity).
  3. Developer specifies a protocol scheme (e.g. ProtocolScheme = "Pop" or future ProtocolScheme = "mtls-pop" / "mtls") in AuthorizationHeaderProviderOptions.
  4. Token acquisition (client credentials flow) is configured accordingly; Entra ID returns a token containing a binding claim (cnf) when certificate binding is active.
  5. The authorization header provider produces the header (currently Bearer <token>; protocol-specific transformations for schemes like Pop are applied internally).
  6. An mTLS-capable HTTP client presents the same certificate during TLS handshake.
  7. Downstream API validates that presented client certificate matches token’s cnf claim (x5t thumbprint).
  8. Fallback path: if no certificate is available (or protocol does not require it), a regular unbound token is retrieved.

@cpp11nullptr cpp11nullptr requested a review from a team as a code owner November 10, 2025 22:25
Copy link
Member

@bgavrilMS bgavrilMS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comments. DevEx needs more clarity.

Copy link
Collaborator

@jmprieur jmprieur left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry I forgot to press "Submit review"

Copilot finished reviewing on behalf of jmprieur November 14, 2025 21:15
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds token binding support for mTLS (mutual TLS) authentication scenarios. The implementation enables acquiring tokens bound to certificates and using those certificates when calling downstream APIs.

Key Changes

  • Introduced MsalMtlsHttpClientFactory for creating HTTP clients configured with binding certificates
  • Extended DefaultAuthorizationHeaderProvider to implement IAuthorizationHeaderProvider2 for returning binding certificates alongside tokens
  • Updated TokenAcquisition to detect mTLS scenarios via authentication scheme and configure token binding accordingly

Reviewed Changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
MsalMtlsHttpClientFactory.cs New factory for creating mTLS-enabled HTTP clients with certificate pooling
DefaultAuthorizationHeaderProvider.cs Extended to support IAuthorizationHeaderProvider2 interface for token binding scenarios
TokenAcquisition.cs Added logic to detect mTLS authentication scheme and enable token binding via WithMtlsProofOfPossession
DownstreamApi.cs Updated to use mTLS HTTP client factory when binding certificate is present
ConfidentialClientApplicationBuilderExtension.cs Added WithBindingCertificateAsync method for configuring binding certificates
MergedOptions.cs Added IsTokenBinding property to track token binding state
TokenAcquirer.cs Updated to populate BindingCertificate in AcquireTokenResult
Test files Comprehensive test coverage for new token binding functionality
PublicAPI files Updated API surface documentation for all target frameworks

@cpp11nullptr
Copy link
Author

Reopened as #3622.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants