MicrosoftIdentityHttpClientBuilderExtensions.AddMicrosoftIdentityMessageHandler Method

public static Microsoft.Extensions.DependencyInjection.IHttpClientBuilder AddMicrosoftIdentityMessageHandler(this Microsoft.Extensions.DependencyInjection.IHttpClientBuilder builder);

static member AddMicrosoftIdentityMessageHandler : Microsoft.Extensions.DependencyInjection.IHttpClientBuilder -> Microsoft.Extensions.DependencyInjection.IHttpClientBuilder

<Extension()>
Public Function AddMicrosoftIdentityMessageHandler (builder As IHttpClientBuilder) As IHttpClientBuilder

Parameters

Returns

The IHttpClientBuilder for method chaining.

Exceptions

Examples

// Configure the HTTP client
services.AddHttpClient("ApiClient")
    .AddMicrosoftIdentityMessageHandler();

// Use the client with per-request configuration
public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient("ApiClient");
    }

    public async Task<string> GetDataAsync()
    {
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.Scopes.Add("https://api.example.com/.default");
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Remarks

This overload is useful when you need maximum flexibility to configure authentication options on a per-request basis. Since no default options are provided, every request must include authentication options via the WithAuthenticationOptions extension method.

The handler will resolve IAuthorizationHeaderProvider from the service provider at runtime to acquire authorization headers for outgoing requests.

public static Microsoft.Extensions.DependencyInjection.IHttpClientBuilder AddMicrosoftIdentityMessageHandler(this Microsoft.Extensions.DependencyInjection.IHttpClientBuilder builder, Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions options);

static member AddMicrosoftIdentityMessageHandler : Microsoft.Extensions.DependencyInjection.IHttpClientBuilder * Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions -> Microsoft.Extensions.DependencyInjection.IHttpClientBuilder

<Extension()>
Public Function AddMicrosoftIdentityMessageHandler (builder As IHttpClientBuilder, options As MicrosoftIdentityMessageHandlerOptions) As IHttpClientBuilder

Parameters

Returns

The IHttpClientBuilder for method chaining.

Exceptions

Examples

// Pre-configure options
var options = new MicrosoftIdentityMessageHandlerOptions
{
    Scopes = { "https://graph.microsoft.com/.default" }
};
options.WithAgentIdentity("agent-application-id");

// Configure the HTTP client with the pre-built options
services.AddHttpClient("GraphClient", client =>
{
    client.BaseAddress = new Uri("https://graph.microsoft.com");
})
.AddMicrosoftIdentityMessageHandler(options);

// Use the client - authentication is automatic
public class GraphService
{
    private readonly HttpClient _httpClient;

    public GraphService(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient("GraphClient");
    }

    public async Task<string> GetUserProfileAsync()
    {
        var response = await _httpClient.GetAsync("/v1.0/me");
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Remarks

This overload is useful when you have a pre-configured MicrosoftIdentityMessageHandlerOptions instance that should be used for all requests made by this HTTP client. Individual requests can still override these default options using the per-request extension methods.

The handler will resolve IAuthorizationHeaderProvider from the service provider at runtime to acquire authorization headers for outgoing requests.

public static Microsoft.Extensions.DependencyInjection.IHttpClientBuilder AddMicrosoftIdentityMessageHandler(this Microsoft.Extensions.DependencyInjection.IHttpClientBuilder builder, Action<Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions> configureOptions);

static member AddMicrosoftIdentityMessageHandler : Microsoft.Extensions.DependencyInjection.IHttpClientBuilder * Action<Microsoft.Identity.Web.MicrosoftIdentityMessageHandlerOptions> -> Microsoft.Extensions.DependencyInjection.IHttpClientBuilder

<Extension()>
Public Function AddMicrosoftIdentityMessageHandler (builder As IHttpClientBuilder, configureOptions As Action(Of MicrosoftIdentityMessageHandlerOptions)) As IHttpClientBuilder

Parameters

Returns

The IHttpClientBuilder for method chaining.

Exceptions

Examples

// Configure the HTTP client with inline options configuration
services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
})
.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes.Add("https://api.example.com/.default");
    options.RequestAppToken = true;
});

// Use the client - authentication is automatic
public class ApiService
{
    private readonly HttpClient _httpClient;

    public ApiService(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient("MyApiClient");
    }

    public async Task<string> GetDataAsync()
    {
        var response = await _httpClient.GetAsync("/api/data");
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

With agent identity:

services.AddHttpClient("AgentClient")
    .AddMicrosoftIdentityMessageHandler(options =>
    {
        options.Scopes.Add("https://graph.microsoft.com/.default");
        options.WithAgentIdentity("agent-application-id");
        options.RequestAppToken = true;
    });

Remarks

This overload is useful for inline configuration of authentication options. The delegate is called once during service configuration to create the default options for the HTTP client. Individual requests can still override these default options using the per-request extension methods.

The handler will resolve IAuthorizationHeaderProvider from the service provider at runtime to acquire authorization headers for outgoing requests.

public static Microsoft.Extensions.DependencyInjection.IHttpClientBuilder AddMicrosoftIdentityMessageHandler(this Microsoft.Extensions.DependencyInjection.IHttpClientBuilder builder, Microsoft.Extensions.Configuration.IConfiguration configuration, string sectionName);

static member AddMicrosoftIdentityMessageHandler : Microsoft.Extensions.DependencyInjection.IHttpClientBuilder * Microsoft.Extensions.Configuration.IConfiguration * string -> Microsoft.Extensions.DependencyInjection.IHttpClientBuilder

<Extension()>
Public Function AddMicrosoftIdentityMessageHandler (builder As IHttpClientBuilder, configuration As IConfiguration, sectionName As String) As IHttpClientBuilder

Parameters

Returns

The IHttpClientBuilder for method chaining.

Exceptions

Examples

Configuration in appsettings.json:

{
  "DownstreamApi": {
    "Scopes": ["https://api.example.com/.default"]
  },
  "GraphApi": {
    "Scopes": ["https://graph.microsoft.com/.default", "User.Read"]
  }
}

Configure the HTTP client:

// In Program.cs or Startup.cs
services.AddHttpClient("DownstreamApiClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
})
.AddMicrosoftIdentityMessageHandler(
    configuration.GetSection("DownstreamApi"),
    "DownstreamApi");

services.AddHttpClient("GraphClient", client =>
{
    client.BaseAddress = new Uri("https://graph.microsoft.com");
})
.AddMicrosoftIdentityMessageHandler(
    configuration.GetSection("GraphApi"),
    "GraphApi");

Use the clients:

public class MyService
{
    private readonly HttpClient _apiClient;
    private readonly HttpClient _graphClient;

    public MyService(IHttpClientFactory factory)
    {
        _apiClient = factory.CreateClient("DownstreamApiClient");
        _graphClient = factory.CreateClient("GraphClient");
    }

    public async Task<string> GetApiDataAsync()
    {
        var response = await _apiClient.GetAsync("/api/data");
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }

    public async Task<string> GetUserProfileAsync()
    {
        var response = await _graphClient.GetAsync("/v1.0/me");
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Remarks

This overload is useful when you want to configure authentication options from appsettings.json or other configuration sources. The configuration section is bound to a new MicrosoftIdentityMessageHandlerOptions instance using standard configuration binding. Individual requests can still override these default options using the per-request extension methods.

The handler will resolve IAuthorizationHeaderProvider from the service provider at runtime to acquire authorization headers for outgoing requests.