HCS.Passwordless.WebAuthn 2.1.0

HCS.Passwordless.WebAuthn

WebAuthn / FIDO2 passkey add-on for HCS.Passwordless. Enables hardware-backed biometric or security-key authentication for Umbraco members using the browser's Credential Management API.

Requirements

• Umbraco 17.3.5 or later ([17.3.5, 18.0.0))
• A browser that supports WebAuthn (all modern browsers)
• HCS.Passwordless.Core is pulled in automatically as a transitive dependency

Installation

dotnet add package HCS.Passwordless.WebAuthn

Setup

1. Register (Program.cs)

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddPasswordlessWebAuthn()
    .Build();

2. Configure (appsettings.json)

{
  "HCS": {
    "Authentication": {
      "WebAuthn": {
        "Enabled": true,
        "RpName": "My Site",
        "Origins": [ "https://example.com" ]
      }
    }
  }
}

Important: Origins must exactly match the origin of the site as seen by the browser, including scheme and port.

3. Add passkey UI partials

@* Sign-in *@
@await Html.PartialAsync("Passwordless/PasskeySignInButton")

@* On a member profile/settings page: *@
@await Html.PartialAsync("Passwordless/PasskeyRegisterButton")
@await Html.PartialAsync("Passwordless/PasskeyCredentialList")

Configuration Options

HCS:Authentication:WebAuthn

Endpoints

Multi-Domain Support

WebAuthn ties credentials to an RP ID (typically the root domain, e.g. example.com). When you need the same passkey to work across multiple origins (e.g. https://example.com and https://login.example.com), browsers require that the RP ID's domain publishes a Related Origins document.

This package automatically serves that document at GET /.well-known/webauthn. The document is populated from HCS:Authentication:WebAuthn:Origins and follows the format defined by the W3C WebAuthn Related Origins spec.

Example configuration

{
  "HCS": {
    "Authentication": {
      "WebAuthn": {
        "RpId": "example.com",
        "Origins": [
          "https://example.com",
          "https://login.example.com",
          "https://app.example.com"
        ]
      }
    }
  }
}

// GET https://example.com/.well-known/webauthn
{
  "origins": [
    "https://example.com",
    "https://login.example.com",
    "https://app.example.com"
  ]
}

The endpoint returns 404 when Enabled is false or Origins is empty.

Database Migration

The package adds a MemberCredential table to the Umbraco database via Umbraco's migration system. This runs automatically on startup.

Security Notes

• Challenge state is stored in distributed cache and is single-use.
• Counter regression (a credential reporting a lower sign-count than previously recorded) triggers a PasskeyCounterRegressionNotification so the site can alert the member of a potential cloned authenticator.
• WebAuthn requires HTTPS in production. localhost is allowed for development.

Replacing Services