@teamhanko/hanko-webauthn
@teamhanko/hanko-webauthn is a client-side Javascript library that serves as a wrapper for the
WebAuthn API by encoding binary data using
base64url (also known as "websafe" or "urlsafe" base64).
The WebAuthn API itself takes input and output values that look almost like JSON, except that binary data is represented
as ArrayBuffers. Using hanko-webauthn allows the data to be sent from/to the server as normal JSON without any custom
client-side processing.
Installation
NPM/Yarn
# Using npm
npm install --save @teamhanko/hanko-webauthn
# Using yarn
yarn add @teamhanko/hanko-webauthnCDN
Alternatively, you can load the library via CDN using a script tag in your application <head>:
<script src="https://cdn.jsdelivr.net/npm/@teamhanko/hanko-webauthn@latest/dist/browser-global/hanko-webauthn.browser-global.js"></script>When using this method a browser global hankoWebAuthn will be set.
// destructure global
const { create: createCredentials, get: getCredentials } = hankoWebAuthn;
// using the global directly
hankoWebAuthn.create();Usage
The following are simple examples for performing registration and authentication using the SDK . For more information, refer to the Hanko API implementation guide.
Registration
import {create as createCredential} from "@teamhanko/hanko-webauthn"
// register credential for a given userName, which typically would be read from
// a registration form
async function register(userName) {
try {
const credentialCreationOptions = await initializeRegistration(userName);
const webAuthnResponse = await createCredential(credentialCreationOptions);
return await finalizeRegistration(webAuthnResponse)
} catch (error) {
// handle error
}
}
// retrieve credential creation options to pass to the WebAuthn API
async function initializeRegistration(userName) {
// adjust fetch URL to backend handler for retrieving
// credential creation options from FIDO server
const response = await fetch(`/webauthn/registration/initialize?user_name=${userName}`);
if (!response.ok) {
// handle fetch error
}
return response.json();
}
// verify WebAuthn response
async function finalizeRegistration(webAuthnResponse) {
// adjust fetch URL to backend handler for verifying
// WebAuthn response with FIDO server
const response = await fetch('/webauthn/registration/finalize', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(webAuthnResponse)
});
if (!response.ok) {
// handle fetch error
}
return response.json();
}Authentication
import {get as getCredential} from "@teamhanko/hanko-webauthn"
// authenticate with a credential for a given userName, which typically would be read from
// a login form
async function authenticate(userName) {
try {
const credentialRequestOptions = await initializeAuthentication(userName);
const credential = await getCredential(credentialRequestOptions);
return await finalizeAuthentication(credential)
} catch (error) {
// handle error
}
}
// retrieve credential request options to pass to the WebAuthn API
async function initializeAuthentication(userName) {
// adjust fetch URL to backend handler for retrieving
// credential request options from FIDO server
const response = await fetch(`/webauthn/authentication/initialize?user_name=${userName}`);
if (!response.ok) {
// handle fetch error
}
return response.json()
}
// verify WebAuthn response
async function finalizeAuthentication(webAuthnResponse) {
// adjust fetch URL to backend handler for verifying
// WebAuthn response with FIDO server
const response = await fetch("/webauthn/authentication/finalize", {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(webAuthnResponse)
});
if (!response.ok) {
// handle fetch error
}
return response.json();
}API
function create(requestJSON: CredentialCreationOptionsJSON): Promise<PublicKeyCredentialWithAttestationJSON>;
function get(requestJSON: CredentialRequestOptionsJSON): Promise<PublicKeyCredentialWithAssertionJSON>;
function supported(): boolean;
function isUserVerifyingPlatformAuthenticatorAvailable: Promise<boolean>;
function isSecurityKeySupported(): Promise<boolean>;-
create(requestJSON: CredentialCreationOptionsJSON): Promise<PublicKeyCredentialWithAttestationJSON>:-
Description: Request the creation of a new credential bound to an authenticator.
-
Parameters:
-
requestJSON:- Type:
CredentialCreationOptionsJSON-
publicKey: -
signal:- Type: AbortSignal
- See also: Aborting Authentication Operations
-
- Type:
-
-
Parameters:
-
Returns: Promise that resolves to a
PublicKeyCredentialWithAttestationJSON(a PublicKeyCredential representation, whoseresponsevalue is an AuthenticatorAttestationResponse) - See also: Web Authentication: An API for accessing Public Key Credentials - Create credential
-
Description: Request the creation of a new credential bound to an authenticator.
-
get(requestJSON: CredentialRequestOptionsJSON): Promise<PublicKeyCredentialWithAssertionJSON>:- Description: Discover and use an existing credential on an authenticator.
-
Parameters:
- Type:
CredentialRequestOptionsJSON-
publicKey: -
signal:- Type: AbortSignal
- See also: Aborting Authentication Operations
-
- Type:
-
Returns: Promise that resolves to a
PublicKeyCredentialWithAssertionJSON(a PublicKeyCredential representation, whoseresponsevalue is an AuthenticatorAssertionResponse) - See also: Web Authentication: An API for accessing Public Key Credentials - Get assertion
-
supported(): boolean:- Description: Check if the browser supports the Web Authentication API.
-
isUserVerifyingPlatformAuthenticatorAvailable(): Promise<boolean>:- Description: Check if a user verifying platform authenticator is available.
-
isSecurityKeySupported(): Promise<boolean>:-
Description: In Firefox, checks if external CTAP2 security keys are supported, does a
supported()check in any other browser.
-
Description: In Firefox, checks if external CTAP2 security keys are supported, does a
Acknowledgements
@teamhanko/hanko-webauthn is a fork of the @github/webauthn-json library.