ASP.NET Core 伺服器端和其他 Blazor Web App 安全性案例

此文章說明如何針對額外的安全性情境設定伺服器端 Blazor，包括如何將憑證傳遞至 Blazor 應用程式。

注意

本文中的程式碼範例採用 可空值參考型別 (NRT) 與 .NET 編譯器的空值狀態靜態分析，這在 .NET 6 或更新版本的 ASP.NET Core 中受到支援。 以 .NET 5 或更早版本為目標時，請從文章範例中的?、string?、TodoItem[]?和WeatherForecast[]?類型中移除空類型指定（IEnumerable<GitHubBranch>?）。

將令牌傳遞至伺服器端 Blazor 應用程式

本節適用於 Blazor Web Apps。 針對 Blazor Server，檢視 本文的 .NET 7 版本一節。

如果您只想使用存取令牌透過Blazor Web App進行 Web API 呼叫，請參閱使用DelegatingHandler Web API 呼叫的令牌處理程式一節，其中說明如何使用 實作將使用者的存取令牌附加至傳出要求。 本節中的下列指引適用於需要存取令牌、重新整理令牌和其他驗證屬性伺服器端以用於其他用途的開發人員。

若要將令牌和其他身份驗證屬性儲存於 Blazor Web App 中以便於伺服器端使用，建議使用 IHttpContextAccessor/HttpContext (IHttpContextAccessor、HttpContext)。 從 HttpContext讀取令牌，包括作為 串聯參數，使用 IHttpContextAccessor 支援在獲取令牌的條件下，於靜態伺服器端渲染（靜態 SSR）或預渲染期間，於互動式伺服器渲染時使用這些令牌。 不過，如果使用者在電路建立後進行驗證，令牌將不會更新，因為 HttpContext 是在連線開始時 SignalR 捕獲的。 此外，使用 AsyncLocal<T>IHttpContextAccessor 意味著在讀取 HttpContext之前，您必須小心不要丟失執行上下文。 如需詳細資訊，請參閱 ASP.NET Core Blazor 應用程式中 IHttpContextAccessor/HttpContext。

在服務類別中，取得命名空間Microsoft.AspNetCore.Authentication成員的存取權，以便在GetTokenAsync上呈現HttpContext方法。 在下列範例中，已被註解掉的替代方法是呼叫 AuthenticateAsync 在 HttpContext 上。 針對傳回的 AuthenticateResult.Properties，呼叫 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;
    }
}

服務會在伺服器項目的 Program 檔案中註冊：

builder.Services.AddScoped<AuthenticationProcessor>();

AuthenticationProcessor 可以插入伺服器端服務中，例如，針對預先設定的 DelegatingHandler 中的 HttpClient。 下列範例僅供示範之用，或如果您需要在服務中AuthenticationProcessor執行特殊處理，因為您可以直接插入IHttpContextAccessor並取得令牌以呼叫外部 Web API（如需直接呼叫 Web API 的詳細資訊，請參閱IHttpContextAccessor Web 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);
    }
}

令牌處理程式已註冊，並在Program檔案中作為具名 HTTP 用戶端的委派處理程式：

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

謹慎

確保令牌永遠不會在用戶端（例如 .Client 項目中）傳輸或處理，例如在採用互動式自動渲染的元件中，以及由用戶端或用戶端服務渲染的情況下。 務必讓用戶端呼叫伺服器（專案）來使用令牌處理要求。 令牌和其他驗證數據不應該離開伺服器。

如需互動式自動元件，請參閱 ASP.NET 核心 Blazor 驗證和授權，示範如何在伺服器上保留存取令牌和其他驗證屬性。 此外，請考慮採用 Backend-for-Frontend （BFF） 模式，其採用類似的呼叫結構，如使用 OIDC 提供者的 OpenID Connect 保護 ASP.NET CoreBlazor Web App（OIDC），以及使用 Entra 保護具有 Microsoft Entra ID Microsoft Web 的 ASP.NET Core Blazor Web AppIdentity。

使用令牌處理程序進行 Web API 呼叫

下列方法旨在將使用者的存取令牌附加至外部請求，特別是進行 Web API 呼叫，以與外部 Web API 應用程式溝通。 採用全域互動式伺服器轉譯的Blazor Web App會示範該方法，但相同的一般方法也適用於採用全域互動式自動轉譯模式的Blazor Web App。 請記住的重要概念是，使用HttpContext來存取IHttpContextAccessor只會在伺服器上執行。

如需本節中指引的示範，請參閱 BlazorWebAppOidcBlazorWebAppOidcServer 和 Blazor 範例應用程式 （.NET 8 或更新版本）。 這些範例會採用全域互動式轉譯模式，並使用 Microsoft Entra 進行 OIDC 驗證，而不需使用 Entra 特定的套件。 這些範例示範如何傳遞 JWT 存取令牌來呼叫安全的 Web API。

Microsoft 身分識別平臺 配合 Microsoft Identity Web 套件 針對 Microsoft Entra ID 提供 API，從 Blazor Web App 提供自動令牌管理和更新的 Web API 呼叫功能。 如需詳細資訊，請參閱 GitHub 範例存放庫中的 使用 Microsoft Entra ID 保護 ASP.NET Core Blazor Web App 以及 BlazorWebAppEntraBlazorWebAppEntraBff 範例應用程式（.NET 9 或更新版本）。

