使用驗證程式庫保護 ASP.NET Core Blazor WebAssembly 獨立應用程式

注意

這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。

如需目前版本,請參閱本文的 .NET 8 版本

本文說明如何使用 Blazor WebAssembly 驗證程式庫保護 ASP.NET Core Blazor WebAssembly 獨立應用程式。

Blazor WebAssembly 驗證程式庫 (Authentication.js) 僅支援透過 Microsoft 驗證程式庫 (MSAL,msal.js) 的程式碼交換證明金鑰 (PKCE) 授權碼流程。 若要實作其他授與流程,請存取 MSAL 指導以直接實作 MSAL,但我們不支援或建議對 Blazor 應用程式使用 PKCE 以外的授與流程。

針對 Microsoft Entra (ME-ID) 和 Azure Active Directory B2C (AAD B2C) 指導,請勿遵循本主題中的指導。 請參閱使用 Microsoft Entra ID 保護 ASP.NET CoreBlazor WebAssembly 獨立應用程式,或使用 Azure Active Directory B2C 保護 ASP.NET Core Blazor WebAssembly 獨立應用程式

在閱讀本文之後,如需其他安全性案例涵蓋範圍,請參閱 ASP.NET Core Blazor WebAssembly 其他安全性案例

逐步解說

逐步解說的子區段說明如何:

  • 註冊應用程式
  • 建立 Blazor 應用程式
  • 執行應用程式

註冊應用程式

遵循 IP 維護者所提供的指導,向 OpenID Connect (OIDC)Identity 提供者 (IP) 註冊應用程式。

記錄下列資訊:

  • 授權單位 (例如 https://accounts.google.com/)。
  • 應用程式 (用戶端) 識別碼 (例如 2...7-e...q.apps.googleusercontent.com)。
  • 其他 IP 設定 (請參閱 IP 的文件)。

注意

IP 必須使用 OIDC。 例如,Facebook 的 IP 不是 OIDC 相容的提供者,因此本主題中的指導不適用於 Facebook IP。 如需詳細資訊,請參閱 保護 ASP.NET Core 的安全Blazor WebAssembly

建立 Blazor 應用程式

若要建立使用 Microsoft.AspNetCore.Components.WebAssembly.Authentication 程式庫的獨立 Blazor WebAssembly 應用程式,請遵循適用於您所選擇工具的指導。 如果新增對驗證的支援,請參閱本文的應用程式部分一節,以取得設定應用程式的指導。

若要建立一個含驗證機制的新 Blazor WebAssembly 專案:

選擇 [Blazor WebAssembly 應用程式] 範本之後,將 [驗證類型] 設定為 [個別帳戶]

選擇 [Blazor WebAssembly 應用程式] 範本之後,將 [驗證類型] 設定為 [個別帳戶]。 確認選取 [裝載的 ASP.NET Core] 核取方塊。

[個別帳戶] 選項會使用 ASP.NET Core 的 Identity 系統。 此選取項目會新增驗證支援,且不會導致將使用者儲存在資料庫中。 本文的下列各節提供進一步的詳細資料。

設定應用程式

遵循 IP 的指導設定應用程式。 應用程式至少需要應用程式 wwwroot/appsettings.json 檔案中的 Local:AuthorityLocal:ClientId 組態設定:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Google OAuth 2.0 OIDC 範例,適用於在連接埠 5001 localhost 位址上執行的應用程式:

{
  "Local": {
    "Authority": "https://accounts.google.com/",
    "ClientId": "2...7-e...q.apps.googleusercontent.com",
    "PostLogoutRedirectUri": "https://localhost:5001/authentication/logout-callback",
    "RedirectUri": "https://localhost:5001/authentication/login-callback",
    "ResponseType": "id_token"
  }
}

重新導向 URI (https://localhost:5001/authentication/login-callback) 會在 [認證]>{NAME}>[授權重新導向 URI] 的 [Google API 主控台] 中註冊,其中 {NAME} 是 Google API 主控台 OAuth 2.0 用戶端識別碼應用程式清單中的應用程式用戶端名稱。

注意

根據 OAuth 2.0 規格,某些 OIDC IP 不需要提供 localhost 重新導向 URI 的連接埠號碼。 某些 IP 允許回送位址的重新導向 URI 省略連接埠。 其他則允許使用萬用字元作為連接埠號碼 (例如 *)。 如需其他資訊,請參閱 IP 的文件。

執行應用程式

使用下列其中一種方法來執行應用程式:

  • Visual Studio
    • 選取 [執行] 按鈕。
    • 從功能表使用 [偵錯]>[開始偵錯]
    • 請按 F5
  • .NET CLI 命令殼層:從應用程式的資料夾執行 dotnet run 命令。

應用程式的組件

本節說明從 Blazor WebAssembly 專案範本產生的應用程式組件,以及應用程式的設定方式。 如果您使用逐步解說一節中的指導來建立應用程式,則本節中沒有針對基本工作應用程式可遵循的任何特定指導。 本節中的指導有助於更新應用程式以驗證和授權使用者。 不過,更新應用程式的替代方法是從逐步解說一節中的指導建立新的應用程式,並將應用程式的元件、類別和資源移至新的應用程式。

驗證套件

在建立應用程式以使用個別使用者帳戶時,該應用程式會自動接收 Microsoft.AspNetCore.Components.WebAssembly.Authentication 套件的套件參考。 套件提供一組基本類型,可協助應用程式驗證使用者,並取得權杖來呼叫受保護的 API。

如果將驗證新增至應用程式,請手動將 Microsoft.AspNetCore.Components.WebAssembly.Authentication 套件新增至應用程式。

注意

如需將套件新增至 .NET 應用程式的指引,請參閱在套件取用工作流程 (NuGet 文件)安裝及管理套件底下的文章。 在 NuGet.org 確認正確的套件版本。

驗證服務支援

支援使用 Microsoft.AspNetCore.Components.WebAssembly.Authentication 套件所提供的 AddOidcAuthentication 擴充方法,使用 OpenID Connect (OIDC) 驗證在服務容器中註冊的使用者。

AddOidcAuthentication 方法接受回呼,以設定使用 OIDC 驗證應用程式所需的參數。 設定應用程式所需的值可以從 OIDC 相容的 IP 取得。 當您註冊應用程式時取得值的情況通常發生在其線上入口網站中。

針對新的應用程式,請在下列設定中提供 {AUTHORITY}{CLIENT ID} 預留位置的值。 提供搭配應用程式 IP 使用所需的其他設定值。 此範例適用於需要 PostLogoutRedirectUriRedirectUriResponseType 的 Google。 如果將驗證新增至應用程式,請以預留位置和其他設定值的值,手動將下列程式碼和設定新增至應用程式。

Program 檔案中:

builder.Services.AddOidcAuthentication(options =>
{
    builder.Configuration.Bind("Local", options.ProviderOptions);
});

wwwroot/appsettings.json 設定

wwwroot/appsettings.json 檔案會提供設定:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

存取權杖範圍

Blazor WebAssembly 範本會自動設定 openidprofile 的預設範圍。

Blazor WebAssembly 範本不會自動設定應用程式來要求安全 API 的存取權杖。 若要在登入流程中佈建存取權杖,請將範圍新增至 OidcProviderOptions 的預設權杖範圍。 如果將驗證新增至應用程式,請手動新增下列程式碼並設定範圍 URI。

Program 檔案中:

builder.Services.AddOidcAuthentication(options =>
{
    ...
    options.ProviderOptions.DefaultScopes.Add("{SCOPE URI}");
});

如需詳細資訊,請參閱其他案例文章的下列各節:

匯入檔案

Microsoft.AspNetCore.Components.Authorization 命名空間可透過 _Imports.razor 檔案在整個應用程式中使用:

@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@using Microsoft.JSInterop
@using {APPLICATION ASSEMBLY}
@using {APPLICATION ASSEMBLY}.Shared

索引頁面

[索引] 頁面 (wwwroot/index.html) 頁面包含一個指令碼,定義 JavaScript 中的 AuthenticationServiceAuthenticationService 會處理 OIDC 通訊協定的低階詳細資料。 應用程式會在內部呼叫指令碼中定義的方法,來執行驗證作業。

<script src="_content/Microsoft.AspNetCore.Components.WebAssembly.Authentication/AuthenticationService.js"></script>

應用程式元件

App 元件 (App.razor) 類似於在 Blazor Server 應用程式中找到的 App 元件:

  • AuthorizeRouteView 元件可確保目前的使用者有權存取指定頁面,否則會轉譯 RedirectToLogin 元件。
  • RedirectToLogin 元件會管理將未經授權的使用者重新導向至登入頁面。

由於 ASP.NET Core 版本之間的架構變更,所以本節不會顯示 App 元件的 Razor 標記 (App.razor)。 若要檢查指定版本的元件標記,請使用下列任一方法:

  • 針對您想要使用的 ASP.NET Core 版本,從預設 Blazor WebAssembly 專案範本建立要佈建以進行驗證的應用程式。 在產生的應用程式中檢查 App 元件 (App.razor)。

  • 參考來源中檢查 App 元件 (App.razor)。 從分支選擇器中選擇版本,然後在存放庫的 ProjectTemplates 資料夾中搜尋該元件,因為它多年來已經移動。

    注意

    .NET 參考來源的文件連結通常會載入存放庫的預設分支,這表示下一版 .NET 的目前開發。 若要選取特定版本的標籤,請使用 [切換分支或標籤] 下拉式清單。 如需詳細資訊,請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤

RedirectToLogin 元件

RedirectToLogin 元件 (RedirectToLogin.razor):

  • 管理將未經授權的使用者重新導向至登入頁面。
  • 使用者嘗試存取的目前 URL 會如此進行維護,以便在驗證成功時返回該頁面:
    • .NET 7 或更新版本中 ASP.NET Core 中的瀏覽歷程記錄狀態
    • .NET 6 或更早版本中 ASP.NET Core 中的查詢字串。

參考來源中檢查 RedirectToLogin 元件。 該元件的位置已隨著時間而變更,因此請使用 GitHub 搜尋工具來找出該元件。

注意

.NET 參考來源的文件連結通常會載入存放庫的預設分支,這表示下一版 .NET 的目前開發。 若要選取特定版本的標籤,請使用 [切換分支或標籤] 下拉式清單。 如需詳細資訊,請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤

LoginDisplay 元件

LoginDisplay 元件 (LoginDisplay.razor) 是在 MainLayout 元件 (MainLayout.razor) 中進行轉譯,並且管理下列行為:

  • 針對已驗證的使用者:
    • 顯示目前的使用者名稱。
    • 提供 ASP.NET Core Identity 中使用者設定檔頁面的連結。
    • 提供登出應用程式的按鈕。
  • 針對匿名使用者:
    • 提供註冊的選項。
    • 提供登入的選項。

由於 ASP.NET Core 版本之間的架構變更,所以本節不會顯示 LoginDisplay 元件的 Razor 標記。 若要檢查指定版本的元件標記,請使用下列任一方法:

  • 針對您想要使用的 ASP.NET Core 版本,從預設 Blazor WebAssembly 專案範本建立要佈建以進行驗證的應用程式。 在產生的應用程式中檢查 LoginDisplay 元件。

  • 參考來源中檢查 LoginDisplay 元件。 該元件的位置已隨著時間而變更,因此請使用 GitHub 搜尋工具來找出該元件。 使用等於 trueHosted 範本化內容。

    注意

    .NET 參考來源的文件連結通常會載入存放庫的預設分支,這表示下一版 .NET 的目前開發。 若要選取特定版本的標籤,請使用 [切換分支或標籤] 下拉式清單。 如需詳細資訊,請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤

驗證元件

Authentication 元件 (Pages/Authentication.razor) 所產生的頁面會定義處理不同驗證階段所需的路由。

RemoteAuthenticatorView 元件:

@page "/authentication/{action}"
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication

<RemoteAuthenticatorView Action="Action" />

@code {
    [Parameter]
    public string? Action { get; set; }
}

注意

.NET 6 或更新版本中的 ASP.NET Core 中支援可為 Null 參考型別 (NRT) 和 .NET 編譯器 Null 狀態靜態分析。 在 .NET 6 中的 ASP.NET Core 版本之前,string 類型會出現,但沒有 Null 型別指定 (?)。

疑難排解

記錄

若要啟用 Blazor WebAssembly 驗證的偵錯或追蹤記錄,請參閱 ASP.NET Core Blazor 記錄用戶端驗證記錄一節,並將發行項版本選取器設定為 ASP.NET Core 7.0 或更新版本。

常見錯誤

  • 應用程式或 Identity 提供者 (IP) 的設定錯誤

    最常見的錯誤是由不正確的設定所造成。 以下是一些範例:

    • 視案例的需求而定,遺漏或不正確的授權單位、執行個體、租用戶識別碼、租用戶網域、用戶端識別碼或重新導向 URI 會防止應用程式驗證用戶端。
    • 不正確的要求範圍會防止用戶端存取伺服器 Web API 端點。
    • 不正確或遺漏伺服器 API 權限會防止用戶端存取伺服器 Web API 端點。
    • 在與 IP 應用程式註冊的重新導 URI 中設定的連接埠不同的連接埠上執行應用程式。 請注意,Microsoft Entra ID 和在 localhost 開發測試位址執行的應用程式不需要連接埠,但應用程式的連接埠設定和應用程式執行的連接埠必須與非 localhost 位址相符。

    本文指導的設定區段顯示正確設定的範例。 仔細查看文章中有關尋找應用程式和 IP 設定錯誤的每個區段。

    如果設定顯示正確:

    • 分析應用程式記錄檔。

    • 使用瀏覽器的開發人員工具,檢查用戶端應用程式與 IP 或伺服器應用程式之間的網路流量。 通常,在提出要求之後,IP 或伺服器應用程式會傳回錯誤訊息或有導致問題的線索訊息給用戶端。 下列文章中可找到開發人員工具指導:

    • 對於使用 JSON Web Token (JWT) 的 Blazor 版本,根據問題發生的位置,對用於驗證用戶端或存取伺服器 Web API 的權杖內容進行解碼。 如需詳細資訊,請參閱檢查 JSON Web 權杖 (JWT) 的內容

    文件小組會回應文章中的文件意見反應和 BUG (從此頁面意見反應區段開啟問題),但是無法提供產品支援。 有數個公用支援論壇可用來協助針對應用程式進行疑難排解。 我們建議下列事項:

    上述論壇並非由 Microsoft 擁有或控制。

    針對非安全性、非敏感性和非機密可重現架構 BUG 報告,向 ASP.NET Core 產品單位提出問題。 在您徹底調查問題的原因而且無法自行解決,並取得公用支援論壇上社群的協助之前,請勿向產品單位提出問題。 產品單位無法針對因簡單設定錯誤或涉及第三方服務的使用案例而中斷的個別應用程式進行疑難排解。 如果報告本質上是敏感性或機密的,或描述了產品中可能被攻擊者利用的潛在安全性缺陷,請參閱報告安全性問題和錯誤 (dotnet/aspnetcoreGitHub 存放庫)

  • ME-ID 未經授權的用戶端

    info: Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] Authorization failed. 不符合以下需求: DenyAnonymousAuthorizationRequirement:需要已驗證的使用者。

    ME-ID 的登入回呼錯誤:

    • 錯誤: unauthorized_client
    • 描述:AADB2C90058: The provided application is not configured to allow public clients.

    若要解決此錯誤:

    1. 在 Azure 入口網站中,存取應用程式的資訊清單
    2. allowPublicClient 屬性設定為 nulltrue

Cookie 和網站資料

Cookie 和網站資料可以在應用程式更新之間保存,並且干擾測試和疑難排解。 進行應用程式程式碼變更、使用提供者的使用者帳戶變更,或提供者應用程式設定變更時,請清除下列內容:

  • 使用者登入 cookie
  • 應用程式 cookie
  • 快取和儲存的網站資料

防止殘留 cookie 和網站資料干擾測試和疑難排解的其中一種方法是:

  • 設定瀏覽器
    • 使用瀏覽器進行測試,您可以設定在每次關閉瀏覽器時刪除所有 cookie 和網站資料。
    • 請確定瀏覽器已手動關閉或由 IDE 關閉,以便對應用程式、測試使用者或提供者設定進行任何變更。
  • 使用自訂命令,在 Visual Studio 中以私人模式或無痕模式開啟瀏覽器:
    • 從 Visual Studio 的 [執行] 按鈕開啟 [瀏覽方式] 對話方塊。
    • 選取新增按鈕。
    • 在 [程式] 欄位中提供瀏覽器的路徑。 下列可執行檔路徑是 Windows 10 的一般安裝位置。 如果您的瀏覽器安裝在不同的位置,或您不是使用 Windows 10,請提供瀏覽器可執行檔的路徑。
      • Microsoft Edge:C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      • Google Chrome:C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
      • Mozilla Firefox:C:\Program Files\Mozilla Firefox\firefox.exe
    • 在 [引數] 欄位中,提供瀏覽器用來在私人模式或無痕模式中開啟的命令列選項。 某些瀏覽器需要應用程式的 URL。
      • Microsoft Edge:使用 -inprivate
      • Google Chrome:使用 --incognito --new-window {URL},其中預留位置 {URL} 是要開啟的 URL (例如 https://localhost:5001)。
      • Mozilla Firefox:使用 -private -url {URL},其中預留位置 {URL} 是要開啟的 URL (例如 https://localhost:5001)。
    • 在 [自訂名稱] 欄位中提供名稱。 例如: Firefox Auth Testing
    • 選取確定按鈕。
    • 若要避免針對使用應用程式測試的每個反覆項目選取瀏覽器設定檔,請使用 [設為預設值] 按鈕,將設定檔設定為預設值。
    • 請確定瀏覽器已由 IDE 關閉,以便對應用程式、測試使用者或提供者設定進行任何變更。

應用程式升級

在升級開發電腦上的 .NET Core SDK 或變更應用程式內的套件版本之後,正常運作的應用程式便立即發生失敗。 在某些情況下,執行主要升級時,不一致的套件可能會中斷應用程式。 大多數這些問題都可依照下列指示來進行修正:

  1. 從命令殼層執行 dotnet nuget locals all --clear,以清除本機系統的 NuGet 套件快取。
  2. 刪除專案的 binobj 資料夾。
  3. 還原並重建專案。
  4. 在重新部署應用程式之前,請先刪除伺服器上部署資料夾中的所有檔案。

注意

不支援使用與應用程式目標框架不相容的套件版本。 如需套件的詳細資訊,請使用 NuGet 資源庫FuGet 套件總管

執行 Server 應用程式

測試裝載 Blazor WebAssembly方案並且進行疑難排解時,請確定您是從 Server 專案執行應用程式。

檢查使用者

下列 User 元件可以直接在應用程式中使用,或作為進一步自訂的基礎。

User.razor

@page "/user"
@attribute [Authorize]
@using System.Text.Json
@using System.Security.Claims
@inject IAccessTokenProvider AuthorizationService

<h1>@AuthenticatedUser?.Identity?.Name</h1>

<h2>Claims</h2>

@foreach (var claim in AuthenticatedUser?.Claims ?? Array.Empty<Claim>())
{
    <p class="claim">@(claim.Type): @claim.Value</p>
}

<h2>Access token</h2>

<p id="access-token">@AccessToken?.Value</p>

<h2>Access token claims</h2>

@foreach (var claim in GetAccessTokenClaims())
{
    <p>@(claim.Key): @claim.Value.ToString()</p>
}

@if (AccessToken != null)
{
    <h2>Access token expires</h2>

    <p>Current time: <span id="current-time">@DateTimeOffset.Now</span></p>
    <p id="access-token-expires">@AccessToken.Expires</p>

    <h2>Access token granted scopes (as reported by the API)</h2>

    @foreach (var scope in AccessToken.GrantedScopes)
    {
        <p>Scope: @scope</p>
    }
}

@code {
    [CascadingParameter]
    private Task<AuthenticationState> AuthenticationState { get; set; }

    public ClaimsPrincipal AuthenticatedUser { get; set; }
    public AccessToken AccessToken { get; set; }

    protected override async Task OnInitializedAsync()
    {
        await base.OnInitializedAsync();
        var state = await AuthenticationState;
        var accessTokenResult = await AuthorizationService.RequestAccessToken();

        if (!accessTokenResult.TryGetToken(out var token))
        {
            throw new InvalidOperationException(
                "Failed to provision the access token.");
        }

        AccessToken = token;

        AuthenticatedUser = state.User;
    }

    protected IDictionary<string, object> GetAccessTokenClaims()
    {
        if (AccessToken == null)
        {
            return new Dictionary<string, object>();
        }

        // header.payload.signature
        var payload = AccessToken.Value.Split(".")[1];
        var base64Payload = payload.Replace('-', '+').Replace('_', '/')
            .PadRight(payload.Length + (4 - payload.Length % 4) % 4, '=');

        return JsonSerializer.Deserialize<IDictionary<string, object>>(
            Convert.FromBase64String(base64Payload));
    }
}

檢查 JSON Web 權杖 (JWT) 的內容

若要解碼 JSON Web 權杖 (JWT),請使用 Microsoft 的 jwt.ms 工具。 UI 中的值永遠不會離開瀏覽器。

範例編碼 JWT (已縮短顯示):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ilg1ZVhrNHh5b2pORnVtMWtsMll0djhkbE5QNC1j ... bQdHBHGcQQRbW7Wmo6SWYG4V_bU55Ug_PW4pLPr20tTS8Ct7_uwy9DWrzCMzpD-EiwT5IjXwlGX3IXVjHIlX50IVIydBoPQtadvT7saKo1G5Jmutgq41o-dmz6-yBMKV2_nXA25Q

針對 Azure AAD B2C 進行驗證之應用程式的工具所解碼的範例 JWT:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1610059429,
  "nbf": 1610055829,
  "ver": "1.0",
  "iss": "https://mysiteb2c.b2clogin.com/5cc15ea8-a296-4aa3-97e4-226dcc9ad298/v2.0/",
  "sub": "5ee963fb-24d6-4d72-a1b6-889c6e2c7438",
  "aud": "70bde375-fce3-4b82-984a-b247d823a03f",
  "nonce": "b2641f54-8dc4-42ca-97ea-7f12ff4af871",
  "iat": 1610055829,
  "auth_time": 1610055822,
  "idp": "idp.com",
  "tfp": "B2C_1_signupsignin"
}.[Signature]

其他資源