webauthn-components v0.2.9

Web Components for the Web Authentication API

A collection of Web Components that make the Web Authentication API a little easier to use.

Installation

npm i webauthn-components

These components use CSS ::part to enable styling

Components

• webauthn-login
• webauthn-registration
• webauthn-recovery
• webauthn-enrollment-requester
• webauthn-enrollment-provider
• webauthn-rtc-enrollment-requester
• webauthn-rtc-enrollment-provider

webauthn-login

Back to components list ☝

Used for connecting with a previously registered account

Usage

with default values

import "webauthn-components/login";

/* html */
<webauthn-login></webauthn-login>;

with custom values

import "webauthn-components/login";

/* html */
<webauthn-login label="Email" input-type="email" input-name="email"></webauthn-login>;

Properties

Endpoint for retrieving details and challenge from the server

• type: String
• default: /api/assertion/start

Endpoint for completing the assertion process and sending the challenge result to the server

• type: String
• default: /api/assertion/finish

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

PublicKeyCredentialRequestOptions decoding function (i.e. Base64URLString to ArrayBuffer)

• type: Function
• default: decodePublicKeyCredentialRequestOptions from utils/parse

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

• type: Function
• default: encodeLoginCredential from utils/parse

The text displayed on the login button

• type: String
• default: Login
• reflected attribute: button-text

The type of input to use for the username

• type: String
• default: text (any valid HTML input type)
• reflected attribute: input-type

The name of the input to use for the username

• type: String
• default: username
• reflected attribute: input-name

Username label content

• type: String
• default: Username
• reflected attribute: label

Should login be done without a username

• type: Boolean
• default: false
• reflected attribute: no-username

Events

Emitted when the login process starts (i.e. on form submit)

• type: CustomEvent
• detail: null

Emitted when retrieving the local credentials using navigator.credentials.get()

• type: CustomEvent
• detail: null

Emitted when the login process is completed succesfully

• type: CustomEvent
• detail: {...} (content returned by the assertionFinishUrl endpoint)

Emitted when the login process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-login::part(form) {...}

Exposes the label element for styling

webauthn-login::part(label) {...}

Exposes the input element for styling

webauthn-login::part(input) {...}

Exposes the button element for styling

webauthn-login::part(button) {...}

webauthn-registration

Back to components list ☝

Used for creating a new account

Usage

with default values

import "webauthn-components/registration";

/* html */
<webauthn-registration></webauthn-registration>;

with custom values

import "webauthn-components/registration";

/* html */
<webauthn-registration label="Email" input-type="email" input-name="email"></webauthn-registration>;

const registrationComponent = document.querySelector("webauthn-registration");
registrationComponent.fetchOptions = { ...registrationComponent.fetchOptions, cache: "no-cache" };

Properties

Endpoint for retrieving initial details and challenge from the server

• type: String
• default: /api/registration/start

Endpoint for completing the registration process

• type: String
• default: /api/registration/finish

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

• type: Function
• default: decodePublicKeyCredentialCreateOptions from utils/parse

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

• type: Function
• default: encodeRegisterCredential from utils/parse

The text displayed on the login button

• type: String
• default: Login
• reflected attribute: button-text

The type of input to use for the username

• type: String
• default: text (any valid HTML input type)
• reflected attribute: input-type

The name of the input to use for the username

• type: String
• default: username
• reflected attribute: input-name

Username label content

• type: String
• default: Username
• reflected attribute: label

Should login be done without a username

• type: Boolean
• default: false
• reflected attribute: no-username

Events

Emitted when the registration process starts (i.e. on form submit)

• type: CustomEvent
• detail: null

Emitted after creating the local credentials using navigator.credentials.create()

• type: CustomEvent
• detail: null

Emitted when the registration process is completed succesfully

• type: CustomEvent
• detail: {...} (content returned by the registrationFinishUrl endpoint)

Emitted when the registration process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-registration::part(form) {...}

