[Pre7] Passkeys coverage

[guardrex]

@mikekistler @MackinnonBuck ... You can place the article content into an issue comment here, and I'll get it situated for Preview 7. I'll place an entry for this into the upcoming Pre7 What's New tracking issue.

Migration notes thus far are on the Pre6 issue for the subject at #35712 (comment).

References ...

• [What's New Pre7 docs issue cross-link will be placed here]
• PU PR: [10.0.1xx-preview6] Add passkeys to ASP.NET Core Identity dotnet#1237

Coverage plan ...

• Reference coverage: New article for the Security & Identity> Authentication > ASP.NET Core Identity node
• Migration coverage: Perhaps, migration coverage will only go into the What's New Pre7 coverage because formal migration coverage typically only goes up in the RC time frame due to high framework churn. However, we could go ahead and get the ball rolling with formal migration coverage given how late in the cycle we'll be.

[MackinnonBuck]

Here is a draft of some docs content. Note that there are still some gaps I need to fill:

• The "Implement passkeys in existing applications" section currently refers to a minimal passkeys sample in the aspnetcore repo, but we shouldn't refer to samples in the repo from docs. This section needs to be replaced with one that does a step-by-step walkthrough of integrating passkeys with an existing Blazor Web App.
  • This section is also probably a good place to explain the core passkey APIs in detail.
• In the "Administrative controls" section, we should show an example of how to detect and revoke compromised credentials.

Passkeys in ASP.NET Core Identity

Passkeys provide a modern, phishing-resistant authentication method based on the WebAuthn and FIDO2 standards. They are a secure alternative to passwords, using public key cryptography and device-based authentication.

What are passkeys?

Passkeys are a replacement for passwords that use cryptographic key pairs. The private key is stored securely on the user's device (such as in a hardware security module, platform authenticator like Windows Hello or Touch ID, or a password manager), while the public key is stored by the web application. During authentication, the user proves possession of the private key without it ever leaving their device.

Key benefits of passkeys include:

• Phishing resistance: Passkeys are bound to specific websites and cannot be used on fake sites
• No shared secrets: The server only stores public keys, eliminating the risk of password database breaches
• User convenience: Simple biometric or PIN verification replaces complex password requirements
• Cross-device synchronization: Many passkey providers sync credentials across a user's devices

Passkeys in ASP.NET Core Identity

ASP.NET Core Identity includes built-in support for passkey registration and authentication. This implementation:

• Integrates seamlessly with Identity infrastructure
• Supports the most common WebAuthn scenarios for user authentication
• Works with the Blazor Web App project template out of the box

Important

The passkey implementation in ASP.NET Core Identity is deliberately scoped to authentication scenarios. It is not intended as a general-purpose WebAuthn library. Developers requiring full WebAuthn functionality should consider community libraries that provide comprehensive protocol support.

Supported scenarios

The ASP.NET Core Identity passkey implementation supports these primary scenarios:

1. Adding passkeys to existing accounts: Users with password-based accounts can register passkeys as an additional authentication method
2. Passwordless account creation: Users can create accounts without a password by registering a passkey on account creation
3. Passwordless sign-in: Users can authenticate using only their passkey without entering a password

Limitations

The current implementation has the following limitations:

• Scoped to ASP.NET Core Identity: The APIs are designed specifically for Identity authentication scenarios
• No default attestation validation: The implementation doesn't validate attestation statements by default
• Template support: Only the Blazor Web App template includes passkey support out of the box
• No built-in 2FA support: Passkeys are treated as a primary authentication factor, not as a second factor

Get started with passkeys

The easiest way to get started with passkeys is to create a new Blazor Web App with individual authentication.

Prerequisites

• .NET 10 SDK or later
• A modern web browser that supports WebAuthn
• A device with a platform authenticator (Windows Hello, Touch ID, Face ID) or a security key

Create a new Blazor Web App with passkeys

Create a new Blazor Web App with individual authentication using the .NET CLI:

dotnet new blazor -au Individual -n MyPasskeyApp
cd MyPasskeyApp

This creates a Blazor Web App with:

• ASP.NET Core Identity configured for user authentication
• Entity Framework Core with SQLite for data storage
• Passkey registration and authentication endpoints
• UI components for managing passkeys

Note

Currently, only the Blazor Web App project template includes built-in passkey support.

Run the application

Run the application:

dotnet run

Navigate to the port shown in the console output.

Register a passkey

To test passkey functionality:

1. Register a new account or sign in with an existing account
2. Navigate to Manage your account (click on the username in the navigation menu)
3. Select Passkeys from the navigation menu
4. Click Add a new passkey
5. Follow your browser's prompts to create a passkey using your device's authenticator

Sign in with a passkey

Once you have registered a passkey:

1. Sign out of the application
2. On the login page, enter your email address
3. Click Log in with a passkey
4. Follow your browser's prompts to authenticate with your passkey

Configure passkeys

ASP.NET Core Identity provides various options to configure passkey behavior through the IdentityPasskeyOptions class:

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    // Explicitly set the Relying Party ID (domain)
    options.ServerDomain = "example.com";
    
    // Configure authenticator timeout
    options.AuthenticatorTimeout = TimeSpan.FromMinutes(3);
    
    // Configure challenge size
    options.ChallengeSize = 64;
});

