如何使用 Identity 來保護 SPA 的 Web API 後端

ASP.NET Core Identity 提供可處理驗證、授權和 identity 管理的 API。 API 可讓您使用 cookie 型驗證來保護 Web API 後端的端點。 權杖型選項適用於無法使用 Cookie 的用戶端，但在使用此選項時，您必須負責確保權杖保持安全。 我們建議針對瀏覽器型應用程式使用 Cookie，因為預設情況下，瀏覽器會自動處理它們，而不會將它們公開給 JavaScript。

本文說明如何使用 Identity 來保護 SPA 的 Web API 後端，例如 Angular、React 和 Vue 應用程式。 相同的後端 API 可用來保護 Blazor WebAssembly 應用程式。

必要條件

本文所示的步驟會將驗證和授權新增至符合下列情況的 ASP.NET Core Web API 應用程式：

• 尚未設定驗證。
• 目標為 net8.0 或更新版本。
• 可以是最小的 API 或控制器型 API。

本文中的一些測試指示會使用專案範本隨附的 Swagger UI。 不需要 Swagger UI 即可使用 Identity 搭配 Web API 後端。

安裝 NuGet 套件

安裝下列 NuGet 套件：

• Microsoft.AspNetCore.Identity.EntityFrameworkCore - 讓 Identity 能夠搭配 Entity Framework Core (EF Core)。
• 它讓 EF Core 能夠搭配資料庫，例如下列其中一個套件：
  • Microsoft.EntityFrameworkCore.SqlServer 或
  • Microsoft.EntityFrameworkCore.Sqlite 或
  • Microsoft.EntityFrameworkCore.InMemory.

若要快速開始使用，請使用記憶體內部資料庫。

之後再將資料庫變更為 SQLite 或 SQL Server，以在測試或供生產環境使用時，在工作階段之間儲存使用者資料。 相較於記憶體內部，這引進了一些複雜度，因為它需要透過移轉建立資料庫，如 EF Core 快速入門教學課程所示。

在 Visual Studio 中使用 NuGet 套件管理員或 dotnet add package CLI 命令來安裝這些套件。

建立 IdentityDbContext

新增名為 ApplicationDbContext 且繼承自 IdentityDbContext<TUser> 的類別：

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

顯示的程式碼會提供特殊的建構函式，讓您能夠針對不同的環境設定資料庫。

新增這些步驟中顯示的程式碼時，視需要新增一或多個下列 using 指示詞。

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

設定 EF Core 內容

如先前所述，開始使用的最簡單方式是使用記憶體內部資料庫。 使用記憶體內部資料庫時，每次執行都會以全新的資料庫開始，且不需要使用移轉。 呼叫 WebApplication.CreateBuilder(args) 之後，新增下列程式碼以將 Identity 設定為使用記憶體內部資料庫：

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

若要在測試或供生產環境使用時，在工作階段之間儲存使用者資料，請將資料庫變更為 SQLite 或 SQL Server。

將 Identity 服務新增至容器

呼叫 WebApplication.CreateBuilder(args) 之後，呼叫 AddAuthorization 以將服務新增至相依性插入 (DI) 容器：

builder.Services.AddAuthorization();

啟用 Identity API

呼叫 WebApplication.CreateBuilder(args) 之後，呼叫 AddIdentityApiEndpoints<TUser>(IServiceCollection) 和 AddEntityFrameworkStores<TContext>(IdentityBuilder)。

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

預設會同時啟用 Cookie 和專屬權杖。 如果登入端點中 useCookies 查詢字串參數為 true，則會在登入時發出 Cookie 和權杖。

對應 Identity 路由

呼叫 builder.Build() 之後，呼叫 MapIdentityApi<TUser>(IEndpointRouteBuilder) 以對應 Identity 端點：

app.MapIdentityApi<IdentityUser>();

保護選取的端點

若要保護端點，請在定義路由的 Map{Method} 呼叫上使用 RequireAuthorization 擴充方法。 例如：

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

RequireAuthorization 方法也可以用來：

• 保護 Swagger UI 端點，如下列範例所示：

  app.MapSwagger().RequireAuthorization();
  