Exposes the label element for styling

webauthn-registration::part(label) {...}

Exposes the input element for styling

webauthn-registration::part(input) {...}

Exposes the button element for styling

webauthn-registration::part(button) {...}

webauthn-recovery

Back to components list ☝

Used for recovering access to an existing account

Usage

with default values

import "webauthn-components/recovery";

/* html */
<webauthn-recovery></webauthn-recovery>;

with custom values

import "webauthn-components/recovery";

/* html */
<webauthn-recovery label="Recovery code" input-type="number" input-name="code"></webauthn-recovery>;

const recoveryComponent = document.querySelector("webauthn-recovery");
recoveryComponent.fetchOptions = { ...recoveryComponent.fetchOptions, cache: "no-cache" };

Properties

Endpoint for retrieving initial details and challenge from the server

• type: String
• default: /api/registration/start

Endpoint for completing the recovery process

• type: String
• default: /api/registration/finish

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

• type: Function
• default: decodePublicKeyCredentialCreateOptions from utils/parse

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

• type: Function
• default: encodeRegisterCredential from utils/parse

The text displayed on the recovery button

• type: String
• default: Recover
• reflected attribute: button-text

The type of input to use for the recovery token

• type: String
• default: text (any valid HTML input type)
• reflected attribute: input-type

The name of the input to use for the recovery token

• type: String
• default: recovery-token
• reflected attribute: input-name

Recovery token label content

• type: String
• default: Recovery token
• reflected attribute: label

Events

Emitted when the recovery process starts (i.e. on form submit)

• type: CustomEvent
• detail: null

Emitted after creating the local credentials using navigator.credentials.create()

• type: CustomEvent
• detail: null

Emitted when the recovery process is completed succesfully

• type: CustomEvent
• detail: {...} (content returned by the registrationFinishUrl endpoint)

Emitted when the recovery process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-recovery::part(form) {...}

Exposes the label element for styling

webauthn-recovery::part(label) {...}

Exposes the input element for styling

webauthn-recovery::part(input) {...}

Exposes the button element for styling

webauthn-recovery::part(button) {...}

webauthn-enrollment-requester

Back to components list ☝

Used for initiating the enrollment flow, which adds a new device to an existing account

Usage

with default values

import "webauthn-components/enrollment-requester";

/* html */
<webauthn-enrollment-requester></webauthn-enrollment-requester>;

with custom values

import "webauthn-components/enrollment-requester";

/* html */
<webauthn-enrollment-requester label="Enrollment code" input-type="number" input-name="code"></webauthn-enrollment-requester>;

const enrollmentComponent = document.querySelector("webauthn-enrollment-requester");
enrollmentComponent.fetchOptions = { ...enrollmentComponent.fetchOptions, cache: "no-cache" };

Properties

Endpoint for retrieving initial details and challenge from the server

• type: String
• default: /api/registration/start

Endpoint for completing the recovery process

• type: String
• default: /api/registration/finish

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

• type: Function
• default: decodePublicKeyCredentialCreateOptions from utils/parse

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

• type: Function
• default: encodeRegisterCredential from utils/parse

The text displayed on the enrollment button

• type: String
• default: Enroll device
• reflected attribute: button-text

The type of input to use for the enrollment token

• type: String
• default: text (any valid HTML input type)
• reflected attribute: input-type

The name of the input to use for the enrollment token

• type: String
• default: registration-add-token
• reflected attribute: input-name

Enrollment token label content

• type: String
• default: Enrollment token
• reflected attribute: label

Events

Emitted when the enrollment process starts (i.e. on form submit)

• type: CustomEvent
• detail: null

Emitted after creating the local credentials using navigator.credentials.create()

• type: CustomEvent
• detail: null

Emitted when the enrollment process is completed succesfully

• type: CustomEvent
• detail: {...} (content returned by the registrationFinishUrl endpoint)

Emitted when the enrollment process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

Exposes the label element for styling

