Passkeys best practice for the web
Learn how to create the best passkey experience for your users on 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. If you are using the pre-built UI, these are implemented for you.
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.
A user is prompted to add a passkey after signing 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.
An example of a prompt to add a passkey to a device.
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.
A user given the option of using Email OTP instead of a 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:
Displaying a list of the user's passkeys.
Whilst the webauthnCredential.aaguidMapping
object is available for most passkeys, it’s not guaranteed to be present. As an alternative, you
can use the webauthnCredential.parsedUserAgent
object to display details about the device the passkey was created on.
Was this page helpful?