• 使用特定宣告或權限保護，如下列範例所示：

  .RequireAuthorization("Admin");
  

在控制器型 Web API 專案中，將 [Authorize] 屬性套用至控制器或動作，以保護端點。

測試 API

測試驗證的快速方式是使用專案範本隨附的記憶體內部資料庫和 Swagger UI。 下列步驟示範如何使用 Swagger UI 測試 API。 請確定 Swagger UI 端點未受到保護。

嘗試存取受保護的端點

• 執行應用程式並瀏覽至 Swagger UI。
• 展開受保護的端點，例如透過 Web API 範本所建立專案中的 /weatherforecast。
• 選取 [試試看]。
• 選取 [執行]。 回應為 401 - not authorized。

測試註冊

• 展開 /register 並選取 [試用]。

• 在 UI 的 [參數] 區段中，會顯示範例要求本文：

  {
    "email": "string",
    "password": "string"
  }
  

• 以有效的電子郵件地址和密碼取代 "string"，然後選取 [執行]。

  若要符合預設的密碼驗證規則，密碼長度必須至少為六個字元，且至少包含下列每一個字元之一：

  • 大寫字母
  • 小寫字母
  • 數字
  • 非英數字元

  如果您輸入無效的電子郵件地址或錯誤的密碼，結果會包含驗證錯誤。 以下是回應本文的範例，其中包含驗證錯誤：

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

  錯誤會以 ProblemDetails 格式傳回，因此用戶端可以剖析錯誤，並視需要顯示驗證錯誤。

  成功的註冊會導致 200 - OK 回應。

測試登入

• 展開 /login 並選取 [試用]。範例要求本文會顯示兩個額外的參數：

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  此範例不需要額外的 JSON 屬性，因此可以刪除。 將 useCookies 設定為 true。

• 將 "string" 取代為您用來註冊的電子郵件地址和密碼，然後選取 [執行]。

  成功的登入會導致回應標頭的 200 - OK 回應具有 cookie。

重新測試受保護的端點

成功登入之後，請重新執行受保護的端點。 驗證 cookie 會自動隨著要求傳送，而且端點已獲得授權。 Cookie 型驗證會安全地內建至瀏覽器並「正常運作」。

使用非瀏覽器用戶端測試

某些 Web 用戶端預設可能不會在標頭中包含 Cookie：

• 如果您使用工具來測試 API，您可能需要在設定中啟用 Cookie。

• JavaScript fetch API 預設不會包含 Cookie。 藉由在選項中將 credentials 設定為值 include 來啟用它們。

• 在 Blazor WebAssembly 應用程式中執行的 HttpClient 需要 HttpRequestMessage 以包含認證，如下列範例所示：

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

使用權杖型驗證

我們建議在瀏覽器型應用程式中使用 Cookie，因為預設情況下，瀏覽器會自動處理它們，而不會將它們公開給 JavaScript。

系統會發出可用來驗證後續要求的自訂權杖 (ASP.NET Core identity 平台專屬的權杖)。 權杖會以持有人權杖的形式傳入 Authorization 標頭。 也會提供重新整理權杖。 此權杖可讓應用程式在舊權杖到期時要求新的權杖，而不需要強制使用者重新登入。

權杖不是標準的 JSON Web 權杖 (JWT)。 使用自訂權杖是刻意的，因為內建的 Identity API 主要用於簡單案例。 權杖選項不是用來作為功能完整的 identity 服務提供者或權杖伺服器，而是作為無法使用 Cookie 用戶端的 cookie 選項的替代方案。

若要使用權杖型驗證，請在呼叫 /login 端點時，將 useCookies 查詢字串參數設定為 false。 權杖會使用持有人驗證配置。 使用從呼叫 /login 傳回的權杖，對受保護端點的後續呼叫應該新增標頭 Authorization: Bearer <token>，其中的 <token> 是存取權杖。 如需詳細資訊，請參閱本文稍後的使用 POST /login 端點。

登出

若要提供讓使用者登出的方式，請定義 /logout 端點，如下列範例所示：

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

呼叫此端點時，在要求本文中提供空的 JSON 物件 ({})。 下列程式碼是對登出端點的呼叫範例：

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

