Passkeys best practice for the web

The following best practice recommendations are designed to help you create the best passkey experience for your users when using Authsignal’s Web SDK.

​

Presenting sign-in options

When using passkeys for signing in to an account, we recommend presenting a username input (e.g. email) and optionally an additional button (e.g. “Sign in with passkey”).

If the username input is configured for passkey autofill then the user will only be shown a passkey if they have one available on the device.

If no passkey is available on the device, then the user can enter their username (e.g. email) and press continue to trigger a backup authentication flow driven off their username (e.g. email OTP).

Alternately, if the user decides to click the “Sign in with passkey” button, you can attempt to initiate passkey sign-in based on whatever credentials are available. In this scenario the browser may show multiple passkeys for different accounts e.g. if the device is shared. The browser may also show a fallback option such as a QR code if no passkey is available on that device.

The browser’s QR code option can lead to a confusing UX if the passkey sign-in is triggered by the website automatically rather than by an explicit user interaction. We recommend triggering this option only from a “Sign in with passkey” button or similar.

​

Increasing passkey adoption

Transitioning your users from traditional sign in methods, like passwords, to passkeys can be a big change. To help with this transition, you can provide a prompt to encourage users to create a passkey when they sign in.

As this may be the first time your users have encountered passkeys, it’s important to provide a summary of what passkeys are and how they can benefit them.

​

Improving passkey coverage across devices

Whilst many passkeys are available across devices, like ones stored in iCloud Keychain, some passkeys are device-bound. For example, a passkey created on a desktop browser may not be available on a mobile device.

If a user authenticates on a device without a passkey, you can prompt them to create one in a similar way to the example above.

Depending on your needs, you can alter the frequency of these prompts to ensure they’re not too intrusive. This could be a timed cooldown or based on the user’s behaviour.

​

Providing a back up when passkeys are unavailable

An often overlooked aspect of passkeys is that you cannot guarantee that a user has access to their passkey. This could be for reasons such as the passkey being bound to a different device or the user has deleted the passkey from their credential manager.

To mitigate this, you should provide a fallback authentication method, like email OTP, that users can use if they don’t have access to their passkey.

​

Displaying passkeys

As users may have multiple passkeys, it’s useful to display them in a distinct way. A passkey user authenticator contains the webauthnCredential.aaguidMapping object. The name field will contain the name of the credential manager, e.g. iCloud Keychain, where the passkey is stored. The svgDark/svgLight fields contain the SVG icons for the credential manager.

In the area of your application where user’s manage their authentication options, you can utilize these fields to display the user’s passkeys: