webauthn-components

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

⚙️ assertionStartUrl

Endpoint for retrieving details and challenge from the server

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

⚙️ assertionFinishUrl

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

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

⚙️ publicKeyCredentialRequestOptionsDecoder

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

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

⚙️ loginCredentialEncoder

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

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

✏️ buttonText

The text displayed on the login button

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

⚙️ inputType

The type of input to use for the username

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

⚙️ inputName

The name of the input to use for the username

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

✏️ label

Username label content

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

⚙️ noUsername

Should login be done without a username

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

Events

🔼 login-started

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

• type: CustomEvent
• detail: null

🔼 login-retrieved

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

• type: CustomEvent
• detail: null

🔼 login-finished

Emitted when the login process is completed succesfully

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

🔼 login-error

Emitted when the login process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(label)

Exposes the label element for styling

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

🎨 ::part(input)

Exposes the input element for styling

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

🎨 ::part(button)

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

⚙️ registrationStartUrl

Endpoint for retrieving initial details and challenge from the server

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

⚙️ registrationFinishUrl

Endpoint for completing the registration process

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

⚙️ publicKeyCredentialCreateOptionsDecoder

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

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

⚙️ registerCredentialEncoder

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

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

✏️ buttonText

The text displayed on the login button

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

⚙️ inputType

The type of input to use for the username

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

⚙️ inputName

The name of the input to use for the username

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

✏️ label

Username label content

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

⚙️ noUsername

Should login be done without a username

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

Events

🔼 registration-started

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

• type: CustomEvent
• detail: null

🔼 registration-created

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

• type: CustomEvent
• detail: null

🔼 registration-finished

Emitted when the registration process is completed succesfully

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

🔼 registration-error

Emitted when the registration process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(label)

Exposes the label element for styling

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

🎨 ::part(input)

Exposes the input element for styling

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

🎨 ::part(button)

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

⚙️ recoveryStartUrl

Endpoint for retrieving initial details and challenge from the server

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

⚙️ recoveryFinishUrl

Endpoint for completing the recovery process

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

⚙️ publicKeyCredentialCreateOptionsDecoder

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

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

⚙️ registerCredentialEncoder

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

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

✏️ buttonText

The text displayed on the recovery button

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

⚙️ inputType

The type of input to use for the recovery token

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

⚙️ inputName

The name of the input to use for the recovery token

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

✏️ label

Recovery token label content

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

Events

🔼 recovery-started

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

• type: CustomEvent
• detail: null

🔼 recovery-created

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

• type: CustomEvent
• detail: null

🔼 recovery-finished

Emitted when the recovery process is completed succesfully

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

🔼 recovery-error

Emitted when the recovery process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(label)

Exposes the label element for styling

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

🎨 ::part(input)

Exposes the input element for styling

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

🎨 ::part(button)

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

⚙️ enrollmentStartUrl

Endpoint for retrieving initial details and challenge from the server

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

⚙️ enrollmentFinishUrl

Endpoint for completing the recovery process

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

⚙️ publicKeyCredentialCreateOptionsDecoder

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

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

⚙️ registerCredentialEncoder

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

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

✏️ buttonText

The text displayed on the enrollment button

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

⚙️ inputType

The type of input to use for the enrollment token

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

⚙️ inputName

The name of the input to use for the enrollment token

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

✏️ label

Enrollment token label content

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

Events

🔼 enrollment-requested

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

• type: CustomEvent
• detail: null

🔼 enrollment-created

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

• type: CustomEvent
• detail: null

🔼 enrollment-finished

Emitted when the enrollment process is completed succesfully

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

🔼 enrollment-error

Emitted when the enrollment process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(label)

Exposes the label element for styling

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

🎨 ::part(input)

Exposes the input element for styling

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

🎨 ::part(button)

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

⚙️ enrollmentTokenUrl

Endpoint for retrieving the registration add token from the server

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

✏️ buttonText

The text displayed on the enrollment button

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

Events

🔼 enrollment-requested

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

• type: CustomEvent
• detail: null

🔼 enrollment-provided

Emitted when the server returns the registration add token

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

🔼 enrollment-error

Emitted when the enrollment process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(button)

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

⚙️ enrollmentStartUrl

Endpoint for retrieving initial details and challenge from the server

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

⚙️ enrollmentFinishUrl

Endpoint for completing the recovery process

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

⚙️ webSocketSignalingEndpoint

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

• type: String
• default: /api/socket

⚙️ rtcIceServers

List of ICE servers to use for WebRTC connectivity

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

⚙️ RTC

Access to the RTCPeerConnection instance associated with this component

• type: RTCPeerConnection
• default: null until initialization

⚙️ publicKeyCredentialCreateOptionsDecoder

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

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

⚙️ registerCredentialEncoder

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

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

✏️ requestButtonText

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

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

✏️ confirmButtonText

The text displayed on the button used to confirm the enrollment

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

✏️ cancelButtonText

The text displayed on the button used to cancel the enrollment

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

✏️ agreementText

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

⚙️ peerCode

The WebSocket room code used to establish connectivity between the devices

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

⚙️ registrationAddToken

The registration add token received from the authenticated device

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

Events

🔼 enrollment-code-requested

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

• type: CustomEvent
• detail: null

🔼 enrollment-provider-connected

Emitted after a enrollment provider has successfuly connected via WebRTC`

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

🔼 enrollment-cancelled

Emitted when the enrollment process is cancelled by the requesting user

• type: CustomEvent
• detail: null

🔼 enrollment-agreement-accepted

Emitted when the user has checked the agreement field

• type: CustomEvent
• detail: null

🔼 enrollment-agreement-declined

Emitted when the user has unchecked the agreement field

• type: CustomEvent
• detail: null

🔼 enrollment-registration-token-received

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

• type: CustomEvent
• detail: null

🔼 enrollment-started

Emitted when the enrollment process begins registering the new device

• type: CustomEvent
• detail: null

🔼 enrollment-created

Emitted when the enrollment process has successfuly created the credentials

• type: CustomEvent
• detail: null

🔼 enrollment-completedd

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)

🔼 enrollment-error

Emitted when the enrollment process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(label)

Exposes the label elements for styling

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

🎨 ::part(checkbox)

Exposes the input[type=checkbox] element for styling

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

🎨 ::part(button)

Exposes the button elements for styling

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

🎨 ::part(request-button)

Exposes the request button element for styling

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

🎨 ::part(confirm-button)

Exposes the confirm button element for styling

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

🎨 ::part(cancel-button)

Exposes the cancel button element for styling

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

🎨 ::part(hidden)

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

⚙️ enrollmentTokenUrl

Endpoint for retrieving the registration add token for the current account

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

⚙️ fetchOptions

Fetch options used for all request within this component

• type: Object
• default:

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

⚙️ webSocketSignalingEndpoint

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

• type: String
• default: /api/socket

⚙️ rtcIceServers

List of ICE servers to use for WebRTC connectivity

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

⚙️ RTC

Access to the RTCPeerConnection instance associated with this component

• type: RTCPeerConnection
• default: null until initialization

✏️ buttonText

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

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

✏️ label

The text on the label for the peer code input

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

⚙️ inputType

The type of the input used for the peer code

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

⚙️ inputName

The name of the input used for the peer code

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

Events

🔼 enrollment-started

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

• type: CustomEvent
• detail: null

🔼 enrollment-requested

Emitted when the component receives an enrollment request from the peer

• type: CustomEvent
• detail: null

🔼 enrollment-provided

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

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

🔼 enrollment-cancelled

Emitted when the enrollment process is cancelled by the requesting user

• type: CustomEvent
• detail: null

🔼 enrollment-completed

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

• type: CustomEvent
• detail: null

🔼 enrollment-error

Emitted when the enrollment process is interrupted by an error

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

Styling

🎨 ::part(form)

Exposes the form element for styling

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

🎨 ::part(label)

Exposes the label element for styling

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

🎨 ::part(input)

Exposes the input element for styling

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

🎨 ::part(button)

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.