Passkeys - Design your Solution

The What are Passkeys? article introduces passkeys and describes their main behaviors. To integrate passkeys successfully you need to understand what is supported, then take control over the technical behaviors. This enables you to activate passkeys while your entire user base continues to reliably sign into your apps.

This article is kept up to date with the currently supported passkey behaviors, including limitations. The current version is accurate as of February 2024. In most use cases, the limitations described are only minor and there should be no current technical barriers to rolling out passkey logins.

Supported Operating Systems

The operating system is the first factor that determines whether users can run passkey logins. Most modern operating systems introduced OS-level passkey APIs around the end of 2022 and most user devices have been updated with passkeys support. For example, Android device support was introduced in October 2022 and could then work on older devices.

Users can use external security keys, like keyfobs configured with a PIN, as passkeys. More commonly though, platform passkeys are more convenient since any user who has an account with Google, Apple or Microsoft can easily use them.

These days a considerable majority of your users run on supported operating systems. To use platform passkeys the user may need to be signed into an account from a provider, such as Google, Apple or Microsoft. On Windows, you must be using Hello as a prerequisite. Microsoft indicates that the number of consumers using Hello to sign in to Windows 10 devices reached 84.7 percent in 2019.

For the minority of your users who do not meet passkeys prerequisites, provide an alternative login method. The following screenshot shows a login screen that includes a backup option for email verification:

Supported Browsers

In most OAuth-secured apps, passkey logins use the system browser. Therefore the browser is the next main factor that determines whether users can run passkey logins. The browser must also run on an operating system that provides passkey APIs. For example, the Chrome browser on Windows integrates with the Hello protocol of the Windows operating system. The following major desktop browsers all support platform passkeys starting with the versions indicated:

Users can also run various types of web browsers on mobile devices. OAuth-secured mobile apps often use special integrated forms of the system browser, the Chrome Custom Tab on Android, or the ASWebAuthenticationSessionWindow on iOS. The following list of major mobile browsers also support platform passkeys:

Passkey logins that use external security keys are managed solely by the browser and its FIDO2 support. You can use these devices on all of the above browsers, on any platform including Linux. Minority browsers have reduced passkeys support, especially on mobile. You can see a more complete list of these, along with their internet usage, on the Can I use? website.

Supported Native Applications

Desktop or mobile apps can use the operating system's native SDKs to integrate passkey logins. Different APIs can potentially be used for platform passkeys and external security keys since the latter could be built with any FIDO2 SDK. Typically, passkey SDKs are very recent and new application builds are needed. The built apps can then run on older operating system versions shown here:

If you are using the Curity Identity Server, the Hypermedia Authentication API (HAAPI) enables your native apps to implement OpenID Connect in an API-driven way. An app plugs in the HAAPI UI SDK, which processes API responses and renders native screens. This enables a pure native passkeys experience in your mobile apps.

Passkeys Account Recovery

Once you understand that passkeys work for most users, and you have a backup authentication option for other users, you can enable passkey logins. If required, allow your users to gradually opt-in to using passkeys. Your next concern is likely to be the following question:

To best answer this question, understand how passkey registration works. The registration ceremony requires the user to authenticate. Email or phone verification is often the most convenient option, though higher security authentication methods such as digital wallets could also be used.

The first screenshot below shows an example where the user chooses to register a passkey. When the user clicks the register link, authentication is triggered. This example uses email verification as the authentication method. In the second screenshot, the user easily authenticates using a one-time password (OTP) received by email.

The user is then prompted to create a passkey, which results in a keypair being generated. The private key is stored by the operating system or browser, and the public key is stored in the application's backend. When using OAuth, the backend is your authorization server.

A key point to understand is that the backend should be able to store multiple passkeys for each of your users. By default, each user only performs the registration ceremony once. Yet it is possible to re-run the registration ceremony and register additional passkeys if the original one somehow gets lost or deleted. This enables you to design for any lost passkey scenario, such as those listed below:

Passkeys and Roaming

Users often log in to applications with more than one device, such as their laptop and their smartphone. Therefore passkey logins need to work across multiple devices. Currently, external security keys are the most portable type of passkey, whereas platform passkeys are not always shareable.

Ideally, a user should also be able to create a platform passkey and then sign in with it on all devices. For example, a user might register a passkey in the Edge browser on their work Windows computer, then use the same passkey in Safari on their home MacBook, and in Chrome on their Android device. Yet currently this is not always possible, so roaming is only partially supported:

Password Managers

When using platform passkeys, the operating system can use a cloud service called a password manager to synchronize passkeys to other devices. The most widely used options are Google Password Manager and Apple iCloud Keychain. The user must first be signed into their Google or Apple account.

Microsoft Hello does not currently synchronize passkeys across devices. On macOS, the Chrome browser defaults to Google passkeys, but can also use Apple passkeys. If users choose the default Google option their passkey is not synchronized. The following examples work successfully:

Yet outcomes such as the following are also likely to occur, e.g. if the operating system APIs provided by one vendor do not synchronize passkeys issued by another vendor:

Users can run specialist third-party password managers such as Bitwarden to resolve passkey synchronization limitations. These can be a good choice in scenarios where you have control over user environments.

Cross Device Authentication

In addition to password managers, another way to share passkeys is using FIDO Cross Device Authentication (CDA), which uses the Client to Authenticator Protocol (CTAP). This protocol is implemented by the operating system separately from its support for platform passkeys. A working CDA flow also requires support from browsers or native clients.

The flow consists of a CDA client that interacts with a CDA authenticator using Bluetooth. Most commonly, the CDA client is a desktop browser login form and the CDA authenticator is a mobile device. The following flows are then supported:

The CDA authenticator renders a QR code, which the user scans with their mobile device's camera. The passkey on the mobile device is used to digitally sign material that is returned to the desktop login form, to enable a passkeys login:

All of the main operating systems support passkeys with Cross Device Authentication, for the main browsers listed earlier.

Up-to-date Linux desktop operating systems, such as Ubuntu 22.04, should also support CDA with the same browsers. Due to the many possible deployments, a complete list of Linux supported environments is not published here.

There is a CDA enhancement called persistent linking, where the CDA client does not require the user to scan a QR code on every login. Currently, only Android CDA authenticators in Chrome and Edge CDA clients support this option.

Passkeys User Experience

A major stakeholder concern when introducing passkeys is the user experience. If a user only runs your apps on a single device, then both the registration and authentication steps are extremely simple and user-friendly, even for non-technical users. Each user simply clicks continue and then provides their familiar device credential as a second factor.

When using platform passkeys, operating system APIs include support for discoverable credentials, which contain a user ID. Users then use passkey autofill, which improves the UX further, especially if the user might otherwise forget their username. You may hear various aliases for discoverable credentials, including usernameless, conditional UI or WebAuthn resident keys. The following table summarizes the current support, for the browser versions listed earlier:

Yet some passkey system dialogs can confuse users. For example, some users may not know how to scan a QR code, so could be confused by a dialog that presents one. Users may also be presented with a misleading OS dialog when logging in for the first time on a new device. For example, if a user creates a passkey in Windows and then tries to use a passkey on macOS, they may be presented with the following choices. Yet in this example, the user's existing passkey is not stored on either a mobile device or an external security key. The user is therefore likely to cancel:

To best manage usability, you should be aware of the FIDO Alliance UX Guidelines for Passkey Creation and Sign-ins. In particular, the authorization server should allow you to customize messages displayed to the user before and after the OS dialogs.

You might choose to present users with a hint message containing the following text when a passkey login is selected. This might encourage a user running a minority browser to switch to a mainstream one:

Similarly, if a user cancels a passkeys login, you might use a recovery hint message like this:

Phasing Out Password Logins

If your current user base authenticates using passwords, you can upgrade them to passkeys in a phased manner, then avoid showing password options to passkey users. You can manage this dynamically without impacting other users who want to continue to sign in with passwords. When using an authorization server, the best way to manage this is to identify a user before they authenticate, by prompting for an email or username. A cookie is then set, to enable this value to be auto-populated for all subsequent logins.

Once the user is identified you can run some authorization server logic to look up the user's public keys. If one or more exist, then you might choose to route that user directly to passkey logins. Alternatively, you could reduce the user's authentication options by removing the password option while still enabling a backup authentication method, such as email verification.

Passkeys Tutorial

The Migrating to Passkeys tutorial explains how to manage a controlled migration from passwords to passkeys when using the Curity Identity Server. A worked example is provided that you can run on a development computer, to practice the reliability techniques from this article. The example covers an entire user base, where some existing users continue to authenticate with passwords while others upgrade to passkeys.

Conclusion

Adding passkeys to your login options provides significant business benefits. Passkeys already have wide platform support. This is continually improving, and users are becoming accustomed to the system dialogs. There are some current technical limitations, but these are not difficult to overcome.

The optimal way to integrate passkeys is to do so within an OAuth architecture. Implementing passkeys should require only minimal work, after which you also have access to other future-facing authentication methods, such as digital wallets. After authentication, your clients receive a correctly issued access token that can be sent to your APIs.