.NET 10 全新功能：在 ASP.NET Core Razor Pages 中實作 Passkey 無密碼登入

前言

密碼已是過去式。忘記密碼、弱密碼、密碼被釣魚攻擊——這些問題困擾開發者與使用者多年。在 .NET 10 中，ASP.NET Core Identity 正式內建支援 Passkey（密碼金鑰），讓你不需依賴第三方函式庫，就能為應用程式加上現代化、抗釣魚攻擊的無密碼認證機制。

本文將以 Razor Pages 為範例，帶你從零開始實作完整的 Passkey 註冊與登入流程。

什麼是 Passkey？

Passkey 是基於 Web Authentication API（WebAuthn） 與 FIDO2 標準所設計的密碼替代方案。它使用 非對稱金鑰加密：

  • 私鑰（Private Key）：安全儲存在使用者裝置上（例如 Windows Hello、Touch ID、Face ID，或密碼管理器）。
  • 公鑰（Public Key）：儲存在伺服器端。

認證時，使用者用裝置上的生物辨識或 PIN 驗證身分，私鑰永遠不會離開裝置，公鑰也沒有密碼外洩的風險。

主要優點

特性 說明
抗釣魚 Passkey 與特定網站綁定，無法在假網站使用
無共享秘密 伺服器只存公鑰，資料庫洩露不影響用戶安全
使用方便 指紋、臉部辨識或 PIN 取代複雜密碼
跨裝置同步 透過 iCloud Keychain、Google Password Manager 等跨裝置同步

.NET 10 的 Identity Passkey 支援

.NET 10 將 Passkey 支援直接整合進 ASP.NET Core Identity，提供以下能力：

  • 為既有帳號新增 Passkey 作為額外認證方式
  • 無密碼帳號建立（直接以 Passkey 註冊）
  • 純 Passkey 登入（完全不需要密碼）

重要限制： 此實作專注於 Identity 認證情境，不是完整 WebAuthn 函式庫。如需完整協定支援，可考慮社群套件如 fido2-net-lib。

核心概念

Attestation（證明 / 註冊）

使用者建立並註冊新 Passkey 的過程：

  1. 伺服器產生唯一挑戰（Challenge）
  2. 認證器建立金鑰對，回傳公鑰與 attestation 資料
  3. 伺服器驗證並儲存公鑰，供日後認證使用

Assertion（斷言 / 登入）

使用已存在的 Passkey 進行認證的過程：

  1. 伺服器產生新的挑戰
  2. 認證器用私鑰對挑戰簽名並回傳
  3. 伺服器用已儲存的公鑰驗證簽名，簽名正確即完成認證

環境需求

  • .NET 10 SDK 或更新版本
  • 支援 WebAuthn 的現代瀏覽器（Chrome、Edge、Safari）
  • 具備平台認證器的裝置（Windows Hello、Apple Secure Enclave、實體安全金鑰等）

安全性考量

在實作前，請務必了解以下安全要求：

明確設定 ServerDomain

若未設定 ServerDomain，框架會從 Host Header 推斷，可能導致 credential-scoping 攻擊。建議在正式環境明確設定：

1
2
3
4
builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.ServerDomain = "yourdomain.com"; 
});

子網域安全

在設定的 ServerDomain 範圍內，不可提供未受信任的內容。例如：在 contoso.com 註冊的 Passkey 也適用於 *.contoso.com，需確保所有子網域都受到控制。

實作步驟

以下我們使用**ASP.NET Core Web應用程式(Razor Pages)**專案來練習，

1. 建立 Razor Pages 專案

建立 ASP.NET Core Web應用程式(Razor Pages)，架構選擇 **.NET 10.0(長期支援)**，驗證類型選擇 個別帳戶

1
2
dotnet new webapp --auth Individual -f net10.0 -o PasskeyDemo
cd PasskeyDemo

2. 設定 Identity 與資料庫

  • 預設會使用 SQLite, 資料庫名稱為 app.db
1
2
3
4
5
6
7
8
9
10
11
// Program.cs
builder.Services.AddDefaultIdentity<IdentityUser>(options =>
{
    // 測試用，所以先關掉驗證 Email 的設定
    options.SignIn.RequireConfirmedAccount = false;
    // 重要：必須指定 Version3 才能使用 Passkey 功能
    options.Stores.SchemaVersion = IdentitySchemaVersions.Version3;
})
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddSignInManager()
.AddDefaultTokenProviders();

3. 設定 Passkey 選項