For a complete list of configuration options, see the IdentityPasskeyOptions API documentation.

Note

The browser defaults mentioned in the API documentation were valid as of August 2025. See the WebAuthn Specification for the most up-to-date defaults.

Custom attestation statement validation

By default, ASP.NET Core Identity doesn't validate attestation statements. This is suitable for most consumer authentication scenarios. If your application requires verification of authenticator properties (for example, in enterprise environments), you can implement custom attestation validation:

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.VerifyAttestationStatement = async (context) =>
    {
        // Custom attestation validation logic
        // Return true if the attestation is valid, false otherwise
        return true;
    };
});

Warning

Attestation validation is complex and requires maintaining trust stores for authenticator certificates. Only implement custom validation if your application requires verification of specific authenticator properties.

Custom origin validation

The default origin validation allows requests from subdomains and disallows cross-origin iframes. To customize this behavior:

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.ValidateOrigin = async (context) =>
    {
        // Custom origin validation logic
        // Access the origin via context.Origin
        // Access the HTTP context via context.HttpContext
        return true; // Return true if the origin is valid
    };
});

Implement passkeys in existing applications

To add passkey support to an existing ASP.NET Core application that uses Identity:

Prerequisites

• An existing ASP.NET Core application using Identity
• Entity Framework Core (for database migrations)
• .NET 10 SDK or later

Update the database schema

First, update your Identity schema version IdentitySchemaVersions.Version3 to include passkey support:

builder.Services.AddIdentityCore<ApplicationUser>(options =>
    {
        options.Stores.SchemaVersion = IdentitySchemaVersions.Version3;
    })
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddSignInManager()
    .AddDefaultTokenProviders();

Then, generate a migration to add the passkey tables:

dotnet ef migrations add AddPasskeySupport
dotnet ef database update

Add client-side implementation

The Blazor Web App template includes the necessary JavaScript and Razor components for passkey functionality. For other project types, you'll need to implement:

• JavaScript code to interact with the WebAuthn API
• UI components for passkey registration and authentication
• Endpoints for passkey operations

Refer to the IdentitySample.PasskeyUI sample application for a complete implementation example.

Security considerations

When implementing passkeys in ASP.NET Core Identity, ensure your application meets the following security requirements:

Host header validation

The implementation infers the Relying Party ID from the host header when ServerDomain is not explicitly configured. Your hosting environment must validate host headers to prevent credential scoping attacks.

Mitigation: Either explicitly configure ServerDomain in IdentityPasskeyOptions or ensure your hosting environment (Kestrel, IIS, reverse proxy) validates host headers. See your hosting platform's documentation for configuration details.

Subdomain security

ASP.NET Core's passkeys implementation handles subdomain security through the ServerDomain configuration option. When ServerDomain is not explicitly specified, the implementation uses the host header to determine the domain. This means that the page on which the passkey was registered will control the domain for that credential.

For example:

• If a passkey is registered on app.example.com, it will also work on *.app.example.com
• If registered on example.com, it will also work on *.example.com
• The browser enforces that passkeys can only be used on the domain (and subdomains) where they were registered

Requirement: Applications requiring strict domain control should explicitly set ServerDomain in their configuration rather than relying on the host header. Do not serve untrusted content on any subdomain within the ServerDomain scope. If you cannot guarantee this, implement custom origin validation to restrict passkey usage to specific origins.

HTTPS requirement

All passkey operations require HTTPS. The implementation stores authentication data in encrypted and signed cookies that could be intercepted over unencrypted connections.

Requirement: Always use HTTPS in production. Configure HSTS to prevent protocol downgrade attacks.

Account recovery

Account recovery is primarily a concern for applications that allow passkeys as the only authentication mechanism. The default Blazor Web App project template already requires users to set up a backup authentication method (password or external provider) when creating an account, so account recovery is handled through these existing mechanisms.

Recommendation:
For applications implementing passkey-only authentication, consider:

• Recovery codes generated during account creation
• Email-based recovery flows
• Mandatory registration of multiple passkeys
• Monitoring the IsBackedUp flag on UserPasskeyInfo to prompt users to add additional credentials

Administrative controls

When an authenticator model is discovered to have security vulnerabilities, you may need to revoke affected credentials. The implementation stores the complete attestation object with each credential, including the AAGUID (Authenticator Attestation GUID).

Implementation: Extract AAGUIDs from stored attestation objects, compare against known-compromised models, and revoke affected credentials. Note that AAGUID reliability depends on whether your application validates attestation statements.

Resource limits

To prevent database exhaustion attacks, applications should enforce limits on passkey registration, such as:

• Maximum number of passkeys per user account
• Maximum length for passkey display names

The Blazor Web App template enforces these limits by default.