MapIdentityApi<TUser> 端點

對 MapIdentityApi<TUser> 的呼叫會將下列端點新增至應用程式：

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

使用 POST /register 端點

要求本文必須具有 Email 和 Password 屬性：

{
  "email": "string",
  "password": "string",
}

如需詳細資訊，請參閱

• 本文稍早的測試註冊。
• RegisterRequest.

使用 POST /login 端點

在要求本文中，Email 和 Password 是必要的。 如果已啟用雙重要素驗證 (2FA)，則需要 TwoFactorCode 或 TwoFactorRecoveryCode。 如果未啟用 2FA，則省略 twoFactorCode 和 twoFactorRecoveryCode。 如需詳細資訊，請參閱本文稍後的使用 POST /manage/2fa 端點。

以下是未啟用 2FA 的要求本文範例：

{
  "email": "string",
  "password": "string"
}

以下是已啟用 2FA 的要求本文範例：

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

端點需要查詢字串參數：

• useCookies - 設定為 true 以進行 cookie 型驗證。 設定為 false 或省略以進行權杖型驗證。

如需 cookie 型驗證的詳細資訊，請參閱本文稍早的測試登入。

權杖型驗證

如果 useCookies 為 false 或省略，則會啟用權杖型驗證。 回應本文包含下列屬性：

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

如需這些內容的相關資訊，請參閱 AccessTokenResponse。

將存取權杖放在標頭中以提出已驗證的要求，如下列範例所示

Authorization: Bearer {access token}

當存取權杖即將到期時，呼叫 /refresh 端點。

使用 POST /refresh 端點

僅適用權杖型驗證。 取得新的存取權杖，而不強制使用者重新登入。 當存取權杖即將到期時，呼叫此端點。

要求本文只包含 RefreshToken。 以下是要求本文範例：

{
  "refreshToken": "string"
}

如果呼叫成功，回應主體為新的 AccessTokenResponse，如下列範例所示：

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

使用 GET /confirmEmail 端點

如果已設定 Identity 進行電子郵件確認，則對 /register 端點的成功呼叫會傳送包含 /confirmEmail 端點連結的電子郵件。 連結包含下列查詢字串參數：

• userId
• code
• changedEmail - 只有在使用者於註冊期間變更電子郵件地址時才包含。

Identity 會提供確認電子郵件的預設文字。 根據預設，電子郵件主旨為「確認您的電子郵件」，而電子郵件本文看起來像下列範例：

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

如果 RequireConfirmedEmail 屬性設定為 true，使用者必須在按一下電子郵件中的連結來確認電子郵件地址之後才能登入。 /confirmEmail 端點：

• 確認電子郵件地址，並讓使用者登入。
• 在回應本文中傳回文字「感謝您確認您的電子郵件」。

若要設定 Identity 以進行電子郵件確認，請在 Program.cs 中新增程式碼，以將 RequireConfirmedEmail 設定為 true，並將實作 IEmailSender 的類別新增至 DI 容器。 例如：

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

如需詳細資訊，請參閱 ASP.NET Core 中的帳戶確認和密碼復原。

Identity 也會為需要傳送的其他電子郵件提供預設文字，例如用於 2FA 和密碼重設。 若要自訂這些電子郵件，請提供 IEmailSender 介面的自訂實作。 在上述範例中，EmailSender 是實作 IEmailSender 的類別。 如需詳細資訊，包括實作 IEmailSender 的類別範例，請參閱 ASP.NET Core 中的帳戶確認和密碼復原。

使用 POST /resendConfirmationEmail 端點

只有當位址對已註冊的使用者有效時，才傳送電子郵件。

要求本文只包含 Email。 以下是要求本文範例：

{
  "email": "string"
}

如需詳細資訊，請參閱本文稍早使用 GET /confirmEmail 端點。

使用 POST /forgotPassword 端點

產生包含密碼重設代碼的電子郵件。 使用新密碼將該代碼傳送到 /resetPassword。

要求本文只包含 Email。 以下是範例：

{
  "email": "string"
}

如需如何啟用 Identity 以傳送電子郵件的相關資訊，請參閱使用 GET /confirmEmail 端點。