1
2
3
4
5
6
7
builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.ServerDomain = "localhost";            // 伺服器網域
    options.AuthenticatorTimeout = TimeSpan.FromMinutes(3); // 等待逾時
    options.UserVerificationRequirement = "required";       // 強制使用者驗證（生物辨識/PIN）
    options.ResidentKeyRequirement = "preferred";
});

4. 執行 Migration

因為 IdentitySchemaVersions.Version3 新增了 AspNetUserPasskeys 資料表，需要執行 migration：

1
2
3
dotnet ef migrations add SyncIdentitySchemaForNet10
dotnet ef database update
dotnet build

執行後資料庫會新增 AspNetUserPasskeys 資料表，用於儲存每把 Passkey 的公鑰等資料。如下圖，

後端實作

4.1 PageModel：取得登入者的 Passkey 清單（OnGetAsync）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.WebUtilities;

public class IndexModel : PageModel
{
    private readonly UserManager<IdentityUser> _userManager;
    private readonly SignInManager<IdentityUser> _signInManager;
    private readonly ILogger<IndexModel> _logger;
    public IList<UserPasskeyInfo> Passkeys { get; private set; } = [];

    public IndexModel(UserManager<IdentityUser> userManager
    , SignInManager<IdentityUser> signInManager
    , ILogger<IndexModel> logger)
    {
        _userManager = userManager;
        _signInManager = signInManager;
        _logger = logger;
    }

    public async Task OnGetAsync()
    {
        if (User.Identity?.IsAuthenticated != true) return;

        var user = await _userManager.GetUserAsync(User);
        if (user is null) return;

        // 查詢該使用者所有已註冊的 Passkey
        Passkeys = await _userManager.GetPasskeysAsync(user);
    }
}

4.2 Passkey 註冊流程

Step 1：產生 Creation Options

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public async Task<IActionResult> OnPostPasskeyCreationOptions()
{
    if (User.Identity?.IsAuthenticated != true) return Unauthorized();

    var user = await _userManager.GetUserAsync(User);
    if (user is null) return NotFound();

    var userId = await _userManager.GetUserIdAsync(user);
    var userName = await _userManager.GetUserNameAsync(user);

    // 向 SignInManager 取得 WebAuthn 註冊選項 JSON
    // 此方法會查詢 DB 取得既有 Passkey，並填入 excludeCredentials 避免重複
    var optionsJson = await _signInManager.MakePasskeyCreationOptionsAsync(new PasskeyUserEntity
    {
        Id = userId,
        Name = userName,
        DisplayName = userName
    });

    return Content(optionsJson, "application/json");
}

Step 2：驗證並儲存 Passkey

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public async Task<IActionResult> OnPostPasskeyRegistration([FromBody] string credentialJson)
{
    if (User.Identity?.IsAuthenticated != true) return Unauthorized();

    var user = await _userManager.GetUserAsync(User);
    if (user is null) return NotFound();

    // 驗證 attestation（確認 challenge、origin、rpId 等都正確）
    var attestationResult = await _signInManager.PerformPasskeyAttestationAsync(credentialJson);

    if (!attestationResult.Succeeded)
        return BadRequest($"Attestation failed: {attestationResult.Failure?.Message}");

    // 將 Passkey 公鑰等資料寫入 AspNetUserPasskeys 資料表
    var addResult = await _userManager.AddOrUpdatePasskeyAsync(user, attestationResult.Passkey);

    if (!addResult.Succeeded)
        return BadRequest("Failed to store passkey");

    return new JsonResult(new { message = "Passkey registered successfully" });
}

4.3 Passkey 登入流程

Step 1：產生 Request Options

1
2
3
4
5
6
public async Task<IActionResult> OnPostPasskeyRequestOptions()
{
    // 傳 null 表示不限定使用者（讓裝置自行選擇 discoverable credential）
    var optionsJson = await _signInManager.MakePasskeyRequestOptionsAsync(null);
    return Content(optionsJson, "application/json");
}

MakePasskeyRequestOptionsAsync(user) 若帶入特定使用者，response 的 allowCredentials 只會列出該使用者的 Passkey。傳 null 則適合「無帳號輸入」的登入情境。

Step 2：驗證 Assertion 並登入

1
2
3
4
5
6
7
8
9
10
public async Task<IActionResult> OnPostPasskeySignIn([FromBody] string credentialJson)
{
    // PasskeySignInAsync 內部呼叫 PerformPasskeyAssertionAsync，驗證後自動建立 Session
    var result = await _signInManager.PasskeySignInAsync(credentialJson);

    if (result.Succeeded)
        return new OkObjectResult(new { message = "Sign in successful" });

    return Unauthorized();
}