子類別 DelegatingHandler ，將使用者的存取令牌附加至傳出要求。 令牌處理程式只會在伺服器上執行，因此使用 HttpContext 是安全的。

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

注意

如需如何從 AuthenticationStateProvider存取 DelegatingHandler 的指引，請參閱傳出要求中間件中的存取AuthenticationStateProvider一節。

在專案的 Program 檔案中，令牌處理程式（TokenHandler）會被註冊為一個範圍服務，並且作為 具名 HTTP 客戶端 的訊息處理程式 AddHttpMessageHandler 進行指定。

在以下範例中，{HTTP CLIENT NAME} 佔位元是 HttpClient 的名稱，而 {BASE ADDRESS} 佔位元是 Web API 的基本位址 URI。 如需有關AddHttpContextAccessor的詳細資訊，請參閱 ASP.NET Core Blazor 應用程式中的 IHttpContextAccessor/HttpContext。

在 Program.cs 中：

builder.Services.AddHttpContextAccessor();

builder.Services.AddScoped<TokenHandler>();

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

範例：

builder.Services.AddScoped<TokenHandler>();

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

您可以從配置提供的 HTTP 用戶端基址中取得，其中builder.Configuration["{CONFIGURATION KEY}"]佔位符是配置鍵：

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

在 appsettings.json中指定 ExternalApiUri。 下列範例會將值設定為外部 Web API 的 localhost 位址：https://localhost:7277。

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

此時，元件所建立的 HttpClient 可以提出安全的 Web API 要求。 在下列範例中，{REQUEST URI} 是相對要求的 URI，而 {HTTP CLIENT NAME} 佔位元符是 HttpClient 的名稱。

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

範例：

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

已針對 規劃 Blazor其他功能，這些功能由 Access AuthenticationStateProvider 在傳出要求中間件中追蹤 （dotnet/aspnetcore #52379） 。 在互動式伺服器模式中提供存取令牌給 HttpClient 的問題，dotnet/aspnetcore是一個已關閉的議題，其中包含有益的討論和針對進階使用案例的潛在解決策略。

設定驗證配置

對於使用多個驗證中介軟體因而具有多個驗證配置的應用程式，可以在 Blazor 檔案的端點設定中明確設定 Program 所使用的配置。 下列範例會設定 OpenID Connect (OIDC) 配置：

using Microsoft.AspNetCore.Authentication.OpenIdConnect;

...

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

用來捕捉使用者以供自訂服務的電路處理程序

使用 CircuitHandler 從 AuthenticationStateProvider 擷取使用者，並在服務中設定使用者。 如果您想更新使用者，請註冊一個回撥函數到 AuthenticationStateChanged，並將 Task 加入佇列，以取得新的使用者並更新服務。 下列範例會示範此方法。

在以下範例中：

• 每次線路重新連線時都會呼叫 OnConnectionUpAsync，為連線的存留期設定使用者。 除非您透過處理常式來實作驗證變更的更新 (下列範例中的 OnConnectionUpAsync)，否則只需要 AuthenticationChanged 方法。
• 呼叫 OnCircuitOpenedAsync 以附加驗證變更的處理常式 AuthenticationChanged，以便更新使用者。
• catch 工作的 UpdateAuthentication 區塊不會對例外狀況採取任何動作，因為目前無法在執行程式碼時報告例外狀況。 如果從工作中擲回例外狀況，則會在應用程式的其他位置回報該例外狀況。

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

在 Program 檔案中：

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

...

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

使用元件中的服務來取得使用者：

@inject UserService UserService

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

若要在 MVC、Razor Pages 和其他 ASP.NET Core 場景的中介軟體中設定使用者，請在驗證中介軟體執行後，於自訂中介軟體中對 SetUser 呼叫 UserService，或使用 IClaimsTransformation 實作來設定使用者。 下列範例採用中介軟體方法。

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

在即將呼叫 app.MapRazorComponents<App>() 檔案中的 Program 之前，呼叫中介軟體：

app.UseMiddleware<UserServiceMiddleware>();

在傳出要求的中介程式中存取 AuthenticationStateProvider

以 AuthenticationStateProvider 建立之 DelegatingHandlerHttpClient 中的 IHttpClientFactory，可以使用線路活動處理常式在傳出要求中介軟體中存取。

注意

如需取得一般指引，了解如何在 ASP.NET Core 應用程式中使用 HttpClient 建立的 IHttpClientFactory 執行個體來定義 HTTP 要求的委派處理常式，請參閱在 ASP.NET Core 中使用 IHttpClientFactory 提出 HTTP 要求 (部分機器翻譯) 的下列各節內容：

• 傳出請求中介軟體
• 在發送請求的中介軟體中使用依賴注入 (DI)

下列範例使用 AuthenticationStateProvider 將已驗證使用者的自訂使用者名稱標頭附加至傳出要求。

首先，在 CircuitServicesAccessor 相依性注入 (DI) 文章的下列部分中，實作 Blazor 類別：

從不同的 DI 範圍存取伺服器端 Blazor 服務 (部分機器翻譯)

使用 CircuitServicesAccessor 來在 AuthenticationStateProvider 實作中存取 DelegatingHandler。

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 檔案中，註冊 AuthenticationStateHandler 並將處理常式新增至 IHttpClientFactory 以建立 HttpClient 執行個體：

builder.Services.AddTransient<AuthenticationStateHandler>();

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