使用 POST /resetPassword 端點

藉由呼叫 /forgotPassword 端點取得重設代碼之後，呼叫此端點。

要求本文需要 Email、ResetCode 與 NewPassword。 以下是範例：

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

使用 POST /manage/2fa 端點

為使用者設定雙重要素驗證 (2FA)。 啟用 2FA 時，除了電子郵件地址和密碼之外，成功登入還需要驗證器應用程式所產生的代碼。

啟用 2FA

若要為目前驗證的使用者啟用 2FA：

• 呼叫 /manage/2fa 端點，在要求本文中傳送空的 JSON 物件 ({})。

• 回應本文會提供 SharedKey，以及目前不需要的一些其他屬性。 共用金鑰是用來設定驗證器應用程式。 回應本文範例：

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• 使用共用金鑰來取得以時間為基礎的一次性密碼 (TOTP)。 如需詳細資訊，請參閱為在 ASP.NET Core 中為 TOTP 驗證器應用程式啟用產生 QR 代碼。

• 呼叫 /manage/2fa 端點，在要求本文中傳送 TOTP 和 "enable": true。 例如：

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• 回應本文會確認 IsTwoFactorEnabled 為 true，並提供 RecoveryCodes。 當驗證器應用程式無法使用時，會使用復原碼來登入。 成功啟用 2FA 之後的回應本文範例：

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

使用 2FA 登入

呼叫 /login 端點，並在要求本文中傳送電子郵件地址、密碼和 TOTP。 例如：

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

如果使用者無法存取驗證器應用程式，請使用啟用 2FA 時提供的其中一個復原碼呼叫 /login 端點來登入。 要求本文看起來像下列範例：

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

重設復原碼

若要取得新的復原碼集合，請呼叫此端點，並將 ResetRecoveryCodes 設定為 true。 以下是要求本文範例：

{
  "resetRecoveryCodes": true
}

重設共用金鑰

若要取得新的隨機共用金鑰，請呼叫此端點，並將 ResetSharedKey 設定為 true。 以下是要求本文範例：

{
  "resetSharedKey": true
}

重設金鑰會自動停用已驗證使用者的雙重要素登入需求，直到稍後要求重新啟用為止。

忘記電腦

若要清除出現的 cookie「記住我旗標」，請呼叫此端點，並將 ForgetMachine 設定為 true。 以下是要求本文範例：

{
  "forgetMachine": true
}

此端點不會影響權杖型驗證。

使用 GET /manage/info 端點

取得已登入使用者的電子郵件地址和電子郵件確認狀態。 基於安全性考量，已從此端點省略宣告。 如果需要宣告，請使用伺服器端 API 來設定宣告的端點。 或者，不要共用所有使用者的宣告，而是提供可接受宣告並回應使用者是否有宣告的驗證端點。

要求不需要任何參數。 回應本文包含 Email 和 IsEmailConfirmed 屬性，如下列範例所示：

{
  "email": "string",
  "isEmailConfirmed": true
}

使用 POST /manage/info 端點

更新登入使用者的電子郵件地址和密碼。 在要求本文中傳送 NewEmail、NewPassword 和 OldPassword，如下列範例所示：

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

以下是回應本文的範例：

{
  "email": "string",
  "isEmailConfirmed": false
}

另請參閱

如需詳細資訊，請參閱以下資源：

• 選擇 identity 管理解決方案
• .NET Web 應用程式的 Identity 管理解決方案
• ASP.NET Core 中的簡單授權
• 在 ASP.NET Core 專案中將使用者資料新增、下載和刪除至 Identity
• 使用以授權機制保護的使用者資料來建立 ASP.NET Core 應用程式
• ASP.NET Core 中的帳戶確認和密碼復原
• 允許為 ASP.NET Core 中的 TOTP 驗證器應用程式產生 QR 代碼
• SPA 的範例 Web API 後端 .http 檔案會顯示權杖型驗證。 例如：
  • 未設定 useCookies
  • 使用授權標頭來傳遞權杖
  • 顯示重新整理以延伸工作階段，而不強制使用者重新登入
• 使用 Identity 來保護 Web API 後端的範例 Angular 應用程式