This monorepo contains two complimentary libraries to help reduce the amount of work needed to incorporate WebAuthn into a website. The following packages are maintained here:
An additional package is also included that contains shared TypeScript definitions:
See these packages' READMEs for more specific implementation information.
API Documentation
In-depth API documentation for all of the packages in this project is available here: https://docs.simplewebauthn.dev/
WebAuthn is a browser API that enables the use of physical, cryptographically-secure hardware "authenticators" to provide stronger replacements to passwords or 2FA.
Website back ends that wish to leverage this technology must be set up to do two things:
- Provide to the front end a specific collection of values that the hardware authenticator will understand for "registration" and "login".
- Parse responses from a hardware authenticator.
Website front ends have their own part to play in the process:
- Pass the server-provided values into
navigator.credentials.create()andnavigator.credentials.get()so the user can interact with their compatible authenticator. - Pass the authenticator's response returned from these methods back to the server.
On the surface, this is a relatively straightforward dance. Unfortunately the values passed into the navigator.credentials methods and the responses received from them make heavy use of ArrayBuffer's which are difficult to transmit as JSON between front end and back end. Not only that, there are many complex ways in which authenticator responses must be parsed, and though finalized, the W3C spec is quite complex and is being expanded all the time.
Enter SimpleWebAuthn.
SimpleWebAuthn attempts to offer a developer-friendly pair of libraries that simplify the above dance. @simplewebauthn/server exports a small number of methods requiring a handful of simple inputs that pair with the two primary methods exported by @simplewebauthn/browser. No converting back and forth between Uint8Array (or was this supposed to be an ArrayBuffer...?) and String, no worrying about JSON compatibility - SimpleWebAuthn takes care of it all!
For a practical guide to implementing these to libraries, take a look at the example project. It includes a single-file Express server and a few HTML files that, combined with the packages in this repo, are close to all it takes to get up and running with WebAuthn.
WebAuthn support is currently spotty, but getting better. Here are things I've tested that I know support WebAuthn and work fine with the SimpleWebAuthn example:
| OS | Browser | Authenticator |
|---|---|---|
| macOS | Firefox | Yubikey Security Key NFC (USB) |
| macOS | Chrome | Touch ID |
| iOS | Safari | Yubikey Security Key NFC (NFC) |
| Android | Chrome | Fingerprint Scanner |
| Android | Firefox | Screen PIN |
The FIDO Alliance maintains a list of what currently supports WebAuthn. If "WebAuthn API" is green, that combination of browser and OS should work fine with SimpleWebAuthn. That said, SimpleWebAuthn isn't perfect, so pull requests are welcome!
After pulling down the code, set up dependencies:
$> npm install
$> npm run bootstrapTo run unit tests for all tracked lerna packages, run the following:
$> npx lerna run testRunning Jest in watch mode for a specific project requires the use of lerna exec:
$> npx lerna exec npm run test:watch --scope=@simplewebauthn/server