A collection of Web Components that make the Web Authentication API a little easier to use.
npm i webauthn-components
These components use CSS ::part
to enable styling
- webauthn-login
- webauthn-registration
- webauthn-recovery
- webauthn-enrollment-requester
- webauthn-enrollment-provider
- webauthn-rtc-enrollment-requester
- webauthn-rtc-enrollment-provider
Used for connecting with a previously registered account
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>;
⚙️ 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
fromutils/parse
⚙️ loginCredentialEncoder
Credential encoding function (i.e. ArrayBuffer to Base64URLString)
- type:
Function
- default:
encodeLoginCredential
fromutils/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
🔼 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 theassertionFinishUrl
endpoint)
🔼 login-error
Emitted when the login process is interrupted by an error
- type:
CustomEvent
- detail:
{ message: String }
🎨 ::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) {...}
Used for creating a new account
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" };
⚙️ 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
fromutils/parse
⚙️ registerCredentialEncoder
Credential encoding function (i.e. ArrayBuffer to Base64URLString)
- type:
Function
- default:
encodeRegisterCredential
fromutils/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
🔼 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 theregistrationFinishUrl
endpoint)
🔼 registration-error
Emitted when the registration process is interrupted by an error
- type:
CustomEvent
- detail:
{ message: String }
🎨 ::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) {...}
Used for recovering access to an existing account
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" };
⚙️ 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
fromutils/parse
⚙️ registerCredentialEncoder
Credential encoding function (i.e. ArrayBuffer to Base64URLString)
- type:
Function
- default:
encodeRegisterCredential
fromutils/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
🔼 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 theregistrationFinishUrl
endpoint)
🔼 recovery-error
Emitted when the recovery process is interrupted by an error
- type:
CustomEvent
- detail:
{ message: String }
🎨 ::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) {...}
Used for initiating the enrollment flow, which adds a new device to an existing account
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" };
⚙️ 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
fromutils/parse
⚙️ registerCredentialEncoder
Credential encoding function (i.e. ArrayBuffer to Base64URLString)
- type:
Function
- default:
encodeRegisterCredential
fromutils/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
🔼 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 theregistrationFinishUrl
endpoint)
🔼 enrollment-error
Emitted when the enrollment process is interrupted by an error
- type:
CustomEvent
- detail:
{ message: String }
🎨 ::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) {...}
Used for generating the registration add token, required to add a new device to an existing account
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" };
⚙️ 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
🔼 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 theenrollmentTokenUrl
endpoint)
🔼 enrollment-error
Emitted when the enrollment process is interrupted by an error
- type:
CustomEvent
- detail:
{ message: String }
🎨 ::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) {...}
Used for initiating the enrollment flow using WebRTC
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";
⚙️ 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
fromutils/parse
⚙️ registerCredentialEncoder
Credential encoding function (i.e. ArrayBuffer to Base64URLString)
- type:
Function
- default:
encodeRegisterCredential
fromutils/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
🔼 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 theenrollmentFinishUrl
endpoint)
🔼 enrollment-error
Emitted when the enrollment process is interrupted by an error
- type:
CustomEvent
- detail:
{ message: String }
🎨 ::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) {...}
Used for providing the registration add token in the enrollment flow using WebRTC
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"
⚙️ 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
🔼 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 theenrollmentTokenUrl
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 }
🎨 ::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) {...}
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.