C# .NET Blazor Server library for WebAuthn passkeys. It wraps the browser WebAuthn API and
FIDO2 verification so you can focus on storage and your sign-in flow.
Targets net10.0. Your app must run on .NET 10 or you must retarget the library.
Designed for Blazor Server. Verification is server-side and not meant for Blazor WebAssembly.
WebAuthn requires HTTPS or localhost. HTTP on public hosts will not work.
The rpId (PasskeyOptions.Domain) must match the effective domain of the origin.
PasskeyProvider returns null/false on failure and suppresses exceptions by design.
Wrap calls and log state if you need diagnostics.
Signature counters are not persisted; clone detection is not implemented.
Advanced WebAuthn options (user verification, resident key, attestation preference,
authenticator attachment, timeout, extensions, hints) are not exposed yet.
All WebAuthn calls must happen after the component is interactive. In Blazor Server,
call from OnAfterRenderAsync or UI event handlers, not during prerender.
using ChatAIze.Passkeys;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorComponents().AddInteractiveServerComponents();
builder.Services.AddPasskeyProvider(options =>
{
options.Domain = "example.com"; // rpId, no scheme
options.AppName = "Example"; // display name shown to users
options.Origins = new List<string>
{
"https://example.com"
};
});
var app = builder.Build();
app.UseStaticFiles(); // Required for the JS module in _content/ChatAIze.Passkeys
app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
app.Run();
Optional: add @using ChatAIze.Passkeys in _Imports.razor to simplify component code.
The JS module is loaded via dynamic import, so you do not need to add script tags manually.
Notes on options
Domain must be a registrable domain (no scheme, path, or port). Example: example.com.
Origins must include the exact origin (scheme + host + port) of your app.
Example: https://example.com or https://localhost:7238.
If the origin does not match, WebAuthn verification will fail.
Data you must store
For each credential, store:
User handle (Passkey.UserHandle)
Credential ID (Passkey.CredentialId)
Public key (Passkey.PublicKey)
Optional but recommended:
Signature counter (not handled by this library yet)
Friendly name or device label
Creation time and last-used time
A simple schema might look like:
UserId
UserHandle (bytes, <= 64 bytes recommended)
CredentialId (bytes)
PublicKey (bytes)
SignCount (uint, optional)
DisplayName (string, optional)
Store multiple credentials per user to support multiple devices.
Registration flow
This flow is typically done after a user has authenticated with another method.
@inject PasskeyProvider PasskeyProvider
@code {
private async Task RegisterPasskeyAsync()
{
var userId = "user-123"; // stable, opaque identifier
var existingCredentialIds = await credentialStore.GetCredentialIdsAsync(userId);
var passkey = await PasskeyProvider.CreatePasskeyAsync(
userId,
userName: "user@example.com",
displayName: "Example User",
excludeCredentials: existingCredentialIds);
if (passkey is null)
{
// Registration failed or was cancelled
return;
}
await credentialStore.SaveAsync(new StoredCredential
{
UserId = userId,
UserHandle = passkey.UserHandle,
CredentialId = passkey.CredentialId,
PublicKey = passkey.PublicKey!
});
}
}
Why exclude credentials?
Use excludeCredentials to prevent registering the same authenticator more than once.
This helps avoid duplicate credentials when the user retries registration.
User handle best practice
Use a stable, opaque identifier (database ID, GUID, etc). Do not use email addresses
or other user-visible data. Keep the byte length small (<= 64 bytes recommended).
If you expect discoverable credentials, you can let the browser choose:
@inject PasskeyProvider PasskeyProvider
@code {
private async Task SignInAsync()
{
var passkey = await PasskeyProvider.GetPasskeyAsync();
if (passkey is null)
{
return; // cancelled or failed
}
var user = await credentialStore.FindByCredentialIdAsync(passkey.CredentialId);
if (user is null)
{
return; // unknown credential
}
var ok = await PasskeyProvider.VerifyPasskeyAsync(
passkey,
user.UserHandle,
user.PublicKey);
if (!ok)
{
return; // verification failed
}
// Sign in user
}
}
Non-discoverable credentials (security keys)
For security keys, provide allowCredentials:
var allowCredentials = await credentialStore.GetCredentialIdsAsync(userId);
var passkey = await PasskeyProvider.GetPasskeyAsync(allowCredentials: allowCredentials);
if (passkey is null)
{
return;
}
var ok = await PasskeyProvider.VerifyPasskeyAsync(
passkey,
storedUserHandle,
storedPublicKey);
If the browser returns an empty user handle, resolve the user by CredentialId and
use that stored user handle for verification.
Prefer discoverable with fallback to security keys
If you want to prefer discoverable passkeys but still allow security keys for a known user,
use the fallback helper:
var allowCredentials = await credentialStore.GetCredentialIdsAsync(userId);
var passkey = await PasskeyProvider.GetPasskeyPreferDiscoverableAsync(
allowCredentials: allowCredentials);
if (passkey is null)
{
return;
}
var user = await credentialStore.FindByCredentialIdAsync(passkey.CredentialId);
if (user is null)
{
return;
}
var ok = await PasskeyProvider.VerifyPasskeyAsync(passkey, user.UserHandle, user.PublicKey);
Conditional mediation (autofill)
Conditional mediation surfaces passkeys in the browser autofill UI. In Blazor Server,
call it after the component renders and ensure an input with
autocomplete="username webauthn" exists.
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (!firstRender)
{
return;
}
var available = await PasskeyProvider.IsConditionalMediationAvailableAsync();
if (!available)
{
return;
}
var passkey = await PasskeyProvider.GetPasskeyConditionalAsync();
if (passkey is null)
{
return; // user did not pick a credential
}
var user = await credentialStore.FindByCredentialIdAsync(passkey.CredentialId);
if (user is null)
{
return;
}
var ok = await PasskeyProvider.VerifyPasskeyAsync(passkey, user.UserHandle, user.PublicKey);
if (!ok)
{
return;
}
// Sign in user
}
Conditional mediation tips
Trigger it once after render; do not spam the call.
Keep a fallback sign-in button for browsers that do not support it.
In some browsers, the user must focus an input to see the autofill UI.
Overloads accept string or Guid user IDs. userId should be a stable, opaque identifier.
The returned Passkey.PublicKey should be stored for future verification.
Overloads accept string or Guid user IDs and base64 public keys. The public key
must be standard base64 (not base64url).
Passkey
Passkey combines registration data (credential ID/public key) and assertion data
(authenticator response fields). Only UserHandle, CredentialId, and PublicKey
should be persisted; assertion fields are transient.
The library exposes raw byte arrays for credential IDs and public keys.
Passkey.*Base64 helpers use standard base64. If you store base64url, convert accordingly.
When passing allowCredentials or excludeCredentials, supply byte arrays. If you store
values as strings, decode them with Convert.FromBase64String.
Best practices
Use a stable, opaque user handle rather than an email address.
Always verify on the server; never trust client-provided claims.
Prefer discoverable credentials for passwordless UX, and allow security keys via allowCredentials.
Keep rpId and allowed origins consistent across environments.
Use HTTPS in production. WebAuthn will not work on insecure origins.
Store multiple credentials per user to support multiple devices.
Provide a fallback sign-in method for unsupported browsers or user cancellations.
Security considerations
Treat credential IDs and public keys as sensitive metadata. Do not log them in production.
If you do not persist signature counters, you lose clone detection. Consider extending
verification with counters in your own storage layer.
Attestation trust is not configured. If you require strict attestation or metadata
validation, extend the library to integrate a metadata service and attestation checks.
Troubleshooting
NotAllowedError: user cancelled, device not available, or request timed out.
InvalidStateError: credential already exists; use excludeCredentials.
SecurityError: rpId or origin mismatch; check PasskeyOptions.Domain and Origins.
Passkeys Supported = false: JS interop not ready or not running in a browser.
Conditional mediation never returns: call after render and ensure input has
autocomplete="username webauthn".
Preview project
The repository includes a preview app in ChatAIze.Passkeys.Preview that demonstrates:
Registration
Authentication
Conditional mediation
Run it locally and update PasskeyOptions to match your local URLs.