WebAuthnJS SDK

Current WebAuthnJS SDK Version: 1.0.1

Version History (change log)

Quick Start Guide

This guide will show you how to install and use the WebAuthnJS SDK.

Prerequisites

WebAuthnJS SDK operates in coordination with the Futurae backend. You must fist integrate the relevant Auth and Admin API endpoints before being able to use WebAuthnJS on the client side. In particular learn more about:

• Using the Admin API to create an RP Configuration for the Futurae Service for which you need to enable FIDO2/WebAuthn.
• Using the Auth (or Admin) API to enroll FIDO2/U2F authenticators for users.
• Using the Auth API to authenticate users using FIDO2/WebAuthn.

Installation

You can use either npm or yarn to fetch and install the WebAuthnJS SDK in your project, as described below.

npm

Create an .npmrc file in the root of your codebase with the following content:

@futurae-public:registry=https://git.futurae.com/api/v4/projects/96/packages/npm/

Install the package:

$ npm i @futurae-public/webauthn-js

yarn

Create an .yarnrc file in the root of your codebase with the following content:

"@futurae-public:registry" "https://git.futurae.com/api/v4/projects/96/packages/npm/"

Install the package:

$ yarn add @futurae-public/webauthn-js

Access

The WebAuthnJS SDK is built by using the Universal Module Definition pattern, so it can be accessed with the following ways:

• ES Module
• Global Variable
• AMD module

ES Module

Call it as an ES6 module in your codebase:

import { FuturaeWebAuthn } from '@futurae-public/webauthn-js';

console.log(FuturaeWebAuthn.supportsWebAuthn());

Global Variable

Use it as a global variable:

<script src="./node_modules/@futurae-public/webauthn-js/dist/futurae-webauthn.min.js"></script>
<script>
  const FuturaeWebAuthn = futuraeWebAuthn.FuturaeWebAuthn;

  console.log(FuturaeWebAuthn.supportsWebAuthn());
</script>

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

<script>

  // ...

  // Initialization
  var webAuthn = new FuturaeWebAuthn({
    base_url: 'https://api.futurae.com',
  });
  webAuthn.init();

  console.log('Version: ' + FuturaeWebAuthn.version);
  console.log('Supports WebAuthn: ' + FuturaeWebAuthn.supportsWebAuthn());

  // ...

  // WebAuthn registration operation (enrollment)
  async handleSubmit() {
    try {
      await webAuthn.enroll({
            activation_code: 'activation_code from the server-side',
            // OR: activation_code_short: 'supplied by the user',
            display_name: 'my usb security key', // supplied by the user
          });

    } catch (err) {
      console.log('====== An error is thrown ======');
      console.log(err);
      console.log(`Name: ${err.name}`);
      console.log(`Message: ${err.message}`);
      console.log(`Status: ${err.status}`);
      console.log(`Code: ${err.code}`);

      // ...
    }
  }

  // ...

  // WebAuthn authentication operation
  async handleSubmit() {
    try {
      await webAuthn.auth({
            session_token: 'session_token from the server-side'
          });

    } catch (err) {
      console.log('====== An error is thrown ======');
      console.log(err);
      console.log(`Name: ${err.name}`);
      console.log(`Message: ${err.message}`);
      console.log(`Status: ${err.status}`);
      console.log(`Code: ${err.code}`);
    }

    // ...
  }

  // ...    
</script>

SDK Reference

Contents

• Class: FuturaeWebAuthn
• Class: FuturaeWebAuthnError
• Interface: Configuration
• Interface: AuthArguments
• Interface: EnrollmentArguments

Class: FuturaeWebAuthn

Constructors

• constructor

Properties

• version

Methods

• auth
• enroll
• init
• isUserVerifyingPlatformAuthenticatorAvailable
• supportsWebAuthn

Constructors

constructor

+ new FuturaeWebAuthn(configuration: Configuration): FuturaeWebAuthn

Parameters:

Returns: FuturaeWebAuthn

Properties

version

▪ Static version: string

The version of the WebAuthnJS SDK.

Methods

auth

▸ auth(args: AuthArguments): Promise

Performs the client-side operation for authenticating the user using FIDO2/WebAuthn. Requires the session_token which was retrieved on the server-side when calling Authenticate with FIDO2/WebAuthn.

Parameters:

Returns: Promise

A promise that is fulfilled if the WebAuthn authentication operation completes successfully or rejected with an error if the operation fails.

enroll

▸ enroll(args: EnrollmentArguments): Promise

Performs the client-side operation for registering a FIDO2/U2F authenticator for a Futurae user using FIDO2/WebAuthn. Requires either the activation_code or the activation_code_short which was retrieved on the server-side when calling Enroll New User with FIDO Device or Enroll New FIDO Device for Existing User.

Parameters:

Returns: Promise

A promise that is fulfilled if the WebAuthn registration operation completes successfully or rejected with an error if the operation fails.

init

▸ init(): void

Initialize the SDK. Has to be called right after constructing the FuturaeWebAuthn object, and before calling any other non-static method.

Returns: void

isUserVerifyingPlatformAuthenticatorAvailable

▸ StaticisUserVerifyingPlatformAuthenticatorAvailable(): Promise<boolean>

Check whether a user-verifying platform authenticator is available.

Returns: Promise<boolean>

supportsWebAuthn

▸ StaticsupportsWebAuthn(): boolean

Check whether WebAuthn is supported in the this browser.

Returns: boolean

Class: FuturaeWebAuthnError

All errors returned by the Futurae WebAuthnJS SDK will be instances of this class.

Properties

• name
• message
• status
• code

Properties

name

• name: string

The name of the error. It’s always FuturaeWebAuthnError.

message

• message: string

An optional message describing the error.

status

• status: number

• If this is a client-side error, status will be 900 and the code will contain a more specific error code.
• If this is a server-side error, i.e., a non 200 OK HTTP response while communicating with the Futurae backend, status will be the returned HTTP response status and the code may contain a more specific (Futurae backend-related) error code.

code

• code: number

The specific error code for this error. Here is the list of specific error codes for client-side errors, i.e., when status is 900:

Interface: Configuration

Properties

base_url

• base_url: string

The base URL to use for connecting to the Futurae backend, for example https://api.futurae.com.

The default value is https://api.futurae.com.

Interface: AuthArguments

Properties

session_token

• session_token: string

The session_token which was retrieved on the server-side when calling Authenticate with FIDO2/WebAuthn.

Interface: EnrollmentArguments

Properties

activation_code

• Optional activation_code: string

The activation_code which was retrieved on the server-side when calling Enroll New User with FIDO Device or Enroll New FIDO Device for Existing User.

You must supply either the activation_code or the activation_code_short.

activation_code_short

• Optional activation_code_short: string

The activation_code_sort which was retrieved on the server-side when calling Enroll New User with FIDO Device or Enroll New FIDO Device for Existing User.

You must supply either the activation_code or the activation_code_short.

display_name

• Optional display_name: string

A user-defined display name for this particular FIDO device. This will help the user distinguish between different FIDO authenticators in case he has more than one enrolled. (It is generally recommended to prompt the user to register more than one FIDO authenticators for his account.) It is recommended to prompt or even force the user choose a name upon registering the device.