Re-authenticating users locally using the userVerification property

Enforcing local re-authentication using biometrics or device passcodes.

Pass the userVerification property during a registration or authentication call to force the user to re-authenticate locally, or explicitly bypass local re-authentication.

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

await authenticatePasskey({ userVerification: "required", ... })

Default
Safe

import { exchangeCode } from "@passlock/server";

const result = await exchangeCode({ code, tenancyId, apiKey });

if (result.passkey?.userVerified) {
  // all good
}

import { exchangeCode } from "@passlock/server/safe";

const result = await exchangeCode({ code, tenancyId, apiKey });

if (!result.success) {
  console.error(result.error.message);
} else if (result.value.passkey?.userVerified) {
  // all good
}

User verification options

Choose from one of these options:

preferred: This is the default during registration and authentication. The device will attempt to re-authenticate the user if technically possible, and frictionless. However if this can’t be achieved, for example a MacBook is in clamshell mode, the device will continue to present the passkey anyway.
required: The device will attempt to use something like Face ID/Touch ID but if it can’t, it will fall back to prompting the user for their device password. Either way, the device won’t present the passkey unless the user has re-authenticated.
discouraged: The device won’t re-authenticate the user, so this option results in the least friction.

Checking the verification status

When preferred is used, it’s useful to know whether the user did actually re-authenticate locally. The resulting Principal includes a passkey.userVerified: boolean property to reflect the status.

Preferred, required or discouraged?
Which option to choose?

In most cases we believe the default, preferred is best. You can always perform some additional verification e.g. sending a one-time code if the user didn’t re-authenticate locally.

However if the user has successfully authenticated you might choose to set a secure session cookie on their machine, in which case discouraged could strike a good balance between friction and security.

required is obviously the most secure and best used for security related operations, e.g. account or billing changes.