MicrosoftIdentityMessageHandler Constructors
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Overloads
| Name | Description |
|---|---|
| MicrosoftIdentityMessageHandler(IAuthorizationHeaderProvider, MicrosoftIdentityMessageHandlerOptions, ILogger<MicrosoftIdentityMessageHandler>) |
Initializes a new instance of the MicrosoftIdentityMessageHandler class. |
| MicrosoftIdentityMessageHandler(IAuthorizationHeaderProvider, MicrosoftIdentityMessageHandlerOptions, IMsalMtlsHttpClientFactory, ILogger<MicrosoftIdentityMessageHandler>) |
Initializes a new instance of the MicrosoftIdentityMessageHandler class with mTLS PoP token binding support. |
MicrosoftIdentityMessageHandler(IAuthorizationHeaderProvider, MicrosoftIdentityMessageHandlerOptions, ILogger<MicrosoftIdentityMessageHandler>)
Initializes a new instance of the MicrosoftIdentityMessageHandler class.
public MicrosoftIdentityMessageHandler(Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider headerProvider, Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions? defaultOptions = default, Microsoft.Extensions.Logging.ILogger<Microsoft.Identity.Web.MicrosoftIdentityMessageHandler>? logger = default);new Microsoft.Identity.Web.MicrosoftIdentityMessageHandler : Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider * Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions * Microsoft.Extensions.Logging.ILogger<Microsoft.Identity.Web.MicrosoftIdentityMessageHandler> -> Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerPublic Sub New (headerProvider As IAuthorizationHeaderProvider, Optional defaultOptions As MicrosoftIdentityMessageHandlerOptions = Nothing, Optional logger As ILogger(Of MicrosoftIdentityMessageHandler) = Nothing)Parameters
- headerProvider
- IAuthorizationHeaderProvider
The IAuthorizationHeaderProvider used to acquire authorization headers for outgoing requests. This is typically obtained from the dependency injection container.
- defaultOptions
- MicrosoftIdentityMessageHandlerOptions
Default authentication options that will be used for all requests unless overridden per-request
using WithAuthenticationOptions(HttpRequestMessage, MicrosoftIdentityMessageHandlerOptions).
If null, each request must specify its own authentication options or an exception will be thrown.
Optional logger for debugging and monitoring authentication operations. If provided, the handler will log information about token acquisition, challenges, and errors.
Exceptions
Thrown when headerProvider is null.
Examples
Basic usage with default options:
var handler = new MicrosoftIdentityMessageHandler(
headerProvider,
new MicrosoftIdentityMessageHandlerOptions
{
Scopes = { "https://api.example.com/.default" }
});
Usage without default options (per-request configuration required):
var handler = new MicrosoftIdentityMessageHandler(headerProvider);
// Each request must specify options
var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
.WithAuthenticationOptions(options =>
options.Scopes.Add("custom.scope"));
Usage with logging:
var logger = serviceProvider.GetService<ILogger<MicrosoftIdentityMessageHandler>>();
var handler = new MicrosoftIdentityMessageHandler(headerProvider, defaultOptions, logger);
Remarks
The defaultOptions parameter provides a convenient way to set authentication options that apply to all requests made through this handler instance. Individual requests can still override these defaults using the extension methods.
When logger is provided, the handler will log at various levels:
- Debug: Successful authorization header addition
- Information: WWW-Authenticate challenge detection and handling
- Warning: Challenge handling failures
- Error: Token acquisition failures
Applies to
MicrosoftIdentityMessageHandler(IAuthorizationHeaderProvider, MicrosoftIdentityMessageHandlerOptions, IMsalMtlsHttpClientFactory, ILogger<MicrosoftIdentityMessageHandler>)
Initializes a new instance of the MicrosoftIdentityMessageHandler class with mTLS PoP token binding support.
public MicrosoftIdentityMessageHandler(Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider headerProvider, Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions? defaultOptions, Microsoft.Identity.Client.IMsalMtlsHttpClientFactory? mtlsHttpClientFactory, Microsoft.Extensions.Logging.ILogger<Microsoft.Identity.Web.MicrosoftIdentityMessageHandler>? logger = default);new Microsoft.Identity.Web.MicrosoftIdentityMessageHandler : Microsoft.Identity.Abstractions.IAuthorizationHeaderProvider * Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions * Microsoft.Identity.Client.IMsalMtlsHttpClientFactory * Microsoft.Extensions.Logging.ILogger<Microsoft.Identity.Web.MicrosoftIdentityMessageHandler> -> Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerPublic Sub New (headerProvider As IAuthorizationHeaderProvider, defaultOptions As MicrosoftIdentityMessageHandlerOptions, mtlsHttpClientFactory As IMsalMtlsHttpClientFactory, Optional logger As ILogger(Of MicrosoftIdentityMessageHandler) = Nothing)Parameters
- headerProvider
- IAuthorizationHeaderProvider
The IAuthorizationHeaderProvider used to acquire authorization headers for outgoing requests. This is typically obtained from the dependency injection container.
- defaultOptions
- MicrosoftIdentityMessageHandlerOptions
Default authentication options that will be used for all requests unless overridden per-request.
If null, each request must specify its own authentication options or an exception will be thrown.
- mtlsHttpClientFactory
- IMsalMtlsHttpClientFactory
Optional factory for creating HTTP clients configured with mTLS client certificates for token binding
(mTLS PoP) scenarios. When provided and the ProtocolScheme
is set to "MTLS_POP", the handler will use this factory to create an HTTP client with the binding
certificate and send requests through it.
Optional logger for debugging and monitoring authentication operations.
Exceptions
Thrown when headerProvider is null.
Remarks
mTLS PoP (Mutual TLS Proof-of-Possession) token binding, as described in RFC 8705, cryptographically binds access tokens to a specific X.509 certificate. When enabled, the handler acquires a bound token with the certificate thumbprint in the cnf claim, creates an mTLS HTTP client with the binding certificate, and sends requests through the mTLS channel.
Token binding currently supports only application (app-only) tokens. Set RequestAppToken to true.
Prefer using the MicrosoftIdentityHttpClientBuilderExtensions extension methods to configure this handler through dependency injection rather than instantiating it directly.