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:

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

Constructors

Properties

Methods

Constructors

constructor

+ new FuturaeWebAuthn(configuration: Configuration): FuturaeWebAuthn

Parameters:
NameTypeDescription
configurationConfigurationThe configuration object.

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:
NameTypeDescription
argsAuthArgumentsThe arguments object for the auth method.

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 the 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:
NameTypeDescription
argsEnrollmentArgumentsThe arguments object for the enroll method.

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

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:

NumberDescription
90000WebAuthn is not supported by this browser.
90001Error during the underlying WebAuthn registration (enrollment) operation.
90002Error during the underlying WebAuthn authentication operation.
90003The supplied configuration is invalid.
90004Missing params when calling enroll.
90005Both activation_code and activation_code_short where supplied when calling enroll.
90006Missing params when calling auth.
90007An unknown error has occurred.

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.