webauthn

Implementation of strong authentication with the webauthn standard and FIDO2. Strong authentication is an authentication method using a physical key.

For a more thorough introduction see these two nice articles:

• introduction
• verifying fido2 responses

Installation

npm install @tanglemesh/webauthn-server

Usage

const WebAuthn = require ("@tanglemesh/webauthn-server");

or

import WebAuthn from "@tanglemesh/webauthn-server";

Then initialize a new Object like

const webAuthn = new WebAuthn ({
    …options
});

Options

• origin – string representing the domain origin that should be allowed
• relyingParty.id – string identifying your platform
• relyingParty.name – string identifying your platform as display name
• relyingParty.icon – string*optional a URL for the service's icon. Can be a RFC 2397 data URL.
• authenticator (default: platform) – string Indicates whether authenticators should be part of the OS ("platform"), or can be roaming authenticators ("cross-platform").
• attestation (default: direct) – string The preferred attestation type to be used. See [AttestationConveyancePreference]{https://w3.org/TR/webauthn/#enumdef-attestationconveyancepreference} in the WebAuthn spec.
• userVerification (default: preferred) – string Indicates whether user verification should be performed. Options are "required", "preferred", or "discouraged".
• timeout (default: 60000) – number The amount of time to wait, in milliseconds, before a call has timed out.
• attestationType (default: public-key) – string The type that should be used to by the fido2 device.
• assertionTransports (default: ['usb','nfc','ble','internal']) – array<string> The assertion transports that can be used by the fido2 device. ],

Methods

• generateAttestation (user = { id, name, displayName*optional }): Generate a challenge from a relying party and a user { relyingParty: { name }, user: { id, name, displayName } } to be sent back to the client, in order to register.
• parseAttestation (attestationResponse): Parse the attestation response from the fido2 device and validate it. Response: { valid, key: { fmt, publicKey, counter, credID } }.
• generateAssertion (key): Generate a challenge from a user's key (returned by parseAttestation) to be sent back to the client, in order to log in.
• parseAssertion (assertionResponse, key): Parse the assertion response from the fido2 device and validate it. Response: { valid, key: { fmt, publicKey, counter, credID }, challenge, id }.
• getClientData (attestationOrAssertionResponse): Extract challenge and key from the register request body. The challenge allow to retrieve the user, and the key must be stored server side linked to the user. Response { type, challenge, origin, crossOrigin }.

Example

See an example in example

You can use the example to test the web-authn package. Just start up the test server with npm install && npm start. Now you can navigate to http://localhost:8000 and test the different requests and web-authn steps.