WebAuthn Passwordless
An example WebAuthn application showing how passwordless registration and authentication journeys work.
Includes progressive enhancement for devices that support saving usernames and keys (via resident storage), account management to add additional devices and fallback to magic email login links for devices that don't support (or cancel) WebAuthn.
Includes web frontend (nginx), API (Node/Express), Database (Mongo), and a Database viewer (Mongo Express).
Quick start
Prerequisites: Node and/or Docker should be installed.
The app can either be started using Node or Docker:
Node
npm installnpm start
Missing `libcrypto.so.1.1`?
On some systems (like some versions of Ubuntu) if using Node only, you may encounter the following error:
StdoutInstanceError: Instance failed to start because a library is missing or cannot be opened: "libcrypto.so.1.1"
Which can be resolved by installing libssl1.1:
wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.debDocker
./start.sh
Usage
- http://localhost:3000 to register and login
- Check the console output for the email confirmation links
- In Chrome, open "DevTools > Console > More tools (hamburger menu) > WebAuthn > Enable virtual authenticator environment" to try out different key types
- If Docker is installed check http://localhost:8081 for the user database
- Attempt to login from different devices, desktop vs. mobile
- Reset database via
npm run reset:db(Docker only) - Optionally set the SMTP settings in
apps.envto send email and changeconfig.tsto match your domain and security requirements
Browser support
| OS/Browser | Android | Windows | iOS | macOS | Linux |
|---|---|---|---|---|---|
| Chrome | 🐾🔑 | 🐾📲🔑 | 🛃 | 🐾📲🔑 | 📲🔑 |
| Safari | ⛔ | ⛔ | 🐾🔑 | 🐾📲🔑 | ⛔ |
| Edge | 🐾🔑 | 🐾📲🔑 | 🛃 | 🐾📲🔑 | 🔑 |
| Firefox | 🐾🔑 | 🐾📲🔑 | 🛃 | 🔑 | 🔑 |
| Chromium based* | 📲🔑 | 🛃 | 📲🔑 | 📲🔑 |
Key:
- 🐾 Platform authentication: such biometric login e.g. fingerprint, face unlock or PIN etc.
- 📲 Roaming authentication: such as a mobile phone that can be setup via a QR to send a login confirmation prompt
- 🔑 Security key: such as a YubiKey
- 🛃 Assumed to work, as iOS prevents browser vendors from using their own engine (uses Safari under the hood)
- ⛔ Not available
Notes on browsers tested
See Can I use WebAuthn? for a full/up to date breakdown.
Chrome 108
Successfully registers and logs in, prompting for fingerprint (even if not signed into Chrome). Same for Microsoft Edge.
Safari 16.1
Allows touch ID only if iCloud is signed in, otherwise falls back to mobile QR code or security key.
Firefox 107
On Windows Firefox supports Windows Hello (biometric login). On Android resident keys are not used, but users can still register and login with on device U2F. While on other platforms Firefox only allows security keys to used for registration and login.
* ⤵️ Other Chromium based browsers
Different Chromium based browsers may have different WebAuthn implementation. Some may have full support (such as Brave & Samsung Internet), partial or no support for WebAuthn.
Managing WebAuthn keys
Android
Open "Settings > Passwords and accounts > Google (under Passwords)" tapping each login allows you to edit or delete it.
As a linked security device/phone
On both Android and desktop in Chrome/Chromium based browsers navigate to "Settings > Privacy and security > Phone as a security key/Manage phones" to remove linked devices.
Windows
Chrome/Chromium (108 & later)
"Settings > Auto-fill > Password Manager > Manage passkeys".
Alternative method
Via Windows Terminal
To view WebAuthn keys stored by Windows Hello, from a command prompt, run:
certutil -csp NGC -key
WebAuthn keys have names that look like <sid>/<guid>/FIDO_AUTHENTICATOR//<rpIdHash>_<user id>
You need to identify the key that you want to delete, and then to delete a WebAuthn key, from an administrator command prompt, run:
certutil -csp NGC -delkey <name> Replacing <name> with the full pathname from the output of the command above.
macOS
Chrome/Chromium (108 & later)
"Settings > Auto-fill > Password Manager > Manage passkeys". Chrome also allows users to edit the username, however this doesn't affect the login process since the resident key is identified by its public key ID.
Safari
Passkeys are managed under "System Settings > Passwords". Click the i icon > Edit and from here you can also "Delete Passkey". However, attempting to add password to a passkey System Settings will not let you save it.
YubiKey
YubiKey 5 and higher: use the Yubico Authenticator app (running as Administrator), clicking through to the WebAuthn settings and entering the keys passphrase to view stored keys. In Chromium based browsers on Linux, security keys can also be managed via "Settings > Privacy and security > Security > Manage security keys".
Older YubiKeys (such as U2F keys) do not store resident keys and use a computed public/private key, as there no data stored on the key.