Skip to content

An example Passkey application showing how passwordless registration and authentication journeys work.

Notifications You must be signed in to change notification settings

DigitallyRefined/passkey-passwordless

Repository files navigation

Passkey Passwordless

An example Passkey application showing how passwordless registration and authentication journeys work (via WebAuthn).

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

  1. npm install
  2. npm start
Missing `libcrypto.so.1.1`?

On some systems if you're 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:

# Debian/Ubuntu
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.deb

# RHL/Fedora
sudo dnf install openssl1.1

Docker

./start.sh

Usage

  1. http://localhost:3000 to register and login
  2. Check the console output for the email confirmation links
  3. In Chrome, open "DevTools > Console > More tools (hamburger menu) > WebAuthn > Enable virtual authenticator environment" to try out different key types
  4. If Docker is installed check http://localhost:8081 for the user database
  5. Attempt to login from different devices, desktop vs. mobile
  6. Reset database via npm run reset:db (Docker only)
  7. Optionally set the SMTP settings in apps.env to send email and change config.ts to 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 implementations. Some may have full support (such as Brave & Samsung Internet), partial or no support for WebAuthn.

Managing Passkeys

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 Passkeys stored by Windows Hello, from a command prompt, run:

certutil -csp NGC -key

Passkeys 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 Passkey, 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's no data stored on the key.

See also

About

An example Passkey application showing how passwordless registration and authentication journeys work.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published