4.4 刪除 Passkey

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public async Task<IActionResult> OnPostDeletePasskey([FromBody] string credentialIdBase64Url)
{
    if (User.Identity?.IsAuthenticated != true) return Unauthorized();

    var user = await _userManager.GetUserAsync(User);
    if (user is null) return NotFound();

    // credentialId 以 Base64Url 格式傳遞，需先解碼
    byte[] credentialId = WebEncoders.Base64UrlDecode(credentialIdBase64Url);

    var result = await _userManager.RemovePasskeyAsync(user, credentialId);

    if (!result.Succeeded) return BadRequest("Failed to delete passkey");

    return new JsonResult(new { message = "Passkey deleted successfully" });
}

UI(Index.cshtml) 實作

在 Razor Pages 中，建議把 UI 分成「已登入」與「未登入」兩個區塊，讓流程清楚：

  • 已登入：可註冊 Passkey、查看已註冊清單、刪除指定 Passkey。
  • 未登入：提供「使用 Passkey 登入」按鈕。

同時放一個隱藏表單承載 Anti-Forgery Token，供 AJAX 呼叫後端 handler 時附帶。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
@page
@model IndexModel
@using Microsoft.AspNetCore.WebUtilities

<form id="passkeyAntiForgeryForm" method="post" style="display:none;">
  @Html.AntiForgeryToken()
</form>

@if (User.Identity?.IsAuthenticated == true)
{
  <div class="text-center">
    <h1 class="display-4">歡迎，@User.Identity.Name！</h1>
    <p>您已成功登入。</p>
  </div>

  <button class="btn btn-primary" id="btnRegisterPasskey">註冊 Passkey</button>

  <hr />
  <h2>已註冊的 Passkeys（@Model.Passkeys.Count）</h2>

  @if (Model.Passkeys.Count == 0)
  {
    <p>目前尚未註冊任何 Passkey。</p>
  }
  else
  {
    <ul class="list-group mb-3">
      @foreach (var passkey in Model.Passkeys)
      {
        var credentialId = WebEncoders.Base64UrlEncode(passkey.CredentialId);
        var label = string.IsNullOrWhiteSpace(passkey.Name) ? "未命名 Passkey" : passkey.Name;

        <li class="list-group-item d-flex justify-content-between align-items-center">
          <div>
            <strong>@label</strong><br />
            <small>建立時間：@passkey.CreatedAt.ToLocalTime()</small>
          </div>
          <button class="btn btn-danger btn-sm btnDeletePasskey"
              data-credential-id="@credentialId">
            刪除
          </button>
        </li>
      }
    </ul>
  }
}
else
{
  <div class="text-center">
    <h1 class="display-4"><a href="/Identity/Account/Login">使用帳號密碼登入</a></h1>
  </div>
  <div class="text-center mt-3">
    <button class="btn btn-success" id="btnSignInPasskey">使用 Passkey 登入</button>
  </div>
}

UI 設計重點

  1. 顯示清單時，將 CredentialId 轉成 Base64Url 字串再放入 data-credential-id，方便前端傳回後端刪除。
  2. Passkeys 來源是 OnGetAsync 透過 UserManager.GetPasskeysAsync(user) 載入，畫面與資料一致。
  3. 每次註冊/刪除/登入成功後重新整理頁面，確保清單、登入狀態與 Cookie 同步。

前端 JavaScript 實作

1
2
3
4
5
6
7
@section Scripts {
    <script>
    $(document).ready(function () {
        //JavaScript 實作
    });
    </script>
}

5.1 確認瀏覽器支援

1
2
3
4
5
6
const browserSupportsPasskeys =
  typeof navigator.credentials !== "undefined" &&
  typeof window.PublicKeyCredential !== "undefined" &&
  typeof window.PublicKeyCredential.parseCreationOptionsFromJSON ===
    "function" &&
  typeof window.PublicKeyCredential.parseRequestOptionsFromJSON === "function";

5.2 Passkey 註冊

  • 按下 註冊 Passkey Button
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
$("#btnRegisterPasskey").click(function () {
  if (browserSupportsPasskeys) {
    console.log("Browser supports Passkeys");
  } else {
    console.warn("Browser does NOT support Passkeys");
    alert(
      "您的瀏覽器不支援 Passkeys 功能，請使用最新版本的 Chrome、Edge 或 Safari 瀏覽器。",
    );
    return;
  }

  const antiForgeryToken = $(
    '#passkeyAntiForgeryForm input[name="__RequestVerificationToken"]',
  ).val();
  // Step 1：向 Server 取得 User's Creation Options
  $.ajax({
    url: '@Url.Page("/Index", "PasskeyCreationOptions")',
    method: "POST",
    headers: {
      RequestVerificationToken: antiForgeryToken,
    },
    success: function (optionsJson) {
      console.log("Received options from server:", optionsJson);

      // Step 2：Parse Options 並呼叫 WebAuthn API
      const options =
        PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);
      console.log("Parsed options object:", options);
      navigator.credentials
        .create({ publicKey: options })
        .then(function (credential) {
          console.log("Credential created:", credential);

          // Step 3：序列化後送回 Server 驗證並儲存（驗題）
          const credentialJson = JSON.stringify(credential);
          const antiForgeryToken = $(
            '#passkeyAntiForgeryForm input[name="__RequestVerificationToken"]',
          ).val();

          $.ajax({
            url: '@Url.Page("/Index", "PasskeyRegistration")',
            method: "POST",
            headers: {
              RequestVerificationToken: antiForgeryToken,
              "Content-Type": "application/json",
            },
            data: JSON.stringify(credentialJson),
            success: function (response) {
              console.log("Passkey registered successfully:", response);
              alert("Passkey 註冊成功！");
              window.location.reload();
            },
            error: function (err) {
              console.error("Error registering passkey:", err);
              alert(
                "Passkey 註冊失敗：" +
                  (err.responseJSON?.message || err.responseText || "未知錯誤"),
              );
            },
          });
        })
        .catch(function (err) {
          console.error("Error creating credential:", err);
          alert("建立 Passkey 失敗：" + err.message);
        });
    },
    error: function (err) {
      console.error("Error fetching options:", err);
    },
  });
});

5.3 Passkey 登入

  • 按下 使用 Passkey 登入 Button
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
$("#btnSignInPasskey").click(function () {
  if (!browserSupportsPasskeys) {
    alert(
      "您的瀏覽器不支援 Passkeys 功能，請使用最新版本的 Chrome、Edge 或 Safari 瀏覽器。",
    );
    return;
  }

  const antiForgeryToken = $(
    '#passkeyAntiForgeryForm input[name="__RequestVerificationToken"]',
  ).val();
  // Step 1：向 Server 取得 Request Options
  $.ajax({
    url: '@Url.Page("/Index", "PasskeyRequestOptions")',
    method: "POST",
    headers: { RequestVerificationToken: antiForgeryToken },
    success: function (optionsJson) {
      console.log("Received request options:", optionsJson);
      // Step 2：Parse Options 並呼叫 WebAuthn API 取得 Assertion
      const options =
        PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
      navigator.credentials
        .get({ publicKey: options })
        .then(function (credential) {
          console.log("Assertion credential:", credential);
          // Step 3：送回 Server 驗證，成功後 Server 就使用 Passkey 登入
          const credentialJson = JSON.stringify(credential);
          const token = $(
            '#passkeyAntiForgeryForm input[name="__RequestVerificationToken"]',
          ).val();
          $.ajax({
            url: '@Url.Page("/Index", "PasskeySignIn")',
            method: "POST",
            headers: {
              RequestVerificationToken: token,
              "Content-Type": "application/json",
            },
            data: JSON.stringify(credentialJson),
            success: function (response) {
              console.log("Sign in successful:", response);
              window.location.reload();
            },
            error: function (err) {
              console.error("Sign in failed:", err);
              alert("Passkey 登入失敗：" + (err.responseText || "未知錯誤"));
            },
          });
        })
        .catch(function (err) {
          console.error("Error getting credential:", err);
          alert("取得 Passkey 失敗：" + err.message);
        });
    },
    error: function (err) {
      console.error("Error fetching request options:", err);
    },
  });
});

5.4 刪除 Passkey

  • 按下 刪除 Passkey 的 Button
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
$(document).on("click", ".btnDeletePasskey", function () {
  const credentialId = $(this).data("credential-id");
  if (!credentialId) {
    alert("找不到要刪除的 Passkey 識別碼。");
    return;
  }

  if (!confirm("確定要刪除此 Passkey 嗎？")) {
    return;
  }

  const antiForgeryToken = $(
    '#passkeyAntiForgeryForm input[name="__RequestVerificationToken"]',
  ).val();
  $.ajax({
    url: '@Url.Page("/Index", "DeletePasskey")',
    method: "POST",
    headers: {
      RequestVerificationToken: antiForgeryToken,
      "Content-Type": "application/json",
    },
    data: JSON.stringify(credentialId),
    success: function () {
      alert("Passkey 已刪除。");
      window.location.reload();
    },
    error: function (err) {
      console.error("Error deleting passkey:", err);
      alert("刪除失敗：" + (err.responseText || "未知錯誤"));
    },
  });
});

