Passkey authentication

The authentication section of the quick start 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 usually identify the user via authenticatorId (passkey ID). Only use userId as your primary lookup key if you have explicitly assigned it to match your own account IDs. See linking-accounts.

Testing for passkey support

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

frontend/login.ts

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

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

import { authenticatePasskey } from "@passlock/browser";

// 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

import { authenticatePasskey } from "@passlock/browser";

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

This is conceptually similar to the excludeCredentials 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

import { authenticatePasskey } from "@passlock/browser";

document.addEventListener('DOMContentLoaded', async () => {
  const result = await authenticatePasskey({ 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 using 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 user’s 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.