webauthn-enrollment-requester::part(label) {...}

Exposes the input element for styling

webauthn-enrollment-requester::part(input) {...}

Exposes the button element for styling

webauthn-enrollment-requester::part(button) {...}

webauthn-enrollment-provider

Back to components list ☝

Used for generating the registration add token, required to add a new device to an existing account

Usage

with default values

import "webauthn-components/enrollment-provider";

/* html */
<webauthn-enrollment-provider></webauthn-enrollment-provider>;

with custom values

import "webauthn-components/enrollment-provider";

/* html */
<webauthn-enrollment-provider button-text="Get registration token"></webauthn-enrollment-provider>;

const enrollmentComponent = document.querySelector("webauthn-enrollment-provider");
enrollmentComponent.fetchOptions = { ...enrollmentComponent.fetchOptions, cache: "no-cache" };

Properties

Endpoint for retrieving the registration add token from the server

• type: String
• default: /api/registration/add

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "GET",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

The text displayed on the enrollment button

• type: String
• default: Connect
• reflected attribute: button-text

Events

Emitted when the enrollment process starts (i.e. on form submit)

• type: CustomEvent
• detail: null

Emitted when the server returns the registration add token

• type: CustomEvent
• detail: {...} (content returned by the enrollmentTokenUrl endpoint)

Emitted when the enrollment process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

Exposes the button element for styling

webauthn-enrollment-requester::part(button) {...}

webauthn-rtc-enrollment-requester

Back to components list ☝

Used for initiating the enrollment flow using WebRTC

Usage

with default values

import "webauthn-components/rtc/enrollment-requester";

/* html */
<webauthn-rtc-enrollment-requester></webauthn-rtc-enrollment-requester>;

with custom values

import "webauthn-components/rtc/enrollment-requester";

/* html */
<webauthn-rtc-enrollment-requester request-button-text="Get connection code"></webauthn-rtc-enrollment-requester>;

const enrollmentComponent = document.querySelector("webauthn-rtc-enrollment-requester");
enrollmentComponent.confirmButtonText = `Add this device to ${userName}'s account`;
enrollmentComponent.agreementText = "I know what I'm doing";

Properties

Endpoint for retrieving initial details and challenge from the server

• type: String
• default: /api/registration/start

Endpoint for completing the recovery process

• type: String
• default: /api/registration/finish

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

WebSocket endpoint used for the discovery of the two devices through WebRTC

• type: String
• default: /api/socket

List of ICE servers to use for WebRTC connectivity

• type: Array
• default: [{ urls: "stun:stun.services.mozilla.com" }]

Access to the RTCPeerConnection instance associated with this component

• type: RTCPeerConnection
• default: null until initialization

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

• type: Function
• default: decodePublicKeyCredentialCreateOptions from utils/parse

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

• type: Function
• default: encodeRegisterCredential from utils/parse

The text displayed on the button used to generate WebSocket room code

• type: String
• default: Generate code
• reflected attribute: request-button-text

The text displayed on the button used to confirm the enrollment

• type: String
• default: Enroll device
• reflected attribute: confirm-button-text

The text displayed on the button used to cancel the enrollment

• type: String
• default: Cancel
• reflected attribute: cancel-button-text

The text displayed next to the checkbox for confirming the enrollment

• type: String
• default: I understand that this device will be added to another account
• reflected attribute: agreement-text

The WebSocket room code used to establish connectivity between the devices

• type: String
• default: ""
• reflected attribute: peer-code

The registration add token received from the authenticated device

• type: String
• default: ""
• reflected attribute: registration-add-token

Events

Emitted when user start the enrollment process by requesting a peer code

• type: CustomEvent
• detail: null

