ASP.NET základní serverové scénáře a Blazor Web App další scénáře zabezpečení

Tento článek vysvětluje, jak nakonfigurovat serverovou stranu Blazor pro další scénáře zabezpečení, včetně způsobu předávání tokenů do Blazor aplikace.

Poznámka:

Příklady kódu v tomto článku využívají návratové typy s možnou hodnotou null (NRT) a statickou analýzu stavu null kompilátoru .NET, které jsou podporovány v ASP.NET Core na .NET 6 nebo novějších verzích. Při cílení na .NET 5 nebo starší odeberte označení typu null (?) z string?, TodoItem[]?, WeatherForecast[]? a IEnumerable<GitHubBranch>? typy v příkladech článku.

Předání tokenů do aplikace na straně Blazor serveru

Tato část se týká Blazor Web App. Prohlédněte si Blazor Serverčást tohoto článku ve verzi .NET 7.

Pokud chcete pouze použít přístupové tokeny k volání webového Blazor Web App rozhraní API z pojmenovaného klienta HTTP, přečtěte si část Použití obslužné rutiny tokenu pro volání webového rozhraní API , která vysvětluje, jak použít DelegatingHandler implementaci pro připojení přístupového tokenu uživatele k odchozím požadavkům. Následující doprovodné materiály v této části jsou určené pro vývojáře, kteří potřebují přístupové tokeny, obnovovací tokeny a další vlastnosti ověřování na straně serveru pro jiné účely.

Pokud chcete uložit tokeny a další vlastnosti ověřování pro použití na straně serveru, Blazor Web Appdoporučujeme použít IHttpContextAccessor/HttpContext (IHttpContextAccessor, HttpContext). Čtení tokenů z HttpContext, včetně použití jako kaskádového parametru, je pomocí IHttpContextAccessor podporováno pro získání tokenů k použití během interaktivního vykreslování na serveru, pokud jsou tokeny získány během statického vykreslování na straně serveru (statické SSR) nebo předběžného vykreslování. Tokeny se ale neaktualizují, pokud se uživatel ověří po navázání okruhu, protože se HttpContext zachytí na začátku SignalR připojení. Také použití AsyncLocal<T> ze strany IHttpContextAccessor znamená, že musíte být opatrní, abyste neztratili kontext provádění před čtením HttpContext. Další informace najdete v tématu IHttpContextAccessor/HttpContext v aplikacích ASP.NET CoreBlazor.

Ve třídě služby získejte přístup k členům jmenného prostoru Microsoft.AspNetCore.Authentication k zpřístupnění metody GetTokenAsync na HttpContext. Alternativním přístupem, který je okomentovaný v následujícím příkladu, je volat AuthenticateAsync na HttpContext. Pro vrácený AuthenticateResult.Properties zavolejte GetTokenValue.

using Microsoft.AspNetCore.Authentication;

public class AuthenticationProcessor(IHttpContextAccessor httpContextAccessor)
{
    public async Task<string?> GetAccessToken()
    {
        if (httpContextAccessor.HttpContext is null)
        {
            throw new Exception("HttpContext not available");
        }

        // Approach 1: Call 'GetTokenAsync'
        var accessToken = await httpContextAccessor.HttpContext
            .GetTokenAsync("access_token");

        // Approach 2: Authenticate the user and call 'GetTokenValue'
        /*
        var authResult = await httpContextAccessor.HttpContext.AuthenticateAsync();
        var accessToken = authResult?.Properties?.GetTokenValue("access_token");
        */

        return accessToken;
    }
}

Služba je zaregistrovaná v souboru projektu Program serveru:

builder.Services.AddScoped<AuthenticationProcessor>();

AuthenticationProcessor lze vložit do služeb na straně serveru, například do DelegatingHandler pro předkonfigurovaný HttpClient. Následující příklad je určen pouze pro demonstrační účely nebo v případě, že potřebujete provést speciální zpracování ve AuthenticationProcessor službě, protože můžete jednoduše vložit IHttpContextAccessor a získat token přímo pro volání externích webových rozhraní API (další informace o použití IHttpContextAccessor přímo k volání webových rozhraní API naleznete v části Použití obslužné rutiny tokenů pro volání webového rozhraní API ).

using System.Net.Http.Headers;

public class TokenHandler(AuthenticationProcessor authProcessor) : 
    DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var accessToken = authProcessor.GetAccessToken();

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", accessToken);

        return await base.SendAsync(request, cancellationToken);
    }
}

Obslužná rutina tokenu je zaregistrovaná a funguje jako delegující obslužná rutina pro pojmenovaného klienta HTTP v Program souboru:

builder.Services.AddHttpContextAccessor();

builder.Services.AddScoped<TokenHandler>();

builder.Services.AddHttpClient("ExternalApi",
      client => client.BaseAddress = new Uri(builder.Configuration["ExternalApiUri"] ?? 
          throw new Exception("Missing base address!")))
      .AddHttpMessageHandler<TokenHandler>();

Upozornění

Ujistěte se, že tokeny nejsou nikdy přenášeny a zpracovávány klientem (.Client projekt), například v komponentě, která přijímá interaktivní automatické zobrazení a je zobrazována na klientovi nebo službě na straně klienta. Vždy požádejte klienta, aby volal server (projekt) pro zpracování požadavků pomocí tokenů. Tokeny a další ověřovací data by nikdy neměly opustit server.

Informace o interaktivních automatických komponentách najdete v tématu ASP.NET Blazor Ověřování a autorizace jádra, který ukazuje, jak na serveru ponechat přístupové tokeny a další vlastnosti ověřování. Zvažte také přijetí vzoru Backend-for-Frontend (BFF), který přijímá podobnou strukturu volání a je popsán v Zabezpečení ASP.NET Core Blazor Web App s OpenID Connect (OIDC) pro poskytovatele OIDC a Zabezpečení ASP.NET Core Blazor Web App s Microsoft Entra ID pro Microsoft Identity web s Entra.

Použijte zpracovač tokenu pro volání webového rozhraní API

Následující přístup je zaměřený na připojení přístupového tokenu uživatele k odchozím požadavkům, konkrétně k volání webového rozhraní API do externích webových aplikací API. Tento přístup je ukázán pro Blazor Web App, který přijímá globální vykreslování interaktivního serveru, ale stejný obecný přístup platí i pro Blazor Web App globální režim interaktivního automatického vykreslování. Důležitým konceptem, který je potřeba mít na paměti, je, že přístup k HttpContext pomocí IHttpContextAccessor se provádí pouze na serveru.

Ukázku pokynů v této části najdete v aplikacích BlazorWebAppOidc a BlazorWebAppOidcServer (.NET 8 nebo novější) v Blazor ukázkovém úložišti GitHubu. Ukázky přijímají globální interaktivní režim vykreslování a ověřování OIDC s Microsoft Entra bez použití balíčků specifických pro Entra. Ukázky ukazují, jak předat přístupový token JWT pro volání zabezpečeného webového rozhraní API.

Microsoft identity platform s webovými balíčky Microsoftu Identity pro Microsoft Entra ID poskytuje rozhraní API pro volání webových rozhraní API z Blazor Web Appaplikací s automatickou správou a obnovováním tokenů. Další informace najdete v tématu Zabezpečení ASP.NET Core Blazor Web App pomocí Microsoft Entra ID a BlazorWebAppEntraBlazorWebAppEntraBff ukázkových aplikací (.NET 9 nebo novější) v Blazor úložišti GitHub s ukázkami.

Podtřída DelegatingHandler pro připojení přístupového tokenu uživatele k odchozím požadavkům. Obslužná rutina tokenu se spustí jenom na serveru, takže použití HttpContext je bezpečné.

TokenHandler.cs:

using System.Net.Http.Headers;
using Microsoft.AspNetCore.Authentication;

public class TokenHandler(IHttpContextAccessor httpContextAccessor) : 
    DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (httpContextAccessor.HttpContext is null)
        {
            throw new Exception("HttpContext not available");
        }

        var accessToken = await httpContextAccessor.HttpContext.GetTokenAsync("access_token");

        if (accessToken is null)
        {
            throw new Exception("No access token");
        }

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", accessToken);

        return await base.SendAsync(request, cancellationToken);
    }
}

Poznámka:

Pokyny, jak přistoupit k AuthenticationStateProvider z DelegatingHandler, najdete v části Přístup k AuthenticationStateProvider v middleware pro odchozí požadavky.

V souboru projektu Program je obslužná rutina tokenu (TokenHandler) registrována jako vymezená služba a určena jako obslužná rutina zpráv pojmenovaného klienta HTTP s AddHttpMessageHandler.

V následujícím příkladu je zástupný symbol {HTTP CLIENT NAME} názvem HttpClient, a zástupný symbol {BASE ADDRESS} je identifikátor URI základní adresy webového rozhraní API. Další informace o AddHttpContextAccessoraplikaci IHttpContextAccessor/HttpContext najdete v aplikacích ASP.NET CoreBlazor.

V Program.cs:

builder.Services.AddHttpContextAccessor();

builder.Services.AddScoped<TokenHandler>();

