Supporting legacy applications and progressive passkey rollout

Note

If you haven’t already done so, please check out the terminology section in the authentication patterns guide.

“Legacy” is maybe a bit harsh, we’re referring to a live app with an existing user base. In this scenario you would maintain your existing authentication mechanisms, but add passkeys as additional authenticators, or as a secondary or step-up authentication mechanism.

Passkey registration

Assuming the user is already signed into your system, prompt them to add a passkey.

You might want to allow them to register more than one passkey given that they may want to sign in from multiple devices that are not synced to the same cloud account.

For example they might want to sign in on their personal device and create a passkey, then sign in on their work machine and register another passkey.

In this scenario, the excludeCredentials registration property is especially important.

Passkey authentication

If your existing/legacy authentication process is a single step flow, you would most likely want to present a “Sign in using your passkey” option alongside the other options.

Note

Whilst we don’t recommend it, WebAuthn autofill is also an option for single step login flows

Two-step flow

If you use a two-step flow, you would first lookup any associated passkeys based on the user’s username. i.e. use the username to fetch the local user ID joining against any linked passkeys.

If the user has one or more passkeys associated with their account, you can present a “Sign in using your passkey” button and prefill the allowCredentials property.

If they haven’t added a passkey, just present them with one of the valid primary authentication mechanisms.

Rolling migration

If you’re using password based authentication, you’re probably aware of the issues associated with passwords. You may decide to migrate users across to passkeys, with a fallback e.g. email or SMS based one-time codes for users whose devices don’t support passkeys.

Autofill

WebAuthn autofill is designed for just such a scenario, but we don’t recommend it unless your user base is tech-savvy.

We recommend you first move to a two-step authentication flow, prompting users for their username/email, followed by their passwords.

This will allow you to identify if the user account already has a passkey associated with it. If it does, you’d display a “Sign in using your passkey” type button as described above.

If the user has not added a passkey to their account, you’d continue to authenticate using passwords (and any secondary authentication), check that their browser supports passkeys, then prompt them to add one. Basically you don’t let them move on until they’ve added a passkey.