https://github.com/digitallyrefined/passkey-passwordless
An example Passkey application showing how passwordless registration and authentication journeys work.
https://github.com/digitallyrefined/passkey-passwordless
browser fido fido2 passkey passkeys passkeys-demo typescript webauthn webauthn-demo
Last synced: 3 months ago
JSON representation
An example Passkey application showing how passwordless registration and authentication journeys work.
- Host: GitHub
- URL: https://github.com/digitallyrefined/passkey-passwordless
- Owner: DigitallyRefined
- Created: 2024-02-03T17:31:10.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-06T08:28:55.000Z (3 months ago)
- Last Synced: 2025-10-06T08:43:54.021Z (3 months ago)
- Topics: browser, fido, fido2, passkey, passkeys, passkeys-demo, typescript, webauthn, webauthn-demo
- Language: TypeScript
- Homepage:
- Size: 516 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: FUNDING.yml
Awesome Lists containing this project
README
# 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](https://nodejs.org/) and/or [Docker](https://www.docker.com/) 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`](https://github.com/nodkz/mongodb-memory-server/issues/480#issuecomment-1488548395):
```bash
# 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:8000 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?](https://caniuse.com/?search=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 `//FIDO_AUTHENTICATOR//_`
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 ` Replacing `` 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](https://support.yubico.com/hc/en-us/articles/360016649339-YubiKey-5C-NFC) and higher: use the [Yubico Authenticator app](https://www.yubico.com/products/yubico-authenticator/) (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](https://support.yubico.com/hc/en-us/articles/360013656800-FIDO-U2F-Security-Key)) do not store resident keys and use a computed public/private key, as there's no data stored on the key.
## See also
- [WebAuthn.io](https://webauthn.io/)
- [FIDO2 - FIDO Alliance](https://fidoalliance.org/fido2/)
- [SimpleWebAuthn Project](https://github.com/MasterKale/SimpleWebAuthn)
- [Can I use WebAuthn? - Browser support](https://caniuse.com/?search=WebAuthn)
- [Google - Build your first WebAuthn app](https://developers.google.com/codelabs/webauthn-reauth)
- [Bringing passkeys to Android & Chrome](https://android-developers.googleblog.com/2022/10/bringing-passkeys-to-android-and-chrome.html)