builder.Services.AddHttpClient("{HTTP CLIENT NAME}",
      client => client.BaseAddress = new Uri("{BASE ADDRESS}"))
      .AddHttpMessageHandler<TokenHandler>();

Příklad:

builder.Services.AddScoped<TokenHandler>();

builder.Services.AddHttpClient("ExternalApi",
      client => client.BaseAddress = new Uri("https://localhost:7277"))
      .AddHttpMessageHandler<TokenHandler>();

Základní adresu klienta HTTP můžete zadat z konfigurace pomocí zástupného symbolu builder.Configuration["{CONFIGURATION KEY}"], kde builder.Configuration["{CONFIGURATION KEY}"] je klíč konfigurace.

new Uri(builder.Configuration["ExternalApiUri"] ?? throw new IOException("No URI!"))

"V appsettings.json určete ExternalApiUri." Následující příklad nastaví hodnotu na adresu localhost externího webového rozhraní API na https://localhost:7277:

"ExternalApiUri": "https://localhost:7277"

V tuto chvíli může komponenta HttpClient vytvořená komponentou provádět zabezpečené požadavky webového rozhraní API. V následujícím příkladu je {REQUEST URI} identifikátor URI relativního požadavku a zástupný symbol {HTTP CLIENT NAME} je název HttpClient.

using var request = new HttpRequestMessage(HttpMethod.Get, "{REQUEST URI}");
var client = ClientFactory.CreateClient("{HTTP CLIENT NAME}");
using var response = await client.SendAsync(request);

Příklad:

using var request = new HttpRequestMessage(HttpMethod.Get, "/weather-forecast");
var client = ClientFactory.CreateClient("ExternalApi");
using var response = await client.SendAsync(request);

Plánují se další funkce pro Blazor, které přístup AuthenticationStateProvider sleduje v middlewaru pro odchozí požadavky (dotnet/aspnetcore #52379). Problém s poskytováním přístupového tokenu pro HttpClient v interaktivním režimu serveru (dotnet/aspnetcore #52390) je uzavřený problém, který obsahuje užitečnou diskuzi a potenciální strategie alternativního řešení pro pokročilé případy použití.

Nastavení schématu ověřování

Pro aplikaci, která používá více než jeden middleware ověřování a má tedy více než jedno schéma ověřování, lze schéma, které Blazor používá, explicitně nastavit v konfiguraci koncového Program bodu souboru. Následující příklad nastaví schéma OpenID Connect (OIDC):

using Microsoft.AspNetCore.Authentication.OpenIdConnect;

...

app.MapRazorComponents<App>().RequireAuthorization(
    new AuthorizeAttribute
    {
        AuthenticationSchemes = OpenIdConnectDefaults.AuthenticationScheme
    })
    .AddInteractiveServerRenderMode();

Obslužná rutina okruhu pro zachycení uživatelů pro vlastní služby

CircuitHandler Použijte k zachycení uživatele ze AuthenticationStateProvider služby a nastavení uživatele ve službě. Pokud chcete aktualizovat uživatele, zaregistrujte zpětná volání a AuthenticationStateChangedTask vytvořte frontu, abyste získali nového uživatele a aktualizovali službu. Následující příklad ukazuje přístup.

V následujícím příkladu:

• OnConnectionUpAsync se volá při každém opětovném připojení okruhu a nastavení uživatele po dobu životnosti připojení. OnConnectionUpAsync Pouze metoda se vyžaduje, pokud neimplementujete aktualizace prostřednictvím obslužné rutiny pro změny ověřování (AuthenticationChangedv následujícím příkladu).
• OnCircuitOpenedAsync je volána pro připojení ověřovací změněné obslužné rutiny , AuthenticationChangedaktualizovat uživatele.
• Blok catchUpdateAuthentication úlohy nemá žádnou akci na výjimky, protože neexistuje způsob, jak v tomto okamžiku při provádění kódu nahlásit výjimky. Pokud je z úlohy vyvoláná výjimka, je výjimka hlášena jinde v aplikaci.

UserService.cs:

using System.Security.Claims;
using Microsoft.AspNetCore.Components.Authorization;
using Microsoft.AspNetCore.Components.Server.Circuits;

public class UserService
{
    private ClaimsPrincipal currentUser = new(new ClaimsIdentity());

    public ClaimsPrincipal GetUser() => currentUser;

    internal void SetUser(ClaimsPrincipal user)
    {
        if (currentUser != user)
        {
            currentUser = user;
        }
    }
}

internal sealed class UserCircuitHandler(
        AuthenticationStateProvider authenticationStateProvider,
        UserService userService) 
        : CircuitHandler, IDisposable
{
    public override Task OnCircuitOpenedAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        authenticationStateProvider.AuthenticationStateChanged += 
            AuthenticationChanged;

        return base.OnCircuitOpenedAsync(circuit, cancellationToken);
    }

    private void AuthenticationChanged(Task<AuthenticationState> task)
    {
        _ = UpdateAuthentication(task);

        async Task UpdateAuthentication(Task<AuthenticationState> task)
        {
            try
            {
                var state = await task;
                userService.SetUser(state.User);
            }
            catch
            {
            }
        }
    }

    public override async Task OnConnectionUpAsync(Circuit circuit, 
        CancellationToken cancellationToken)
    {
        var state = await authenticationStateProvider.GetAuthenticationStateAsync();
        userService.SetUser(state.User);
    }

    public void Dispose()
    {
        authenticationStateProvider.AuthenticationStateChanged -= 
            AuthenticationChanged;
    }
}

