webauthn-simple-app

node.js:

This module makes passwordless (or second-factor) W3C's Web Authentication simple. The primary interface is the WebAuthnApp class, with the register() and login() methods for registering new devices and / or logging in via WebAuthn. The interface takes care of communicating with your WebAuthn server, validating server responses, calling the browser's WebAuthn API with the right options, and everything else.

There is much more functionality available for debugging or more granular control, but it probably isn't needed for most applications.

The module is also exported as a npm module, allowing the Msg class to be used in node.js servers for creating, validating, and converting all the communications with a browser.

For a live demo of this project, see webauthn.org.

Documentation for all classes and advanced options is available online.

Install

npm

npm install webauthn-simple-app

CDN

ES6 Module

<script src="https://cdn.jsdelivr.net/npm/webauthn-simple-app/dist/webauthn-simple-app.esm.js"></script>

Universial Module (UMD)

<script src="https://cdn.jsdelivr.net/npm/webauthn-simple-app/dist/webauthn-simple-app.umd.js"></script>

GitHub

git clone https://github.com/apowers313/webauthn-simple-app

Download .zip and .tgz downloads are available from the releases page.

Simple Example

Register:

// register a new device / account
var waApp = new WebAuthnApp()
waApp.username = "me";
waApp.register()
    .then(() => {
        alert("You are now registered!");
    })
    .catch((err) => {
        alert("Registration error: " + err.message);
    });

Log in:

// log in to a previously registered account
var waApp = new WebAuthnApp()
waApp.username = "me";
waApp.login()
    .then(() => {
        alert("You are now logged in!");
    })
    .catch((err) => {
        alert("Log in error: " + err.message);
    });

Real Example

Here is a more complete example, using jQuery to do things like get inputs from forms and respond to various events that are fired.

JavaScript

// override some of the default configuration options
// see the docs for a full list of configuration options
var webAuthnConfig = {
    timeout: 30000
};
 
// when user clicks submit in the register form, start the registration process
$("#register-form").submit(function(event) {
    event.preventDefault();
    webAuthnConfig.username = $(event.target).children("input[name=username]")[0].value
    new WebAuthnApp(webAuthnConfig).register();
});
 
// when user clicks submit in the login form, start the log in process
$("#login-form").submit(function(event) {
    event.preventDefault();
    webAuthnConfig.username = $(event.target).children("input[name=username]")[0].value
    new WebAuthnApp(webAuthnConfig).login();
});
 
// do something when registration is successful
$(document).on("webauthn-register-success", () => {
    window.location = "https://example.com/sign-in-page";
});
 
// do something when registration fails
$(document).on("webauthn-register-error", (err) => {
    // probably do something nice like a toast or a modal...
    alert("Registration error: " + err.message);
});
 
// do something when log in is successful
$(document).on("webauthn-login-success", () => {
    window.location = "https://example.com/my-profile-page";
});
 
// do something when log in fails
$(document).on("webauthn-login-error", (err) => {
    // probably do something nice like a toast or a modal...
    alert("Log in error: " + err.message);
});
 
// gently remind the user to authenticate when it's time
$(document).on("webauthn-user-presence-start", (err) => {
  // probably do something nice like a toast or a modal...
    alert("Please perform user verification on your authenticator now!");
});

HTML

<html>
    <!-- A very simple registration form -->
    <form id="register-form">
        <input type="text" id="username" name="username" placeholder="Username" autofocus="autofocus">
        <input type="submit" id="registerButton" class="btn btn-success" value="Register">
    </form>
 
    <!-- A very simple log in form -->
    <form id="login-form">
        <input type="text" id="username" name="username" placeholder="Username" autofocus="autofocus">
        <input type="submit" id="loginButton" class="btn btn-success" value="Login">
    </form>
</html>

Complete Example

For a complete example using jQuery and Bootstrap, refer to the code at the webauthn-yubiclone project, specifically index.html and ux-events.js.

Theory of Operation

Here's what's going on inside when you call register or login:

WebAuthnApp.register():

getRegisterOptions()
- client --> CreateOptionsRequest --> server
- client <-- CreateOptions <-- server
create()
- CredentialAttestation = navigator.credentials.create(CreateOptions)
sendRegisterResult()
- client --> CredentialAttestation --> server
- client <-- ServerResponse <-- server

WebAuthnApp.login():

getLoginOptions()
- client --> GetOptionsRequest --> server
- client <-- GetOptions <-- server
get()
- CredentialAssertion = navigator.credentials.get(GetOptions)
sendLoginResult()
- client --> CredentialAssertion --> server
- client <-- ServerResponse <-- server

Sponsor

Note that while I used to be Technical Director for FIDO Alliance (and I am currently the Technical Advisor for FIDO Alliance), THIS PROJECT IS NOT ENDORSED OR SPONSORED BY FIDO ALLIANCE.

Work for this project is supported by my consulting company: WebAuthn Consulting.

npm