MicrosoftIdentityMessageHandler Classe

Definizione

Spazio dei nomi:
Microsoft.Identity.Web
Assembly:
Microsoft.Identity.Web.TokenAcquisition.dll
Pacchetto:
Microsoft.Identity.Web.TokenAcquisition v4.10.0

Implementazione DelegatingHandler che aggiunge automaticamente le intestazioni di autorizzazione alle richieste HTTP in uscita tramite IAuthorizationHeaderProvider e MicrosoftIdentityMessageHandlerOptions.

public class MicrosoftIdentityMessageHandler : System.Net.Http.DelegatingHandler
type MicrosoftIdentityMessageHandler = class
    inherit DelegatingHandler
Public Class MicrosoftIdentityMessageHandler
Inherits DelegatingHandler
Ereditarietà
DelegatingHandler
MicrosoftIdentityMessageHandler

Esempio

Configurazione di base con inserimento delle dipendenze: 

// 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();
    }
}

Opzioni di autenticazione per richiesta: 

// 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);

Utilizzo dell'identità dell'agente: 

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);

Creazione di istanze manuali: 

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");

Gestione degli errori: 

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;
}

Commenti

Questo gestore di messaggi offre un modo flessibile e componibile per aggiungere Microsoft'autenticazione di identità al codice basato su HttpClient. Funge da alternativa a IDownstreamApi per gli scenari in cui gli sviluppatori vogliono mantenere il controllo diretto sulla gestione delle richieste HTTP, sfruttando al contempo le funzionalità di autenticazione di Microsoft Identity Web.

Funzionalità principali:

  • Inserimento automatico dell'intestazione di autorizzazione per tutte le richieste in uscita
  • Opzioni di autenticazione per richiesta tramite metodi di estensione
  • Gestione automatica delle WWW-Authenticate di verifica con l'aggiornamento del token
  • Supporto per scenari di identità dell'agente e identità gestita
  • Registrazione completa e gestione degli errori
  • Compatibilità con più framework (.NET Framework 4.6.2+, .NET Standard 2.0+, .NET 5+)

WWW-Authenticate Gestione delle sfide:

Quando un'API downstream restituisce una risposta non autorizzata 401 con un'intestazione WWW-Authenticate contenente richieste di connessione con attestazioni aggiuntive, questo gestore tenterà automaticamente di acquisire un nuovo token con le attestazioni richieste e ritentare la richiesta. Ciò è particolarmente utile per gli scenari di accesso condizionale in cui sono necessarie attestazioni aggiuntive.

Costruttori

Nome Descrizione
MicrosoftIdentityMessageHandler(IAuthorizationHeaderProvider, MicrosoftIdentityMessageHandlerOptions, ILogger<MicrosoftIdentityMessageHandler>)

Inizializza una nuova istanza della classe MicrosoftIdentityMessageHandler.
MicrosoftIdentityMessageHandler(IAuthorizationHeaderProvider, MicrosoftIdentityMessageHandlerOptions, IMsalMtlsHttpClientFactory, ILogger<MicrosoftIdentityMessageHandler>)

Inizializza una nuova istanza della classe con supporto dell'associazione MicrosoftIdentityMessageHandler di token poP mTLS.

Metodi

Nome Descrizione
SendAsync(HttpRequestMessage, CancellationToken)

Invia una richiesta HTTP con inserimento automatico dell'intestazione di autenticazione. Gestisce WWW-Authenticate problemi tentando l'aggiornamento del token con attestazioni aggiuntive, se necessario.

Si applica a

Vedi anche