V souboru Program:

using Microsoft.AspNetCore.Components.Server.Circuits;
using Microsoft.Extensions.DependencyInjection.Extensions;

...

builder.Services.AddScoped<UserService>();
builder.Services.TryAddEnumerable(
    ServiceDescriptor.Scoped<CircuitHandler, UserCircuitHandler>());

Pomocí služby v komponentě získejte uživatele:

@inject UserService UserService

<h1>Hello, @(UserService.GetUser().Identity?.Name ?? "world")!</h1>

Pokud chcete nastavit uživatele v middlewaru pro MVC, Razor Pages a v jiných scénářích ASP.NET Core, zavolejte SetUserUserService ve vlastním middlewaru po spuštění middlewaru ověřování nebo nastavte uživatele s implementací IClaimsTransformation . Následující příklad přijímá přístup middlewaru.

UserServiceMiddleware.cs:

public class UserServiceMiddleware
{
    private readonly RequestDelegate next;

    public UserServiceMiddleware(RequestDelegate next)
    {
        this.next = next ?? throw new ArgumentNullException(nameof(next));
    }

    public async Task InvokeAsync(HttpContext context, UserService service)
    {
        service.SetUser(context.User);
        await next(context);
    }
}

Bezprostředně před voláním app.MapRazorComponents<App>() do Program souboru zavolejte middleware:

app.UseMiddleware<UserServiceMiddleware>();

Přístup AuthenticationStateProvider k middlewaru odchozích požadavků

Do middlewaru při odchozích požadavcích z AuthenticationStateProvider vytvořeného pomocí DelegatingHandler lze přistupovat pomocí obslužného programu HttpClient.

Poznámka:

Obecné pokyny k definování delegujících obslužných rutin pro požadavky HTTP pomocí instancí vytvořených HttpClient pomocí IHttpClientFactory v aplikacích ASP.NET Core najdete v následujících částech Vytváření požadavků HTTP pomocí IHttpClientFactory v ASP.NET Core:

• Middleware pro odchozí požadavky
• Použití DI v middlewaru odchozích požadavků

Následující příklad používá AuthenticationStateProvider k připojení vlastní hlavičky uživatelského jména pro ověřené uživatele k odchozím požadavkům.

Nejprve implementujte CircuitServicesAccessor třídu v následující části Blazor článku injektáž závislostí (DI):

Přistupte ke službám na straně Blazor serveru z jiného DI kontextu

CircuitServicesAccessor Použijte k přístupu k implementaci AuthenticationStateProviderDelegatingHandler.

AuthenticationStateHandler.cs:

using Microsoft.AspNetCore.Components.Authorization;

public class AuthenticationStateHandler(
    CircuitServicesAccessor circuitServicesAccessor) 
    : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var authStateProvider = circuitServicesAccessor.Services?
            .GetRequiredService<AuthenticationStateProvider>();

        if (authStateProvider is null)
        {
            throw new Exception("AuthenticationStateProvider not available");
        }

        var authState = await authStateProvider.GetAuthenticationStateAsync();

        var user = authState?.User;

        if (user?.Identity is not null && user.Identity.IsAuthenticated)
        {
            request.Headers.Add("X-USER-IDENTITY-NAME", user.Identity.Name);
        }

        return await base.SendAsync(request, cancellationToken);
    }
}

Program V souboru zaregistrujte AuthenticationStateHandler a přidejte obslužnou rutinu do IHttpClientFactory instance, která vytváří HttpClient instance:

builder.Services.AddTransient<AuthenticationStateHandler>();

builder.Services.AddHttpClient("HttpMessageHandler")
    .AddHttpMessageHandler<AuthenticationStateHandler>();