Passkeys in ASP.NET Core Identity (.NET 10): Build a Passwordless-First Web App with WebAuthn

PasskeyFirstIdentity/
├── src/PasskeyFirstIdentity.Web/
│   ├── Components/Account/Pages/
│   ├── Components/Account/Shared/PasskeySubmit.razor.js
│   ├── Identity/ApplicationDbContext.cs
│   ├── Identity/IdentityComponentsEndpointRouteBuilderExtensions.cs
│   ├── Migrations/
│   └── Program.cs
├── tests/PasskeyFirstIdentity.Tests/
├── Directory.Packages.props
└── PasskeyFirstIdentity.sln

REGISTRATION (attestation)
Browser -> Server: request creation options
Server -> Browser: challenge + RP + user options
Browser -> Authenticator: navigator.credentials.create()
Authenticator -> Browser: new public-key credential
Browser -> Server: credential JSON
Server: verify + store public key

AUTHENTICATION (assertion)
Browser -> Server: request assertion options
Server -> Browser: challenge + RP options
Browser -> Authenticator: navigator.credentials.get()
Authenticator -> Browser: signed assertion
Browser -> Server: assertion JSON
Server: verify signature + sign user in

dotnet --info

dotnet dev-certs https --trust

dotnet new blazor -au Individual -o PasskeyFirstIdentity
cd PasskeyFirstIdentity
dotnet watch

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

dotnet ef migrations add AddPasskeySupport
dotnet ef database update

builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
    options.ServerDomain =
        builder.Configuration["Passkeys:ServerDomain"];
    options.AuthenticatorTimeout = TimeSpan.FromMinutes(3);
    options.ChallengeSize = 32;
    options.UserVerificationRequirement = "preferred";
    options.ResidentKeyRequirement = "required";
});

{
  "Passkeys": {
    "ServerDomain": "localhost"
  }
}

accountGroup.MapPost("/PasskeyCreationOptions", async (
    ClaimsPrincipal principal,
    UserManager<ApplicationUser> userManager,
    SignInManager<ApplicationUser> signInManager) =>
{
    ApplicationUser user = await userManager.GetUserAsync(principal)
        ?? throw new InvalidOperationException("Authenticated user required.");

    string userId = await userManager.GetUserIdAsync(user);
    string userName = await userManager.GetUserNameAsync(user)
        ?? throw new InvalidOperationException("Username required.");

    var userEntity = new PasskeyUserEntity
    {
        Id = userId,
        Name = userName,
        DisplayName = userName
    };

    string optionsJson =
        await signInManager.MakePasskeyCreationOptionsAsync(userEntity);

    return TypedResults.Content(optionsJson, "application/json");
})
.RequireAuthorization()
.ValidateAntiforgery();

accountGroup.MapPost("/RegisterPasskey", async (
    HttpRequest request,
    ClaimsPrincipal principal,
    UserManager<ApplicationUser> userManager,
    SignInManager<ApplicationUser> signInManager) =>
{
    ApplicationUser user = await userManager.GetUserAsync(principal)
        ?? throw new InvalidOperationException("Authenticated user required.");

    using var reader = new StreamReader(request.Body);
    string credentialJson = await reader.ReadToEndAsync();

    PasskeyAttestationResult attestation =
        await signInManager.PerformPasskeyAttestationAsync(credentialJson);

    if (!attestation.Succeeded)
    {
        return Results.BadRequest(new
        {
            error = attestation.Failure?.Message ?? "Passkey verification failed."
        });
    }

    IdentityResult stored = await userManager.AddOrUpdatePasskeyAsync(
        user,
        attestation.Passkey);

    return stored.Succeeded
        ? Results.NoContent()
        : Results.ValidationProblem(stored.Errors.ToDictionary(
            error => error.Code,
            error => new[] { error.Description }));
})
.RequireAuthorization()
.ValidateAntiforgery();

export async function createPasskey(antiforgeryToken) {
  const headers = {
    "Content-Type": "application/json",
    "RequestVerificationToken": antiforgeryToken
  };

  const optionsResponse = await fetch(
    "/Account/PasskeyCreationOptions",
    { method: "POST", headers });

  if (!optionsResponse.ok) {
    throw new Error("Could not create passkey options.");
  }

  const optionsJson = await optionsResponse.json();
  const publicKey =
    PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);

  const credential = await navigator.credentials.create({ publicKey });
  if (!credential) {
    throw new Error("The authenticator returned no credential.");
  }

  const registerResponse = await fetch("/Account/RegisterPasskey", {
    method: "POST",
    headers,
    body: JSON.stringify(credential)
  });

  if (!registerResponse.ok) {
    throw new Error(await registerResponse.text());
  }
}

accountGroup.MapPost("/PasskeyRequestOptions", async (
    string? username,
    UserManager<ApplicationUser> userManager,
    SignInManager<ApplicationUser> signInManager) =>
{
    ApplicationUser? user = string.IsNullOrWhiteSpace(username)
        ? null
        : await userManager.FindByNameAsync(username);

    string optionsJson =
        await signInManager.MakePasskeyRequestOptionsAsync(user);

    return TypedResults.Content(optionsJson, "application/json");
})
.ValidateAntiforgery();

accountGroup.MapPost("/PasskeySignIn", async (
    HttpRequest request,
    SignInManager<ApplicationUser> signInManager) =>
{
    using var reader = new StreamReader(request.Body);
    string credentialJson = await reader.ReadToEndAsync();

    SignInResult result =
        await signInManager.PasskeySignInAsync(credentialJson);

    return result.Succeeded
        ? Results.NoContent()
        : Results.Unauthorized();
})
.ValidateAntiforgery();

export async function signInWithPasskey(
  username,
  antiforgeryToken,
  conditional = false) {

  const headers = {
    "Content-Type": "application/json",
    "RequestVerificationToken": antiforgeryToken
  };

  const query = username
    ? `?username=${encodeURIComponent(username)}`
    : "";

  const optionsResponse = await fetch(
    `/Account/PasskeyRequestOptions${query}`,
    { method: "POST", headers });

  const optionsJson = await optionsResponse.json();
  const publicKey =
    PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);

  const credential = await navigator.credentials.get({
    publicKey,
    mediation: conditional ? "conditional" : "optional"
  });

  if (!credential) return false;

  const response = await fetch("/Account/PasskeySignIn", {
    method: "POST",
    headers,
    body: JSON.stringify(credential)
  });

  return response.ok;
}

ApplicationUser user = await userManager.GetUserAsync(User)
    ?? throw new InvalidOperationException("Authenticated user required.");

IList<UserPasskeyInfo> passkeys =
    await userManager.GetPasskeysAsync(user);

var view = passkeys.Select(passkey => new
{
    passkey.Name,
    passkey.CredentialId,
    passkey.IsBackupEligible,
    passkey.IsBackedUp
});

UserPasskeyInfo? passkey =
    await userManager.FindPasskeyAsync(user, credentialId);

if (passkey is null)
{
    return Results.NotFound();
}

passkey.Name = friendlyName.Trim();
IdentityResult result =
    await userManager.AddOrUpdatePasskeyAsync(user, passkey);

IList<UserPasskeyInfo> passkeys =
    await userManager.GetPasskeysAsync(user);

bool hasVerifiedRecoveryEmail =
    await userManager.IsEmailConfirmedAsync(user);

if (passkeys.Count == 0 || !hasVerifiedRecoveryEmail)
{
    return Results.Problem(
        statusCode: StatusCodes.Status409Conflict,
        detail: "Add a passkey and verify a recovery email before removing the password.");
}

IdentityResult result = await userManager.RemovePasswordAsync(user);

static bool CanDeletePasskey(
    int currentPasskeyCount,
    bool hasPassword,
    bool hasExternalLogin,
    bool hasVerifiedRecoveryCodes)
{
    if (currentPasskeyCount > 1)
    {
        return true;
    }

    return hasPassword || hasExternalLogin || hasVerifiedRecoveryCodes;
}

WebApplication app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();

app.MapControllers();
app.MapRazorPages();
app.MapPasskeyIdentityEndpoints();

using Microsoft.AspNetCore.Antiforgery;

internal static class AntiforgeryEndpointExtensions
{
    public static TBuilder ValidateAntiforgery<TBuilder>(this TBuilder builder)
        where TBuilder : IEndpointConventionBuilder =>
        builder.AddEndpointFilter(async (context, next) =>
        {
            var antiforgery = context.HttpContext.RequestServices
                .GetRequiredService<IAntiforgery>();
            try
            {
                await antiforgery.ValidateRequestAsync(context.HttpContext);
            }
            catch (AntiforgeryValidationException)
            {
                return Results.BadRequest("Antiforgery validation failed.");
            }
            return await next(context);
        });
}

Registration
- enroll a discoverable credential
- duplicate registration behavior
- invalid challenge and origin
- maximum credential count

Authentication
- username-first assertion
- username-less conditional UI
- invalid signature
- stale or replayed assertion
- cancellation and timeout

Recovery
- delete one of multiple passkeys
- block deletion of the final factor
- recover with code or verified email
- notify user after credential changes

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("passkeys", limiter =>
    {
        limiter.PermitLimit = 10;
        limiter.Window = TimeSpan.FromMinutes(1);
        limiter.QueueLimit = 0;
    });
});

accountGroup.RequireRateLimiting("passkeys");