Pre-selecting specific passkeys using the allowCredentials property

TL;DR

If you know which passkeys are associated with an account, you can pre-select them via the allowCredentials or userId option. The user’s device will then limit passkey selection to one of those.

If the user is already logged into their account, or they have presented a username/email in a two-step login flow, you can help them out by preselecting the passkey they should use to authenticate.

backend/authenticate.ts

const allowCredentials = await lookupUserPasskeys(user.id);

const result = await passlock.authorizePasskeyAuthentication({
  allowCredentials,
});

// alternatively pass the userId
// Passlock will look up the passkeys for you
const result = await passlock.authorizePasskeyAuthentication({
  userId: user.id,
});

Note

You need to use the backend authorizePasskeyAuthentication call followed by a frontend authenticatePasskey({ authenticationToken }) if you want to pass allowable credentials into the authenticate call.

Given that you already know the user ID (or claimed ID), you can look up the passkeys associated with the account and pass them to authorizePasskeyAuthentication via the allowCredentials property. As a shortcut, you can also pass the userId property instead, which Passlock will use to look up the passkeys for you.

Tip

This is especially valuable during re-authentication e.g. security critical steps.

Take GitHub as an example. You might have a personal and work account, with associated passkeys on the same device. If you are currently working on a personal project and need to perform a sensitive operation GitHub will prompt you to re-authenticate with your passkey.

By passing the list of allowable credentials GitHub can ensure that your device only offers the personal passkey and not the work passkey.

This is conceptually similar to the excludeCredentials registration option.

Handling missing device passkeys

A user may have deleted a passkey on their device, but it’s still linked in your app. When you pass the missing passkey ID via allowCredentials, the user’s device will adopt the roaming authenticator flow, assuming the passkey exists on a different device.

See handling missing passkeys.