linuxchata/fido2

# 概述 此仓库提供了 WebAuthn 标准的服务端实现，为 Web 应用程序启用安全的无密码和多因素认证 (MFA)。它支持关键的 WebAuthn 操作——凭证注册和认证——确保符合 [WebAuthn Level 2 规范](https://www.w3.org/TR/webauthn-2/)（Web Authentication: An API for accessing Public Key Credentials Level 2）。 [](https://github.com/linuxchata/fido2/actions/workflows/build.yml) [](https://sonarcloud.io/summary/new_code?id=linuxchata_fido2) [](https://sonarcloud.io/summary/new_code?id=linuxchata_fido2) [](https://github.com/linuxchata/fido2/actions/workflows/build_nuget_packages.yml) [](https://github.com/linuxchata/fido2/blob/main/LICENSE) [](https://hub.docker.com/r/linuxchata/shark-fido2-sample) ## 支持的功能 - 用于公钥凭证注册的 **Attestation 流程** - 用于公钥凭证验证的 **Assertion 流程** - **支持的 Attestation 声明格式**: - Packed - TPM - Android Key - Android SafetyNet - FIDO U2F - None - Apple Anonymous - 支持的加密算法：ES256, EdDSA, ES384, ES512, PS256, PS384, PS512, ES256K, RS256, RS384, RS512, RS1 - WebAuthn 扩展，包括凭证属性 和大对象存储。 - **内置存储提供商**: - Microsoft SQL Server - PostgreSQL - Amazon DynamoDB - 内存存储 - **FIDO Metadata Service** - **全面测试**，使用 [FIDO Conformance Tool](https://fidoalliance.org/certification/conformance/) – 所有测试用例均已成功通过 - 代码示例和演示网站 # 包 | 包名 | 状态 | |-|-| | Shark.Fido2.Core | [](https://www.nuget.org/packages/Shark.Fido2.Core/) | | Shark.Fido2.DynamoDB | [](https://www.nuget.org/packages/Shark.Fido2.DynamoDB/) | | Shark.Fido2.InMemory | [](https://www.nuget.org/packages/Shark.Fido2.InMemory/) | | Shark.Fido2.Models | [](https://www.nuget.org/packages/Shark.Fido2.Models/) | | Shark.Fido2.PostgreSQL | [](https://www.nuget.org/packages/Shark.Fido2.PostgreSql/) | | Shark.Fido2.SqlServer | [](https://www.nuget.org/packages/Shark.Fido2.SqlServer/) | # ASP.NET Core Identity 中的 Passkeys ASP.NET Core Identity 从 .NET 10 开始内置对 Passkeys 的支持。 | 能力 | Shark WebAuthn | ASP.NET Core Identity | |---|---|---| | 库范围 | 通用 WebAuthn 库，不依赖于 ASP.NET Core Identity | 与 ASP.NET Core Identity 集成；非通用 WebAuthn 库，主要范围限于 Identity 用例 | | .NET 版本 | 目标 .NET 8（兼容 .NET 8/9/10） | 需要 .NET 10 SDK | | 开发者体验 | 以 NuGet 包形式提供 | 内置于 .NET 10，无需安装包 | | Attestation 支持 | 全面支持所有 Attestation 格式 | :x: 无默认 Attestation 验证 | | 加密算法 | 支持所有 WebAuthn 定义的加密算法 | 支持除 EdDSA 外的所有 WebAuthn 定义的加密算法。[来源](https://github.com/dotnet/aspnetcore/pull/62112) | | 持久化数据存储 | 为 Microsoft SQL Server、PostgreSQL、Amazon DynamoDB 和内存存储提供内置提供商 | 使用 ASP.NET Core Identity 配置的存储提供商 | | FIDO Metadata Service | 与 FIDO Metadata Service 内置集成 | :x: 无与 FIDO Metadata Service 的内置集成 | | FIDO Conformance Tool | 已测试 | 已测试 | **在以下情况下选择 Shark WebAuthn：** - 您需要完全符合标准的 WebAuthn 支持。 - 您希望灵活选择持久化数据存储。 - 您需要满足企业或监管合规要求。 - 您需要通过 FIDO Metadata Service 进行认证器验证。 **在以下情况下选择 ASP.NET Core Identity 中的 Passkeys：** - 您的应用程序已经在使用 ASP.NET Core Identity。 - 您只需要基本的基于 Passkey 的无密码认证。 - 您愿意在必要时实现额外的 Attestation 验证。 # 用法 以下示例演示了如何在您的应用程序中实现无密码认证。有关完整的参考和更多详细信息，请参阅[完整文档](https://shark-fido2.com/Documentation)。 ## 服务端 API (ASP.NET Core Controllers) 下面的 C# 示例代码专为 ASP.NET Core 控制器设计。 ### 依赖项注册 注册凭证存储（内存或其他）和核心依赖项。 ``` builder.Services.AddFido2(builder.Configuration); builder.Services.AddFido2InMemoryStore(); ``` ### 服务端配置 可以使用以下配置选项自定义服务端。您可以在 `appsettings.json` 文件中设置这些选项。 **核心配置** | 选项 | 默认值 | 描述 | |-|-|-| | `RelyingPartyId` | | 有效的域名字符串，用于标识代表其执行注册或认证仪式的依赖方。这是 WebAuthn 协议中的关键参数。它定义了凭证有效的安全范围。因此，仔细选择至关重要，因为不正确或过于宽泛的值可能导致意外的凭证重用或安全漏洞。 | | `RelyingPartyIdName` | | 依赖方可读的标识符，仅供显示。 | | `Origins` | | 发起请求的依赖方的完全限定来源列表，由浏览器传递给认证器。 | | `Timeout` | `60000` | 依赖方愿意等待调用完成的时间（以毫秒为单位）。 | | `AlgorithmsSet` | `Extended` | 支持的加密算法集。可能的值为 `Required`、`Recommended` 或 `Extended`。有关加密算法的更多信息，请访问 [fidoalliance.org](https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-server-v2.0-rd-20180702.html#other) 站点。 | | `AllowNoneAttestation` | `true` | 指示在依赖方策略下是否接受 None Attestation 类型的值。当认证器没有任何可用的 Attestation 信息时，使用 [None Attestation](https://www.w3.org/TR/webauthn-2/#none)。 | | `AllowSelfAttestation` | `true` | 指示在依赖方策略下是否接受 Self Attestation 类型的值。当认证器没有专用的 Attestation 密钥对或供应商颁发的证书时，使用 [Self Attestation](https://www.w3.org/TR/webauthn-2/#self-attestation)。 | | `EnableTrustedExecutionEnvironmentOnly` | `true` | 指示依赖方是否仅信任在可信执行环境中安全生成和存储的密钥的值（与 Android Key Attestation 相关）。 | | `EnableMetadataService` | `true` | 指示依赖方是否使用 FIDO Metadata Service 来验证 Attestation 对象的值。来自 FIDO Metadata Service 的元数据存储在内存缓存中，并保持有效直到 `nextUpdate` 时间戳，该时间戳从元数据 BLOB 接收，指示可能提供新元数据 BLOB 的最晚时间。 | | `EnableStrictAuthenticatorVerification` | `false` | 指示依赖方是否需要严格验证认证器的值。如果启用，缺少认证器的元数据将导致 Attestation 失败。如果禁用 FIDO Metadata Service，则忽略此参数。 | **FIDO Metadata Service 配置** | 选项 | 默认值 | 描述 | |-|-|-| | `MetadataBlobLocation` | `https://mds3.fidoalliance.org/` | 关于 FIDO 认证器的集中可信信息源的位置。 | | `RootCertificateLocationUrl` | `https://secure.globalsign.com/cacert/root-r3.crt` | Metadata Service BLOB 的 GlobalSign Root R3 证书的位置。 | | `MaximumTokenSizeInBytes` | `8388608` | 将处理的最大 Token 大小（以字节为单位）。此配置与 Metadata Service BLOB 大小有关。 | 示例 `appsettings.json` 文件：[appsettings.Production.json](https://github.com/linuxchata/fido2/blob/main/src/Shark.Fido2.Sample/appsettings.Production.json) ### Attestation (注册) Attestation 控制器 1. 通过检索创建选项开始注册。 ``` [HttpPost("options")] public async Task Options(ServerPublicKeyCredentialCreationOptionsRequest request, CancellationToken cancellationToken) { var createOptions = await _attestation.BeginRegistration(request.Map(), cancellationToken); var response = createOptions.Map(); HttpContext.Session.SetString("CreateOptions", JsonSerializer.Serialize(createOptions)); return Ok(response); } ``` 2. 完成注册以创建凭证。 ``` [HttpPost("result")] public async Task Result(ServerPublicKeyCredentialAttestation request, CancellationToken cancellationToken) { var createOptionsString = HttpContext.Session.GetString("CreateOptions"); var createOptions = JsonSerializer.Deserialize(createOptionsString!); await _attestation.CompleteRegistration(request.Map(), createOptions!, cancellationToken); return Ok(ServerResponse.Create()); } ``` ### Assertion (认证) Assertion 控制器 1. 通过检索请求选项开始认证。 ``` [HttpPost("options")] public async Task Options(ServerPublicKeyCredentialGetOptionsRequest request, CancellationToken cancellationToken) { var requestOptions = await _assertion.BeginAuthentication(request.Map(), cancellationToken); var response = requestOptions.Map(); HttpContext.Session.SetString("RequestOptions", JsonSerializer.Serialize(requestOptions)); return Ok(response); } ``` 2. 完成认证以验证凭证。 ``` [HttpPost("result")] public async Task Result(ServerPublicKeyCredentialAssertion request, CancellationToken cancellationToken) { var requestOptionsString = HttpContext.Session.GetString("RequestOptions"); var requestOptions = JsonSerializer.Deserialize(requestOptionsString!); await _assertion.CompleteAuthentication(request.Map(), requestOptions!, cancellationToken); return Ok(ServerResponse.Create()); } ``` ## 客户端集成 要完成实现，您必须包含与浏览器的 Web Authentication API 交互的 JavaScript 代码。此 API 管理客户端认证过程。以下是一个示例实现： - [attestation.js](https://github.com/linuxchata/fido2/blob/main/src/Shark.Fido2.Sample/wwwroot/js/attestation.js) 使用 Web Authentication API (`navigator.credentials.create`) 处理注册过程。 - [assertion.js](https://github.com/linuxchata/fido2/blob/main/src/Shark.Fido2.Sample/wwwroot/js/assertion.js) 使用 Web Authentication API (`navigator.credentials.get`) 处理认证过程。 此 JavaScript 代码将浏览器的 Web Authentication API 绑定到上述 ASP.NET Core 控制器提供的服务端 REST API 端点。有关 Web Authentication API 的更多信息，请访问 MDN Web Docs 站点的 [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) 页面。 # Docker 示例依赖方可以使用 Docker（Linux 容器）运行。确保您的机器上已安装并运行 [Docker](https://docs.docker.com/get-docker/)。 **拉取并运行镜像** ``` docker pull linuxchata/shark-fido2-sample:latest ``` ``` docker run -d -e ASPNETCORE_ENVIRONMENT=Development -p 8080:8080 linuxchata/shark-fido2-sample:latest ``` 应用程序将可通过 `http://localhost:8080` 访问。 # FIDO 一致性测试 使用官方 [FIDO Conformance Tool](https://fidoalliance.org/certification/conformance/) 成功通过所有测试用例，确认完全符合 WebAuthn Level 2 和 FIDO2 规范。 # 许可证 本项目采用 [BSD 3-Clause 许可证](LICENSE) 授权。 # 贡献 有关为项目做贡献的信息，请参阅[贡献](https://github.com/linuxchata/fido2/blob/main/CONTRIBUTING.md)。 # 规范 **简介** - [Web Authentication 简介](https://webauthn.guide/) - [Web Authentication 凭证和登录演示](https://webauthn.me/) - [FIDO Alliance](https://fidoalliance.org/) **Web Authentication** - [Web Authentication: An API for accessing Public Key Credentials Level 2](https://www.w3.org/TR/webauthn-2/) - [Server Requirements and Transport Binding Profile](https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-server-v2.0-rd-20180702.html) - [Web Authentication: An API for accessing Public Key Credentials Level 3](https://www.w3.org/TR/webauthn-3/) - [PublicKeyCredential](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential) **FIDO Metadata Service** - [FIDO Metadata Service](https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html) - [FIDO Metadata Statement](https://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html) **工具** - [FIDO Alliance - Certification Conformance Test Tools](https://github.com/fido-alliance/conformance-test-tools-resources/tree/main)

标签：Android SafetyNet, ASP.NET, CVE, DynamoDB, EdDSA, ES256, FIDO2, FIDO U2F, JSONLines, MFA, OpenID Connect, PostgreSQL, RS256, SQL Server, SSO, TPM, WebAuthn, Windows Hello, YubiKey, 公钥基础设施, 凭据填充, 加密算法, 多人体追踪, 多因素认证, 库, 应急响应, 数字签名, 无密码认证, 服务器端, 测试用例, 生物识别, 网络安全, 认证器, 请求拦截, 防网络钓鱼, 隐私保护, 零信任