web-authn-components v0.2.5

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 web-authn-components

Components

• web-authn-login
• web-authn-registration
• web-authn-recovery
• web-authn-enrollment-requester
• web-authn-enrollment-provider
• web-authn-rtc-enrollment-requester
• web-authn-rtc-enrollment-provider

web-authn-login

Used for connecting with a previously registered account

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 }

Usage

with default values

import "web-authn-components/login";

/* html */
<web-authn-login></web-authn-login>;

with custom values

import "web-authn-components/login";

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

web-authn-registration

Used for creating a new account

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 }

Usage

with default values

import "web-authn-components/registration";

/* html */
<web-authn-registration></web-authn-registration>;

with custom values

import "web-authn-components/registration";

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

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

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.