Passkey Registration

The registration section of the quickstart guide covers the basics, so we’ll focus on some more advanced aspects of passkey registration 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 passkey id (authenticatorId) to identify the user.

Testing for passkey support

Most devices and browsers now support passkeys, albeit with a few quirks. However we can’t assume support is universal.

Before prompting the user to register or authenticate with a passkey you should call isPasskeySupport(): boolean. Alternatively test for the PasskeysUnsupportedError error during a registration call:

import {
  isPasskeySupport,
  PasskeysUnsupportedError
} from "@passlock/client/passkey";

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

try {
  const result = await Passlock.registerPasskey({ ... })
} catch (e) {
  if (PasskeysUnsupportedError.isPasskeyUnsupportedError(e)) {
    throw new Error("Bad news...")
  }
}

Biometric verification

Enforce user verification by passing the userVerification option:

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

For more information see the dedicated user verification guide.

Testing for an existing passkey

To prevent the user from creating multiple passkeys on a device (for the same account), pass the existing passkey ids during the registerPasskey call:

import * as Passlock from "@passlock/client/passkey";
import * as PasslockError from "@passlock/client/error";

// from your backend database
const excludeCredentials = [existingPasskeyId];

try {
  const result = await Passlock.registerPasskey({ excludeCredentials, ... });
} catch (e) {
  if (PasslockError.isDuplicatePasskey(e)) {
    alert("You already have a passkey on this device")
  }
}

You should already know the passkey ids associated with a user because this is how you link the passkey to an account during authentication.

Why is excludeCredentials needed?

Imagine this scenario:

1. A user has registered a passkey using their personal smartphone.
2. They want to sign in to your app using their work computer. This computer is not linked to their personal iCloud account, therefore there is no local copy of the passkey on the device.

They can use the roaming authenticator flow to sign in from their work computer, but they would need to do this every time. To reduce friction, you might want to allow them to register more than one passkey. One linked to their personal device/cloud account, and one stored on their work machine.

The user would sign in using the roaming flow, then register an additional passkey which is stored on their work machine. Next time they want to sign in from the work computer they can use the local passkey on that machine, avoiding the overhead of the roaming flow.

They would end up with one passkey on their personal devices, and one on their work machine.

However there is nothing to stop a user registering multiple passkeys synced to the same cloud account. This could be very confusing becuase during authentication, the device would ask them to choose from multiple passkeys, potentially with the same name!

To prevent this, the WebAuthn specification allows you to pass a list of existing passkey ids during the passkey registration. If the device recognises one or more of the ids it will return an error.

This solves the problem described in this scenario because although the original passkey id will be shared with the work computer during registration, it won’t generate an error as the passkey is not present on that machine. However if the user tries to register another passkey on their personal smartphone the device will say “hey, you already have a passkey”.

Attestation

Attestation is an advanced concept which essentially allows you to obtain information about the authenticator (device) generating the passkey. If you want to restrict users to a list of approved platforms, attestation can be used for this.

Note: Passlock does not currently support attestation, but it will be introduced at a later date.