Passkeys¶
Who supports sign-in with passkeys, in the who-passkey module (org.jwcarman.who.passkey). It is built on Spring Security's WebAuthn support, with Spring's filters moved under who.base-path (default /who): POST /who/passkey/sign-in/options and POST /who/passkey/sign-in to sign in, and POST /who/me/passkeys/options and POST /who/me/passkeys to register one. Who adds GET /who/me/passkeys and DELETE /who/me/passkeys/{credentialId} for a person's own list, supplies the hooks Spring leaves fixed, and stores passkeys in its own tables.
A passkey is the only factor. Who requires user verification (a PIN, a fingerprint or a face scan) and a discoverable (resident) credential, so the user does not type a name.
Add who-passkey to turn passkeys on; an application without the jar has none of this.
Turn it on¶
Add the dependency (its version comes from who's BOM):
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-passkey</artifactId>
</dependency>
Then set the relying party id: the host of your app. Startup fails until it is set; the message
also says how to turn passkeys off without removing the jar: who.passkey.enabled=false.
who:
passkey:
rp-id: app.example.com
The defaults are rp-name who and allowed-origins https://<rp-id>:
who:
passkey:
rp-id: app.example.com
rp-name: Example App
allowed-origins:
- https://app.example.com
Each allowed-origins entry is an origin: a scheme (http or https), a host and an optional port, with no path or trailing slash, as the browser reports it. A blank rp-name, or an entry such as app.example.com or https://app.example.com/signin, fails startup with a message that names the property.
For local development, the default origin https://<rp-id> does not match the page. Set the origin explicitly, with rp-id localhost (browsers allow WebAuthn over plain http on localhost only):
who:
passkey:
rp-id: localhost
allowed-origins:
- http://localhost:8080
Use one rp-id per app host. Never use a registrable domain that other apps share (for example example.com for several apps under it). Every app's passkeys would then appear in every other app's picker.
Passkey storage is PostgreSQL only, because the repositories use ON CONFLICT. It needs PostgreSQL 14+. See Database Setup.
See the Configuration Reference for all five properties.
Wire the chain¶
With no SecurityFilterChain of your own there is nothing to wire: who's default chain mounts
passkeys and opens /who/passkey/sign-in/options and /who/passkey/sign-in to signed-out requests
(see Getting Started). List your own sign-in page in
who.security.public-paths.
Your own chain¶
In a chain of your own, WhoSecurity.all() mounts every sign-in method at once (see Getting
Started). Or use the same WhoWebSecurity.passwordless() as
Email Links: apply it to the chain that serves your browser app and permit the
sign-in endpoints:
@Bean
SecurityFilterChain browserChain(HttpSecurity http) throws Exception {
http.with(WhoWebSecurity.passwordless(), Customizer.withDefaults());
http.authorizeHttpRequests(a -> a
.requestMatchers("/who/passkey/sign-in/options", "/who/passkey/sign-in", "/signin").permitAll()
.anyRequest().authenticated());
return http.build();
}
passwordless() adds Spring Security's passkey filters to the chain itself, at who's paths, without Spring's webAuthn() (which fixes the paths) and without a registration page. Do not also call webAuthn() on the chain. It also makes the session id change at sign-in and rotates the CSRF token, which Spring's WebAuthn filter does not do by default. Everything passwordless() does for email links applies here too (see Email Links).
The endpoints under /who/me/passkeys need a signed-in browser session, but anyRequest().authenticated() does not protect all of them. Spring runs the filter for POST /who/me/passkeys/options before the authorization filter, so your rules never see it. Who's PasskeyRegistrationGuardFilter covers it, and POST /who/me/passkeys, with a 401 for a caller who is signed out (NotSignedInException) or signed in too long ago (ReauthenticationRequiredException), and a 403 for an API key or bearer token on the request, even beside a session cookie; your application formats them (see Errors). Each endpoint is protected like this:
POST /who/me/passkeys/options: by who's guard only. YourauthorizeHttpRequestsrules do not apply.POST /who/me/passkeys: by your rules (leave it behindauthenticated()) and by who's guard.GET /who/me/passkeysandDELETE /who/me/passkeys/{credentialId}: by who's own filter, which runs before your rules and answers a signed-out caller with401itself. Spring's own delete endpoint is turned off.
Do not put these paths under permitAll().
If your app defines its own PublicKeyCredentialUserEntityRepository or UserCredentialRepository bean for another chain that calls webAuthn(), that chain falls back to in-memory storage, because Spring finds two beans of one type. Who's chain is not affected: who hands its own repositories to its passkey filters directly.
The browser flow¶
The TypeScript client does all of this, the encoding included: who.passkeys.signIn, and who.me.passkeys.register, who.me.passkeys.list and who.me.passkeys.remove.
All requests are JSON. Every POST needs the CSRF token in the X-XSRF-TOKEN header, as described in Email Links. The examples use the same post helper:
function xsrf() {
return document.cookie.split('; ')
.find(c => c.startsWith('XSRF-TOKEN='))?.split('=')[1];
}
async function post(path, body) {
return fetch(path, {
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-XSRF-TOKEN': decodeURIComponent(xsrf() ?? '')
},
body: body === undefined ? undefined : JSON.stringify(body)
});
}
// Spring's options are JSON with base64url strings. The browser wants bytes.
const b64u = {
decode: s => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0)),
encode: b => btoa(String.fromCharCode(...new Uint8Array(b)))
.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
};
Register a passkey¶
The user must be signed in, and the sign-in must be within who.security.recent-sign-in (10 minutes by default), the window every way of adding a credential shares. The usual path is: sign in by email link, then add a passkey.
Passkeys cannot be an app's only way in. Registering needs a recent who session, and in who only Email Links create the first one: passkey sign-in needs a passkey that is already registered. An app that turns on passkeys alone has no way for a new user to register one. Turn on email links as well, or create the first session yourself with your own PasswordlessLoginMethod.
async function registerPasskey(label) {
const optionsRes = await post('/who/me/passkeys/options');
if (!optionsRes.ok) throw new Error('options ' + optionsRes.status);
const options = await optionsRes.json();
options.challenge = b64u.decode(options.challenge);
options.user.id = b64u.decode(options.user.id);
options.excludeCredentials = (options.excludeCredentials ?? [])
.map(c => ({ ...c, id: b64u.decode(c.id) }));
const credential = await navigator.credentials.create({ publicKey: options });
const res = await post('/who/me/passkeys', {
publicKey: {
credential: {
id: credential.id,
rawId: b64u.encode(credential.rawId),
type: credential.type,
response: {
attestationObject: b64u.encode(credential.response.attestationObject),
clientDataJSON: b64u.encode(credential.response.clientDataJSON),
transports: credential.response.getTransports?.() ?? []
},
clientExtensionResults: credential.getClientExtensionResults(),
authenticatorAttachment: credential.authenticatorAttachment
},
label
}
});
return res.status; // 200 with {"success":true}
}
The label is required: 1 to 64 characters, not blank, with no line breaks or other control characters, or the registration answers 400 invalid-passkey-registration. It is the name the user sees in your passkey list and in the "passkey added" email, such as "Laptop".
The answers. An error's body is whatever your application writes for its exception (see Errors):
| Status | Body | Meaning |
|---|---|---|
200 |
{"success":true} |
The passkey is registered. |
401 |
yours | NotSignedInException: the caller is signed out. |
401 |
yours | ReauthenticationRequiredException: the sign-in is older than who.security.recent-sign-in. Send the user through an email link again, then retry. |
403 |
yours | An API key or a bearer token on the request: only a browser session registers a passkey. |
400 |
yours | InvalidPasskeyRegistrationException: the response failed verification: a wrong origin or challenge, or a device that did not verify the user. Also when the options in the session were requested by a different identity than the one signed in now (someone else signed in on the same browser before the registration finished). |
400 |
empty | Spring's own answer to a malformed registration body, or to a request with no options in the session (post to /who/me/passkeys/options first). |
Sign in with a passkey¶
Sign-in needs no session. The user does not type anything: the browser shows the passkeys it holds for the rp-id.
async function signInWithPasskey() {
const optionsRes = await post('/who/passkey/sign-in/options');
const options = await optionsRes.json();
options.challenge = b64u.decode(options.challenge);
options.allowCredentials = (options.allowCredentials ?? [])
.map(c => ({ ...c, id: b64u.decode(c.id) }));
const credential = await navigator.credentials.get({ publicKey: options });
const res = await post('/who/passkey/sign-in', {
id: credential.id,
rawId: b64u.encode(credential.rawId),
type: credential.type,
response: {
authenticatorData: b64u.encode(credential.response.authenticatorData),
clientDataJSON: b64u.encode(credential.response.clientDataJSON),
signature: b64u.encode(credential.response.signature),
userHandle: credential.response.userHandle
? b64u.encode(credential.response.userHandle) : null
},
clientExtensionResults: credential.getClientExtensionResults(),
authenticatorAttachment: credential.authenticatorAttachment
});
if (res.ok) {
const { identityId } = await res.json();
}
}
On success the answer is 200 with {"identityId": "..."} and a session cookie. Every failure is a SignInFailedException (401 unless your application maps it otherwise; see Errors): an unknown passkey, a bad signature, a missing user verification, or an identity that is not active.
The session id changes at sign-in and the CSRF token rotates. With csrf.spa() the page must read the XSRF-TOKEN cookie again after signing in and after signing out, before the next POST. A page that cached the old value gets 403.
await signInWithPasskey();
const csrf = decodeURIComponent(xsrf()); // read it again, not before sign-in
GET /who/me and POST /who/logout work as for email links.
Listing and revoking passkeys¶
A person lists and removes their own passkeys through who's endpoints, on every browser chain:
| Request | Answer |
|---|---|
GET /who/me/passkeys |
200, [{credentialId, label, createdAt, lastUsedAt}], oldest first |
DELETE /who/me/passkeys/{credentialId} |
204. The passkey is deleted, with who's identity link, so it cannot sign in again |
Both are for a browser session only (403 otherwise), and removing needs a recent sign-in (401
ReauthenticationRequiredException). A passkey that is someone else's, or does not exist, is 404.
Removing the identity's last way to sign in is 409 (last-credential). Removing the passkey a
session signed in with ends that session. See Your Account for the full rules.
From your own code, inject PasskeyService:
List<PasskeySummary> passkeys = passkeyService.list(identityId);
passkeyService.revoke(passkeys.get(0).id());
list returns the identity's passkeys, oldest first, as PasskeySummary(id, credentialId, label, created, lastUsed). id is who's credential UUID, which revoke takes. credentialId is the WebAuthn credential id in base64url, which DELETE /who/me/passkeys/{credentialId} takes. revoke(UUID) deletes the credential record and unlinks it from the identity. It does nothing if no passkey has that id. ownerOf(credentialId) answers the identity a credential id belongs to.
PasskeyService.revoke checks neither ownership nor the last-credential rule. It is an application or admin API: check in your own code that the passkey belongs to the caller, and remove it through LastCredentialGuard when the person must keep a way in.
The name on the passkey picker¶
The browser shows a name next to each passkey. Who does not assume an identity has an email address, so it picks, in order:
- the address of the email credential the current session signed in with. Registering needs a recent sign-in, usually by email link, so this is the address the user just proved they own;
- otherwise, the address of the identity's oldest email credential;
- otherwise, the identity id.
Without who-email-link the name is always the identity id.
Who picks the name again each time registration starts (POST /who/me/passkeys/options) and updates its own record, so an identity that gains or changes an address gets the new name on its next passkey. The browser stores the name on the user's device when the passkey is created, and devices keep the old name for passkeys they already hold, until browsers support updating it. Sign-in is not affected, because it maps by user handle. The user handle is 64 random bytes. It is not derived from the identity or the address.
The address lands in the user's synced credential manager (for example iCloud Keychain or a password manager). That is the user's own device, and a trade-off to accept.
The "passkey added" email¶
When a passkey is registered, who emails the owner, so that someone who did not add a passkey notices. The email goes to the identity's oldest address, through the same email setup as sign-in links, so it is sent whenever email-link sign-in is on:
spring:
mail:
host: smtp.example.com
who:
email:
from: no-reply@example.com
email-link:
link-base-url: https://app.example.com/signin
code-secret: <at least 32 random characters>
passkey:
rp-id: app.example.com
Its template is passkey-added, and {{email.label}} is the passkey's name; its subject is
who.email.passkey-added.subject. Without who-email-link, or with it turned off, no email is
sent and who logs a warning once at startup, at WARN, saying why. An identity with no email
address gets no email. A failure to send is logged, never thrown, so it never fails the
registration.
To notify some other way, register a PasskeyAddedNotifier bean:
@Bean
PasskeyAddedNotifier passkeyAddedNotifier(MyMailer mailer) {
return (identityId, label) -> mailer.passkeyAdded(identityId, label);
}
It runs only after a successful registration. An exception it throws is logged and does not fail the registration.
Trust and recovery¶
Registering a passkey needs a recent sign-in, so the first factor (usually the mailbox) stays the root of trust. A lost device does not lock a user out if the mailbox still works. To remove a lost passkey, the user calls DELETE /who/me/passkeys/{credentialId} from another signed-in browser, or an administrator calls PasskeyService.revoke.
Database¶
The module adds who_passkey_user and who_passkey_credential. See Database Setup.