完整程式碼

本文只拆解關鍵片段，完整可執行版本我放在 Gist：

操作過程

6.1 登入後註冊 Passkey

6.2 註冊 Passkey 成功後，會在 Passkey 列出註冊的資料

6.3 預設會存在 Browser 的密碼中

  • 重覆註冊 Passkey 會發出 建立 Passkey 失敗：The user attempted to register an authenticator that contains one of the credentials already registered with the relying party. 的錯誤。

6.4 按下 「使用 Passkey 登入」 Button

關鍵 API 整理

API 說明
SignInManager.MakePasskeyCreationOptionsAsync(user) 產生 WebAuthn 註冊選項 JSON（出題），並查詢 DB 填入 excludeCredentials
SignInManager.PerformPasskeyAttestationAsync(json) 驗證前端回傳的 attestation（驗題），回傳 PasskeyAttestationResult
UserManager.AddOrUpdatePasskeyAsync(user, passkey) 將 Passkey 公鑰等資料寫入 AspNetUserPasskeys 資料表
SignInManager.MakePasskeyRequestOptionsAsync(user?) 產生 WebAuthn 登入選項 JSON（出題），null 表示不指定使用者
SignInManager.PasskeySignInAsync(json) 驗證 assertion 並自動 Sign In，回傳 SignInResult
UserManager.GetPasskeysAsync(user) 查詢使用者所有已註冊的 Passkey 清單（IList<UserPasskeyInfo>）
UserManager.RemovePasskeyAsync(user, credentialId) 從 DB 刪除指定 Passkey

常見問題

Q：只刪除 Server 端的 Passkey 資料就夠了嗎？

不完全夠。Passkey 是雙邊資料：

  • Server 端：公鑰、credentialId（你刪除的部分）
  • 使用者裝置端：私鑰（存在 Keychain、密碼管理器等）

刪除 Server 端後，這把 Passkey 無法再登入你的網站，但裝置上仍有殘留憑證（orphan credential）。建議 UI 上提示使用者到裝置端（瀏覽器設定 / 系統密碼管理器）一併刪除。

Q：同一把 Passkey 刪掉後可以重新註冊嗎？

可以。刪除 Server 端資料後，MakePasskeyCreationOptionsAsync 產生的 options 不會再帶舊的 excludeCredentials，瀏覽器呼叫 navigator.credentials.create() 就不會被擋，可正常重新註冊。

Q：MakePasskeyCreationOptionsAsync 會查資料庫嗎？

會。它在產生選項時，會查詢 AspNetUserPasskeys 資料表取得該使用者既有的 Passkey，並填入 excludeCredentials，目的是讓瀏覽器/認證器避免在同一裝置上建立重複的 credential，防止重複綁定。

Q：JavaScript 可以直接刪除裝置上的 Passkey 嗎？

不能。WebAuthn API 提供 create 與 get，但不提供網站主動刪除認證器內憑證的能力。這是設計上的安全考量，避免任意網站偷偷移除使用者的憑證。

小結

.NET 10 將 Passkey 支援內建進 ASP.NET Core Identity，大幅降低了無密碼認證的實作門檻。整個流程的核心可以用一句話概括：

MakePasskey*OptionsAsync 是「出題」，PerformPasskeyAttestation / PasskeySignIn 是「驗題」。

只要掌握這個觀念，搭配 WebAuthn API 的 navigator.credentials.create() 與 navigator.credentials.get()，就能在 Razor Pages 應用程式中快速實現現代化的無密碼登入體驗。

參考資料

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

大家好，我是亂馬客 Rainmaker，目前任職於叡揚資訊，大家也都叫我 RM 。 平常負責開發公司各產品線的加值、共用的軟體，例如 Azure, OpenAI, Chatbot, Database ... 同時 Support 公司各種技術及資安黑箱(AppScan)、白箱(Checkmarx)等問題的解決。 Blog中的內容也是個人的看法， 如果有需要討論的地方， 可以留言，或是 mail 給我 :) rainmaker_ho@gss.com.tw