Emitted after a enrollment provider has successfuly connected via WebRTC`

• type: CustomEvent
• detail: { user: String }

Emitted when the enrollment process is cancelled by the requesting user

• type: CustomEvent
• detail: null

Emitted when the user has checked the agreement field

• type: CustomEvent
• detail: null

Emitted when the user has unchecked the agreement field

• type: CustomEvent
• detail: null

Emitted when the registration add token is received from the provider and set on the property

• type: CustomEvent
• detail: null

Emitted when the enrollment process begins registering the new device

• type: CustomEvent
• detail: null

Emitted when the enrollment process has successfuly created the credentials

• type: CustomEvent
• detail: null

Emitted when the enrollment process has successfuly completed and the device has been registered to an existing account

• type: CustomEvent
• detail: { ... } (content returned by the enrollmentFinishUrl endpoint)

Emitted when the enrollment process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

Exposes the label elements for styling

webauthn-enrollment-requester::part(label) {...}

Exposes the input[type=checkbox] element for styling

webauthn-enrollment-requester::part(checkbox) {...}

Exposes the button elements for styling

webauthn-enrollment-requester::part(button) {...}

Exposes the request button element for styling

webauthn-enrollment-requester::part(request-button) {...}

Exposes the confirm button element for styling

webauthn-enrollment-requester::part(confirm-button) {...}

Exposes the cancel button element for styling

webauthn-enrollment-requester::part(cancel-button) {...}

Exposes the elements marked [hidden] for styling

webauthn-enrollment-requester::part(hidden) {...}

webauthn-rtc-enrollment-provider

Back to components list ☝

Used for providing the registration add token in the enrollment flow using WebRTC

Usage

with default values

import "webauthn-components/rtc/enrollment-provider";

/* html */
<webauthn-rtc-enrollment-provider></webauthn-rtc-enrollment-provider>;

with custom values

import "webauthn-components/rtc/enrollment-provider";

/* html */
<webauthn-rtc-enrollment-provider button-text="Establish connection"></webauthn-rtc-enrollment-provider>;

const enrollmentComponent = document.querySelector("webauthn-rtc-enrollment-provider");
enrollmentComponent.webSocketSignalingEndpoint = "/api/ws";
enrollmentComponent.inputName = "ws-peer-code"

Properties

Endpoint for retrieving the registration add token for the current account

• type: String
• default: /api/registration/add

Fetch options used for all request within this component

• type: Object
• default:

{
  "method": "GET",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

WebSocket endpoint used for the discovery of the two devices through WebRTC

• type: String
• default: /api/socket

List of ICE servers to use for WebRTC connectivity

• type: Array
• default: [{ urls: "stun:stun.services.mozilla.com" }]

Access to the RTCPeerConnection instance associated with this component

• type: RTCPeerConnection
• default: null until initialization

The text displayed on the button used to connect to the enrollment requester

• type: String
• default: Connect
• reflected attribute: button-text

The text on the label for the peer code input

• type: String
• default: Code
• reflected attribute: label

The type of the input used for the peer code

• type: String
• default: text
• reflected attribute: input-type

The name of the input used for the peer code

• type: String
• default: code
• reflected attribute: input-name

Events

Emitted when the enrollment process begins and the two devices try to connect to each other

• type: CustomEvent
• detail: null

Emitted when the component receives an enrollment request from the peer

• type: CustomEvent
• detail: null

Emitted when the registration add token is sent to the peer device requesting it

• type: CustomEvent
• detail: { ... } (content returned by the enrollmentTokenUrl endpoint)

Emitted when the enrollment process is cancelled by the requesting user

• type: CustomEvent
• detail: null

Emitted when the enrollment process has successfuly completed and the peer device has been registered to the current account

• type: CustomEvent
• detail: null

Emitted when the enrollment process is interrupted by an error

• type: CustomEvent
• detail: { message: String }

Styling

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

Exposes the label element for styling

webauthn-enrollment-requester::part(label) {...}

Exposes the input element for styling

webauthn-enrollment-requester::part(input) {...}

Exposes the button element for styling

webauthn-enrollment-requester::part(button) {...}

License

MIT License

A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

Refer to the LICENSE file for the complete text.