passkey

Overview ¶

Package passkey implements the server (Relying Party) side of WebAuthn for discoverable credentials (passkeys).

Although WebAuthn supports a range of purposes and policies, this package is designed for password-less authentication with discoverable credentials: i.e. logging into an account with a passkey.

The package is built around passkey records: opaque strings, handled like prefixed password hashes, that encode everything the server needs to store about a credential.

$webauthn$v=1$transports=hybrid+internal$<base64 authenticator data>

Records are immutable: they are produced by RelyingParty.Register and never change afterwards. Mutable authenticator state (like backup state) is not tracked; per-login values are reported by RelyingParty.Login as LoginResult.BackedUp and LoginResult.UserVerified.

Storage model ¶

Applications are expected to store passkey records in a table keyed only by user ID, for example

CREATE TABLE passkeys (
    user_id TEXT NOT NULL,
    record  TEXT NOT NULL,
    FOREIGN KEY(user_id) REFERENCES users(passkeys_user_id)
);
CREATE INDEX passkeys_user_id ON passkeys(user_id);

with no index on credential IDs and no uniqueness constraints. No other columns are needed by this package; applications may add their own (e.g. a nickname, creation time, or last-used time for a passkey management UI). Lookups always resolve the user first (from the session during registration, from Response.UnauthenticatedUserID or the session during login) and then pass all of the user's records to RelyingParty.Login, which selects the right one.

(Because credentials are never resolved by credential ID across accounts, a credential ID registered maliciously into one account can never affect authentication for another, and the cross-account uniqueness check recommended by the WebAuthn specification becomes unnecessary.)

User IDs ¶

User IDs are opaque strings, at most 64 bytes. They are stored inside the authenticator and returned in every login, so they MUST NOT contain personal information such as usernames or email addresses, and they cannot be changed later. Generate them with crypto/rand.Text at account creation and map them to accounts in the database. Do not reuse internal account identifiers.

For example

ALTER TABLE users ADD COLUMN passkeys_user_id TEXT;
CREATE UNIQUE INDEX users_passkeys_user_id ON users(passkeys_user_id);

Challenges ¶

RelyingParty.NewLogin and RelyingParty.NewLoginWithOptions return an opaque request value that must be presented back to RelyingParty.Login.

The application must:

• store the request, either server-side (in memory or in a KV store, keyed by RequestID) or client-side in a cookie;
• if possible, delete it after use, so that each request is accepted at most once (client-side storage can't enforce this: an attacker who captured both request and response can replay the login until the request expires); and
• protect its integrity if stored client-side (e.g. with an authenticated cookie), as a forged request could defeat challenge freshness.

Requests expire Options.Timeout after creation (which RequestCreation returns), and the application can use the same window as the lifetime of stored requests (e.g. as the KV TTL or cookie Max-Age).

Request values don't need to be kept secret but must be protected from tampering.

(Registration has no request value: with attestation "none", no part of a registration response is signed by a party the server trusts, so a registration challenge can't prove freshness and is not verified. Applications tie a registration to the signed-in session, and must protect the registration endpoint with their usual session and cross-site request forgery defenses, like any other authenticated endpoint.)

WebAuthn interface details ¶

Registration options request a discoverable credential (residentKey: "required") with user verification "preferred", attestation "none", and the credProps extension.

The requested algorithms are, in order of preference, ML-DSA-44, ES256, and RS256.

The user name is also sent as the displayName, which credential providers ignore in practice.

Register fails if the response reports (via the credProps extension) that the created credential is not discoverable. Absence of the extension output is accepted: some clients (notably Safari) never report it, and enforcement of discoverability rests on the client's residentKey: "required" obligation.

Register does not require the user presence flag, so that conditional (automatic) passkey creation flows, in which the user does not interact with a prompt, are supported.

Register verifies that the client data is well-formed JSON with type "webauthn.create", the expected origin, and crossOrigin absent or false; that the authenticator data carries the hash of the RP ID; and, unless Options.OptionalUserVerification is set, that user verification is set up on the authenticator (see the User verification section below). The challenge is not verified; see the Challenges section above.

Login options request user verification "required", or "preferred" if Options.OptionalUserVerification is set. RelyingParty.NewLogin sends an empty allowCredentials list; LoginOptions.AllowCredentials populates it with the user's credentials instead.

Credential descriptors, in excludeCredentials at registration and in allowCredentials at login, carry the transports recorded at registration, which help the client reach the right authenticator.

Both registration and login options carry Options.Timeout as the ceremony timeout hint.

Login verifies that the signature is valid, with the matched record's public key, over the authenticator data and the hash of the client data; that the client data is well-formed JSON with type "webauthn.get", the request's challenge, the expected origin, and crossOrigin absent or false; that the authenticator data carries the hash of the RP ID (as does the matched record) and has the user presence flag set; that the request has not expired; and, unless Options.OptionalUserVerification is set, that user verification was performed and can be relied upon (see the User verification section below).

The signature counter is not checked (it is zero for the major passkey providers).

User verification ¶

The UV flag of a login assertion is relied upon (and LoginResult.UserVerified is set) only if the matched record has the UV or the BE flag, i.e. if user verification was performed at registration or the credential is a synced passkey. Otherwise, it suggests the credential was stored on an external authenticator without UV set up, and an attacker that were to steal it could have set up their own PIN to enable UV. UserVerificationAvailable reports this property of a record.

By default, login options request user verification "required", and Login fails unless LoginResult.UserVerified would be true: with ErrUserVerificationUnavailable if the record has neither the UV nor the BE flag (likely a security key without a PIN), and with a generic error otherwise. Registration options request "preferred", to allow conditional (automatic) passkey creation, but Register fails with ErrUserVerificationUnavailable if the response has neither the UV nor the BE flag, as the credential could never log in.

If Options.OptionalUserVerification is set, login options request "preferred", Register and Login accept responses regardless of the flags, and LoginResult.UserVerified retains the same semantics.

package main

import (
	"crypto/rand"
	"errors"
	"io"
	"log"
	"net/http"
	"sync"
	"time"

	"filippo.io/passkey"
)

func main() {
	const page = `<!DOCTYPE html>
<meta charset="utf-8">
<title>passkey example</title>
<button id="login">Sign in</button>
<hr>
<input id="username" placeholder="username" autocomplete="username">
<button id="register">Sign up with a passkey</button>
<hr>
<p id="out"></p>
<script type="module">
addEventListener("unhandledrejection", e => out.textContent = e.reason)
const post = async (url, body) => {
const res = await fetch(url, { method: "POST", body })
if (!res.ok) throw new Error(await res.text())
return res
}
register.onclick = async () => {
const options = await (await post("/register", username.value)).json()
const credential = await navigator.credentials.create({
	publicKey: PublicKeyCredential.parseCreationOptionsFromJSON(options),
})
await post("/add-passkey", JSON.stringify(credential))
out.textContent = "Account created."
}
const loginOptions = () => post("/login/options").then(res => res.json())
let nextLogin = loginOptions()
login.onclick = async () => {
const options = await nextLogin
nextLogin = loginOptions() // requests are single-use
const credential = await navigator.credentials.get({
	publicKey: PublicKeyCredential.parseRequestOptionsFromJSON(options),
})
const res = await post("/login", JSON.stringify(credential))
out.textContent = "Signed in as " + await res.text() + "."
}
</script>
`

	rp, err := passkey.NewRelyingParty(&passkey.Options{
		// The RP ID is the site's registrable domain, so passkeys keep
		// working if sign-in later moves to a different origin.
		RPID:   "example.com",
		Origin: "https://login.example.com",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Stand-ins for the application's session and database.
	type user struct {
		username      string
		passkeyUserID string
		passkeys      []string
	}
	var sessionUser func(*http.Request) (*user, error)
	var sessionSignIn func(rw http.ResponseWriter, username string)
	var userByUserID func(passkeyUserID string) (*user, error)
	var registerNewUser func(username, passkeyUserID string) (*user, error)
	var requests sync.Map // request ID -> pending login request

	mux := http.NewServeMux()

	mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
		io.WriteString(w, page)
	})

	mux.HandleFunc("POST /register", func(w http.ResponseWriter, r *http.Request) {
		username, _ := io.ReadAll(r.Body)
		// A user ID must be opaque and unique, so we generate a random one.
		u, err := registerNewUser(string(username), rand.Text())
		if err != nil {
			http.Error(w, "user already exists", http.StatusConflict)
			return
		}
		sessionSignIn(w, u.username)
		optionsJSON, err := rp.NewRegistration(
			passkey.User{ID: u.passkeyUserID, Name: u.username}, nil)
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		w.Write(optionsJSON)
	})

	mux.HandleFunc("POST /add-passkey", func(w http.ResponseWriter, r *http.Request) {
		u, err := sessionUser(r)
		if err != nil {
			http.Error(w, "not signed in", http.StatusUnauthorized)
			return
		}
		responseJSON, _ := io.ReadAll(r.Body)
		record, err := rp.Register(responseJSON)
		if err != nil {
			switch {
			case errors.Is(err, passkey.ErrUserVerificationUnavailable):
				http.Error(w, "this passkey can't verify it's you: set up a PIN "+
					"on your security key, or use a different authenticator",
					http.StatusBadRequest)
			default:
				http.Error(w, "registration failed", http.StatusBadRequest)
			}
			return
		}
		u.passkeys = append(u.passkeys, record)
	})

	mux.HandleFunc("POST /login/options", func(w http.ResponseWriter, r *http.Request) {
		request, optionsJSON, err := rp.NewLogin()
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		requests.Store(passkey.RequestID(request), request)
		w.Write(optionsJSON)
	})

	mux.HandleFunc("POST /login", func(w http.ResponseWriter, r *http.Request) {
		responseJSON, _ := io.ReadAll(r.Body)
		response, err := passkey.ParseResponse(responseJSON)
		if err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		// Each request is deleted after use, so it can't be replayed.
		request, ok := requests.LoadAndDelete(response.RequestID())
		// The asserted user ID is attacker-controlled until Login succeeds,
		// and is only used to look up the candidate passkey records.
		u, err := userByUserID(response.UnauthenticatedUserID())
		if !ok || err != nil {
			http.Error(w, "login failed", http.StatusUnauthorized)
			return
		}
		if _, err := rp.Login(response, request.([]byte), u.passkeys); err != nil {
			switch {
			case errors.Is(err, passkey.ErrUnknownCredential):
				http.Error(w, "this passkey was removed from the account",
					http.StatusUnauthorized)
			case errors.Is(err, passkey.ErrRequestExpired):
				http.Error(w, "took too long, please try again", http.StatusUnauthorized)
			default:
				http.Error(w, "login failed", http.StatusUnauthorized)
			}
			return
		}
		sessionSignIn(w, u.username)
		io.WriteString(w, u.username)
	})

	// Evict expired pending requests to reclaim memory;
	// a production KV store would rely on a TTL instead.
	go func() {
		for range time.Tick(time.Minute) {
			requests.Range(func(key, value any) bool {
				created := passkey.RequestCreation(value.([]byte))
				if time.Since(created) > 5*time.Minute {
					requests.Delete(key)
				}
				return true
			})
		}
	}()

	// CSRF protection is critical to avoid POST /add-passkey
	// being abused to add a passkey to another user's account.
	handler := http.NewCrossOriginProtection().Handler(mux)

	log.Fatal(http.ListenAndServe("localhost:8080", handler))
}

Output: