Using Multi-Factor WebAuthn Devices

Starting from version 8.0 of the Curity Identity Server, a new mode is available on the WebAuthn authenticator, called passkeys-or-user-verifying-devices. This enables you to enforce usage of multi-factor WebAuthn devices, such as Google passkeys, Apple passkeys, or Yubikeys with a PIN configured:

When using WebAuthn, a cryptographic signature is used as the main authentication factor. This is combined with a second factor of something the user knows, such as a PIN or password, or something the user is, like a biometric. This protects against lost or stolen WebAuthn devices, and can avoid the need for any other authentication factors in many use cases. It also enables users to provide their identity in the same way, across all applications where WebAuthn is supported.

Web Clients

Two user journeys are involved, to first register a device, and then to use it for authentication. For a browser based client, the registration experience first involves prompting the user to create a passkey, using the system dialog for the operating system:

If you instead want to register a Yubikey with a PIN, first use a tool such as Yubikey Manager to configure the device with a PIN. When registering the device against a web application, select the Try another way option, then insert the device in a USB port and enter its PIN when prompted:

In the Curity Identity Server, the following screen is presented after successful creation. The passkey or user verified device can then be used for authentication. This is done by simply inputting the second factor, typically a PIN, password or biometric, on every login.

The passkey created for the web application is stored by an operating system or browser specific password management service, such as the Google Password Manager or Apple iCloud Keychain. As long as you are signed in with your Google / Apple account on both devices, the same passkey will then be synchronized across devices. If you login to the web application from a mobile browser, this prevents the need for re-registration.

Mobile Browser Clients

Passkeys and user verified devices can be registered in an equivalent way for mobile applications as for web applications. By default the system browser is used, which invokes system dialogs. The following system activity is presented on Android when registering a device:

The equivalent option on iOS encourages you to select a passkey, though a later screen in the below flow allows you to select an alternative device type, such as a Yubikey:

Any supported option can then be used, to create a passkey or register a user verified device. This will require a user gesture, such as providing a biometric or PIN, or using the device's NFC or USB options to register using a Yubikey. The same user gesture must then be provided every time the user authenticates.

Mobile Native Clients

Mobile apps can also use Android native or iOS native APIs to implement WebAuthn. This work is done for you when using the hypermedia authentication API (HAAPI). User choices are then rendered in native screens, and no browser screens are shown:

HAAPI native screens then hand control over to system dialogs, for registration:

Similarly, the user also authenticates using a system dialog:

Use of native WebAuthn APIs requires some extra configuration, to enable the app to receive the authorization response from the device and provide it to the Curity Identity Server for verification. See the HAAPI WebAuthn native configuration tutorial for details on the technical setup. The following short videos demonstrates the native user experience when using passkeys on iOS:

Testing Resources

Browser, operating system and mobile support for passkeys and user verified devices is continually changing. See documents such as FIDO2 WebAuthn supported platforms for the latest state. For the latest technical information on behaviors supported in the Curity Identity Server, see the authentication service admin guide.

Before changing code in your applications, you can use the following tools and code examples to run OAuth flows that use WebAuthn passkeys and user verified devices on web and mobile platforms:

• OAuth Tools as a Web Client
• Android HAAPI Client
• Android AppAuth Client
• iOS HAAPI Client
• iOS AppAuth Client

Migrating Users to WebAuthn

Using WebAuthn in real world business scenarios will often require a migration design. Firstly, in many use cases you will not be able to force all users to update to WebAuthn. You may therefore need to make it optional, and support different authentication methods for different users.

In the Curity Identity Server, registered WebAuthn devices are saved to a data store under a devices schema, that links to the owning user account. When migrating existing users to use passkeys or user verified devices, you typically need to ensure that your APIs receive the existing identity in access tokens, which map to the user's business resources.

For details on how to manage these topics, see the migrating to passwordless tutorial, which describes how to use authentication actions to present options to users, then link WebAuthn keys to an existing account.

Conclusion

WebAuthn multi-factor devices provide a highly secure, yet user-friendly experience. It can avoid the need to manage multiple factors, and also enables users to manage their identity in the same way across many internet applications. WebAuthn should be adopted as part of an OAuth based flow. This ensures that, after login, applications can use access tokens to securely interact with APIs. Doing so results in a modern end-to-end security architecture.