Passkeys - Design your Solution

The What are Passkeys? article introduces passkeys and describes their main behaviors. To integrate passkeys successfully you need to understand technical limitations and then ensure that you can work around them. You can then activate passkeys logins 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 November 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 now have passkeys support. For example, Android added passkeys support in October 2022 and security patches enabled older devices to use passkeys.

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 may have incomplete 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. Applications can potentially use different APIs 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:

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 sees the passkey login screen. When the user selects the option to create a passkey, a registration authenticator runs. This example uses email verification as the registration authenticator. In the second screenshot, the user easily authenticates using a one-time password (OTP) received by email.

The user then follows prompts to create a passkey, which results in the generation of a keypair. The operating system or browser stores the private key and the application's backend stores the public key. When you use 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 built-in options from platform providers are Windows Hello, Google Password Manager and Apple iCloud Keychain. The user must first be signed into their account with the platform provider.

Microsoft Hello does not currently synchronize passkeys to other computers or devices. On macOS, the Chrome browser defaults to iCloud keychain but can also use Google Password Manager. The following example demonstrates successful passkey synchronization:

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, 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:

Users may be presented with a misleading system dialog when logging in for the first time on a new device. For example, if a user creates a passkey on Windows and tries to login on macOS they might see the following dialog. 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 out of the system dialog:

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 system dialogs.

Before triggering passkeys system dialogs you should present an entry screen to users to prepare them for the passkeys login. If a user fails to authenticate due to a missing passkey, then an exit screen should provide a recovery hint, to make it clear to the user that they can create a new passkey to recover.

Going Live With Passkeys

To enable your production users to sign in with a passkey, you simply need to add passkeys to your authentication options. All users will then see an authentication selection screen and can choose their preferred authentication method. This enables you to introduce passkeys without any users being blocked from signing in.

If you use passwords today, you might decide to go further and disable the use of passwords, to force users to sign in with passkeys. If this leads to any users being blocked, you could activate a backup authentication option, such as email verification.

The Migrating to Passkeys tutorial provides further details on techniques you can use to migrate to passkeys when using the Curity Identity Server. The tutorial explains how to manage reliability and take finer control over user experiences. A worked example is also provided, which you can run on a development computer.

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.

This article has been updated on: 2024-11-05Published: 2024-11-05

Gary Archer

Product Marketing Engineer at Curity