ASP.NET Core 10如何实现Passkey登录？无密码身份认证开发教程

什么是Passkey？

Passkey是一种基于WebAuthn和FIDO2标准的无密码身份认证技术，它使用公钥密码学代替传统的用户名和密码。用户首次注册Passkey时，设备会生成一对公钥和私钥，私钥安全地保存在设备、系统安全模块或者密码管理器中，而网站服务器只需要保存公钥。

登录时，服务器生成一次性的Challenge，浏览器调用Web Authentication API与设备身份验证器进行交互。用户可以通过Windows Hello、Touch ID、Face ID、设备PIN或者安全密钥完成验证，设备使用私钥对Challenge进行签名，服务器再使用保存的公钥验证签名。

这种方式最大的优势是私钥不会上传到服务器，而且Passkey与网站域名绑定，因此相比传统密码登录具有更好的抗钓鱼能力。微软已经在ASP.NET Core 10的Identity中提供Passkey支持，可以直接用于已有Identity账户，也可以用于创建完全无密码的账户。

ASP.NET Core 10为什么适合实现Passkey？

过去在ASP.NET Core项目中实现WebAuthn，通常需要引入第三方WebAuthn库，并自行处理Challenge、Credential、Assertion以及公钥验证等流程。ASP.NET Core 10则进一步将Passkey能力集成到ASP.NET Core Identity中。项目可以通过SignInManager和UserManager处理Passkey注册、验证和登录，减少自行实现WebAuthn协议带来的安全风险。

创建项目时可以直接使用.NET 10：

dotnet new blazor -n PasskeyDemo -f net10.0
cd PasskeyDemo
dotnet run

ASP.NET Core 10的Blazor Web App模板已经提供Passkey相关的管理和登录功能，因此如果使用Blazor Web App，可以直接基于模板进行二次开发。

如果是传统MVC、Razor Pages或者自定义Identity界面，也可以直接使用ASP.NET Core Identity提供的Passkey API实现自己的登录页面。

配置ASP.NET Core Identity Passkey

首先确保项目使用ASP.NET Core Identity，然后配置IdentityPasskeyOptions：

using Microsoft.AspNetCore.Identity;

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.ServerDomain = "example.com";
    options.AuthenticatorTimeout = TimeSpan.FromMinutes(3);
    options.ChallengeSize = 32;
    options.UserVerificationRequirement = "required";
    options.ResidentKeyRequirement = "preferred";
});

其中ServerDomain非常重要，它代表Passkey所属的Relying Party ID，也就是Passkey绑定的网站域名。

生产环境建议明确设置ServerDomain，不要完全依赖HTTP请求中的Host头自动推断域名。微软文档特别提醒，如果服务器没有正确验证Host头，可能产生凭据范围攻击风险。

UserVerificationRequirement = "required"则要求身份验证器进行用户验证，例如指纹、面容、Windows Hello PIN等。

Passkey注册流程

Passkey注册并不是简单地在数据库中保存一串密码，而是一个完整的WebAuthn注册流程。

用户点击“添加Passkey”后，浏览器首先向服务器请求创建凭据所需要的参数。服务器生成随机Challenge并返回给浏览器。

浏览器随后调用：

const credential = await navigator.credentials.create({
    publicKey: options
});

此时浏览器会调用操作系统的身份验证器，用户可能看到Windows Hello、Touch ID或者其他Passkey确认界面。

身份验证器生成新的公钥和私钥，并将公钥以及Credential相关信息返回给浏览器。私钥不会发送到ASP.NET Core服务器。

服务器收到Credential后，可以通过ASP.NET Core Identity进行验证。Identity会检查Credential类型、Challenge、Origin以及Authenticator数据等内容，验证通过后再将Passkey信息保存到用户账户。

ASP.NET Core Identity提供了AddOrUpdatePasskeyAsync等API处理Passkey的保存工作，因此开发者不需要从零实现WebAuthn协议。

Passkey无密码登录怎么实现？

用户完成Passkey注册以后，登录过程就不再需要输入密码。

客户端首先向服务器请求登录Challenge：

const response = await fetch(
    "/Account/PasskeyRequestOptions",
    {
        method: "POST"
    }
);

const json = await response.json();

const options =
    PublicKeyCredential.parseRequestOptionsFromJSON(json);

const credential =
    await navigator.credentials.get({
        publicKey: options
    });

浏览器将请求交给设备身份验证器，用户通过指纹、面容、PIN等方式确认身份。

随后浏览器将签名后的Credential发送回ASP.NET Core服务器。

ASP.NET Core Identity可以直接使用：

var result =
    await signInManager.PasskeySignInAsync(credentialJson);

if (result.Succeeded)
{
    return Results.Ok();
}

return Results.Unauthorized();

PasskeySignInAsync会验证签名、Challenge、用户存在状态以及Authenticator相关数据。验证成功后，ASP.NET Core Identity会建立正常的身份认证Session/Cookie，后续访问[Authorize]保护的页面就与普通Identity登录基本一致。

支持无用户名登录

Passkey还有一个非常实用的能力，就是允许用户不输入用户名。

服务器可以调用：

var options =
    await signInManager.MakePasskeyRequestOptionsAsync(null);

如果没有指定用户，生成的请求参数可以用于条件UI或者用户名无关的Passkey认证。

现代浏览器可以配合Passkey自动填充功能，让用户点击用户名输入框后直接看到可用Passkey，然后通过设备验证完成登录。

这种模式可以把传统的“输入用户名 → 输入密码 → 登录”简化成“选择Passkey → 指纹/面容/PIN验证 → 登录”。对于会员网站、SaaS平台以及后台管理系统来说，这种体验尤其适合移动端用户。

ASP.NET Core 10 Passkey开发注意事项

Passkey虽然能够降低密码泄露和钓鱼风险，但开发过程中仍然需要特别关注域名、HTTPS和Challenge安全。

首先，生产环境应该使用HTTPS，并确保Passkey注册和登录使用稳定的正式域名。ServerDomain一旦配置错误，可能导致已经注册的Passkey无法正常登录。

其次，不要自行实现Challenge生成、签名验证等核心WebAuthn逻辑。ASP.NET Core Identity已经提供了相关能力，直接使用官方Identity API能够降低实现错误。

另外还需要限制每个账户可以注册的Passkey数量以及Passkey名称长度，避免恶意请求造成数据库资源消耗。微软当前的Blazor Web App模板已经对这类场景提供了相应限制。

如果企业环境需要检查具体的身份验证器，例如限制某些设备或者验证Authenticator Attestation，则可以进一步实现自定义Attestation验证。但这属于高级安全场景，大多数普通网站并不需要自行维护验证器证书信任体系。

ASP.NET Core 10 Passkey适合哪些项目？

对于新开发的ASP.NET Core 10应用，如果已经使用ASP.NET Core Identity，那么Passkey值得作为主要登录方式之一。

传统密码可以继续作为兼容方案，让老用户逐步注册Passkey。新用户则可以直接创建Passkey，实现真正的Passwordless账户。

对于企业后台、SaaS系统、电商平台、开发者工具以及需要较高账户安全性的Web应用，可以考虑采用 Passkey + Identity Cookie 的架构。

总体来看，ASP.NET Core 10最大的变化并不是单纯增加了一个登录API，而是将WebAuthn/FIDO2能力进一步融入ASP.NET Core Identity。开发者不再需要从零实现复杂的Credential验证流程，就可以构建基于设备生物识别、PIN和安全密钥的现代化无密码登录系统。