webauthn-simple-app

    2.0.0 • Public • Published

    Sauce Test Status

    node.js: Build Status

    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.

    Install

    npm i webauthn-simple-app

    DownloadsWeekly Downloads

    75

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    1.1 MB

    Total Files

    48

    Last publish

    Collaborators

    • apowers313