Passkey authentication

The authentication section of the quickstart guide covers the basics, so we’ll focus on some more advanced aspects of passkey authentication here.

Username

The passkey username serves as a human palatable representation of the associated account. Suitable values include:

• jdoe
• jdoe@example.com
• jdoe (prod-env)

During authentication, the username will not be returned. You should instead use the authenticatorId or userId to identify the user.

Testing for passkey support

Similar to the registration flow, you probably want to test for passkey support:

frontend/login.ts

import { isPasskeySupport } from "@passlock/client";

if (!isPasskeySupport()) {
  throw new Error("Bad news...")
}

Caution

Don’t assume that because a user registered a passkey, they’re able to authenticate with it. They might be using a different device which doesn’t support passkeys.

Biometric verification

User verification is especially useful during authentication:

frontend/login.ts

// discouraged, preferred (default) or required
const userVerification = "required" as const;
const result = await authenticatePasskey({ tenancyId, userVerification });

Pre-selecting a passkey

To preselect the passkey(s)] presented to the user, pass the ids via the allowCredentials option:

frontend/login.ts

const allowCredentials = [existingPasskeyId]
const result = await authenticatePasskey({ allowCredentials, ... })

This is conceptually similar to the exludeCredentials registration option.

Autofill

If you support more than one login mechanism, passkey autofill tells the browser to use passkey login if a passkey exists on the device.

frontend/login.ts

document.addEventListener('load', async () => {
  const result = await authenticatePasskey({
    tenancyId,
    endpoint: data.endpoint,
    autofill: true
  });
})

Two step login

Alternatively, you might choose to implement a two step login flow, in which the user first enters their account identifier (username/email), before authenticating with their chosen mechanism. After they enter their identifier, check if they registered a passkey, and if so prompt them to authenticate with it.

Handling missing passkeys

Passkeys are comprised of two components - a private key, stored on the users device, and a public key, stored in your passlock vault. If either component is missing the user will receive an error. Learn how to handle missing passkeys gracefully.