MicrosoftIdentityMessageHandler Klasse

Definition

public class MicrosoftIdentityMessageHandler : System.Net.Http.DelegatingHandler

type MicrosoftIdentityMessageHandler = class
    inherit DelegatingHandler

Public Class MicrosoftIdentityMessageHandler
Inherits DelegatingHandler

Vererbung

DelegatingHandler

MicrosoftIdentityMessageHandler

Beispiele

Grundlegendes Setup mit Abhängigkeitsinjektion:

// In Program.cs or Startup.cs
services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
})
.AddHttpMessageHandler(serviceProvider => new MicrosoftIdentityMessageHandler(
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>(),
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = { "https://api.example.com/.default" }
    }));

// In a controller or service
public class ApiService
{
    private readonly HttpClient _httpClient;

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

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

Authentifizierungsoptionen pro Anforderung:

// Override scopes for a specific request
var request = new HttpRequestMessage(HttpMethod.Get, "/api/sensitive-data")
    .WithAuthenticationOptions(options =>
    {
        options.Scopes.Add("https://api.example.com/sensitive.read");
        options.RequestAppToken = true;
    });

var response = await _httpClient.SendAsync(request);

Verwendung der Agentidentität:

var request = new HttpRequestMessage(HttpMethod.Get, "/api/agent-data")
    .WithAuthenticationOptions(options =>
    {
        options.Scopes.Add("https://graph.microsoft.com/.default");
        options.WithAgentIdentity("agent-application-id");
        options.RequestAppToken = true;
    });

var response = await _httpClient.SendAsync(request);

Manuelle Instanziierung:

var headerProvider = serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();
var logger = serviceProvider.GetService<ILogger<MicrosoftIdentityMessageHandler>>();

var handler = new MicrosoftIdentityMessageHandler(
    headerProvider,
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = { "https://graph.microsoft.com/.default" }
    },
    logger);

using var httpClient = new HttpClient(handler);
var response = await httpClient.GetAsync("https://graph.microsoft.com/v1.0/me");

Fehlerbehandlung:

try
{
    var response = await _httpClient.SendAsync(request, cancellationToken);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}
catch (MicrosoftIdentityAuthenticationException authEx)
{
    // Handle authentication-specific failures
    _logger.LogError(authEx, "Authentication failed: {Message}", authEx.Message);
    throw;
}
catch (HttpRequestException httpEx)
{
    // Handle other HTTP failures
    _logger.LogError(httpEx, "HTTP request failed: {Message}", httpEx.Message);
    throw;
}

Hinweise

Dieser Nachrichtenhandler bietet eine flexible, komponierbare Möglichkeit, Microsoft Identitätsauthentifizierung httpClient-basierten Code hinzuzufügen. Sie dient als Alternative zu IDownstreamApi Szenarien, in denen Entwickler die direkte Kontrolle über die VERARBEITUNG von HTTP-Anforderungen behalten möchten und gleichzeitig von den Authentifizierungsfunktionen Microsoft Identity Web profitieren.

Wichtige Features:

• Automatische Autorisierungsheadereinfügung für alle ausgehenden Anforderungen
• Authentifizierungsoptionen pro Anforderung mithilfe von Erweiterungsmethoden
• Automatische WWW-Authenticate Behandlung von Herausforderungen bei der Tokenaktualisierung
• Unterstützung für Agentidentitäts- und verwaltete Identitätsszenarien
• Umfassende Protokollierung und Fehlerbehandlung
• Kompatibilität mit mehreren Frameworks (.NET Framework 4.6.2+, .NET Standard 2.0+, .NET 5+)

WWW-Authenticate Problembehandlung:

Wenn eine nachgelagerte API eine 401 Nicht autorisierte Antwort mit einem WWW-Authenticate Header zurückgibt, der Bearer-Herausforderungen mit zusätzlichen Ansprüchen enthält, versucht dieser Handler automatisch, ein neues Token mit den angeforderten Ansprüchen abzurufen und die Anforderung erneut zu versuchen. Dies ist besonders nützlich für Szenarien mit bedingtem Zugriff, in denen zusätzliche Ansprüche erforderlich sind.

Weitere Informationen

• MicrosoftIdentityMessageHandlerOptions
• HttpRequestMessageAuthenticationExtensions
• MicrosoftIdentityAuthenticationException
• IAuthorizationHeaderProvider