fido2-net-lib

Passkeys - FIDO2 .NET Library (WebAuthn)

A fully working and battle tested library for passkeys (FIDO2 and WebAuthn) on .NET Releases & Change log

Bitwarden Passwordless API

The quickest way to get started with FIDO2 and WebAuthn is with the Bitwarden Passwordless API. It's free up to 10k users and a faster way to start using passkeys on your website or mobile app.

Bitwarden Passwordless.dev supports .NET Framework as well as the latest .net 8+.

Get started with passwordless.dev

Purpose

Our purpose is to enable passwordless sign in for all .NET apps (asp, core, native).

To provide a developer friendly and well tested .NET FIDO2 Server / WebAuthn relying party library for the easy validation of registration (attestation) and authentication (assertion) of FIDO2 / WebAuthn credentials, in order to increase the adoption of the technology, ultimately defeating phishing attacks.

This project is part of the .NET foundation

.NET 10 Passkeys vs this library?

Wondering if you should use what's in .NET 10 or this library? I've worked together with Microsoft on their passkey implementation and how it relates to this library, so I can share some perspective that may be aid in your decision:

• The passkey support announced Microsoft in .NET 10 is only available as part of ASP.NET Identity.
• Fido2-net-lib is a more capable implementation, and Microsoft recommends you to use this (or any other 3p library) if you want to use more advanced features like attestation. They built a plugin interface so you can combine this library with theirs.
• Since the passkey specification is evolving, I think using this library will give you access to new parts of the standard faster than using ASP.NET Identity.

When picking Microsoft asp.net identity is a good idea:

• You're using ASP.NET Identity and need passkeys.
• You don't want to use attestation or newer passkey features

When picking this library is a good idea:

• You don't want to be tied to using ASP.NET Identity
• You're building a SPA and doing auth without asp.net identity
• You want to use modern passkey features
• You want to use attestation (Could combine this library with the asp.net identity version)

I'm happy that Microsoft is finally joining the passkey train, but this library is probably still what you want to use unless you're running the vanilla asp.net Identity-stack. At least for the time beeing.

Installation

Requirements: .NET 8.0 or later

dotnet add package Fido2

To use the ASP.NET Core helpers:

dotnet add package Fido2.AspNet

For Blazor WebAssembly support:

dotnet add package Fido2.BlazorWebAssembly

⚠️ Breaking Changes: If upgrading from v3.x, see the Upgrade Guide for migration instructions.

Demo

• Library website: https://fido2.andersaberg.com
• Code examples

What is FIDO2?

The passwordless web is here. FIDO2 / WebAuthn is a modern, stable and open authentication standard, supported by browsers and many large tech companies such as Microsoft, Google etc. The main driver is to allow a user to login without passwords, creating passwordless flows or strong MFA for user signup/login on websites. The standard is not limited to web applications with support coming to native apps. The technology builds on public/private keys, allowing authentication to happen without sharing a secret between the user & website. This brings many benefits, such as easier and safer logins and makes phishing attempts extremely hard.

Read more:

• Why it's exciting
• Medium
• FIDO Alliance
• Yubico
• WebAuthn.Guide from Duo Security
• WebAuthn.io
• WebAuthn Awesome

Supported features

• ✅ Attestation API & verification (Register and verify credentials/authenticators)
• ✅ Assertion API & verification (Authenticate users)
• ✅ 100% pass rate in conformance testing (results)
• ✅ FIDO2 security keys aka roaming authenticators (spec), like SoloKeys Solo, Yubico YubiKey, and Feitian BioPass FIDO2)
• ✅ Device embedded authenticators aka platform authenticators (spec), like Android Key and TPM)
• ✅ Backwards compatibility with FIDO U2F authenticators (spec)
• ✅ Windows Hello
• ✅ Face ID and Touch ID for the Web (aka "Apple Hello")
• ✅ All currently referenced cryptographic algorithms for FIDO2 Server (spec)
• ✅ All current attestation formats: "packed", "tpm", "android-key", "android-safetynet", "fido-u2f", "apple", "apple-appattest", and "none" (spec)
• ✅ FIDO2 Server attestation validation via FIDO Metadata Service V3 (spec)
• ✅ WebAuthn extensions (spec) including PRF, Large Blob, Credential Protection
• ✅ Blazor WebAssembly support for client-side applications
• ✅ Examples & demos (ASP.NET Core and Blazor WebAssembly)
• ✅ Intellisense documentation

Configuration

Only some options are mentioned here, see the Configuration class for all options

• fido2:MDSCacheDirPath - App Secret / environment variable that sets the cache path for the MDS. Defaults to "current user's temporary folder"/fido2mdscache. Optional when using the default MetadataService provider.

Quick Start

1. Configure Services (ASP.NET Core)

services.AddFido2(options =>
{
    options.ServerDomain = "example.com";
    options.ServerName = "Example App";
    options.Origins = new HashSet<string> { "https://example.com" };
});

2. Inject IFido2 Service

public class AuthController : Controller
{
    private readonly IFido2 _fido2;

    public AuthController(IFido2 fido2)
    {
        _fido2 = fido2;
    }
}

Examples

• ASP.NET Core Demo - Complete implementation with registration and authentication
• Demo Controller - Main demo API endpoints for registration and authentication
• Blazor WebAssembly Demo - Client-side Blazor example
• Conformance Test Controller - Conformance testing endpoints

For integration patterns, see:

• Active Directory Store information
• Example credential store

Create Attestation Options

To add FIDO2 credentials to an existing user account, start by creating options for the client.

…

Register Credentials

When the client returns a response, verify and register the credentials.

…

Create Assertion Options

For user authentication, create assertion options based on registered credentials.

…

Verify the Assertion Response

When the client returns a response, verify it and accept the login.

…

Nuget package

https://www.nuget.org/packages/Fido2/ and https://www.nuget.org/packages/Fido2.Models/

Contributing

See Contributing for information about contributing to the project.

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.

For security and penetration testing, please see our Vulnerability Disclosure Program

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

.NET Foundation

This project is supported by the .NET Foundation.