On this page
Web Authentication (WebAuthn) is a way of performing user authentication with the help of software or devices which can authenticate a user without a password. Things like external key-fobs or fingerprint readers can be used with this method. If you need an overview of the standard itself, have a look at the WebAuthn overview article. In this article we'll show you how to configure a WebAuthn authenticator in the Curity Identity Server. We'll also show you some common scenarios in which this type of authentication can be used.
No special configuration is required in order to enable WebAuthn authentication, so any running instance of the Curity Identity Server will suffice. The WebAuthn authenticator is bundled with the Curity Identity Server since version 6.2., so make sure that you're using at least this version.
Configuring the Authenticator
In the Authentication Profile, go to Authenticators and click on + New Authenticator button. Choose a suitable name for your authenticator and select the
WebAuthn authenticator. Then click Next to configure the authenticator.
Choose the Account Manager that the authenticator should use - this is the manager where information about users' devices will be kept. The meaning of other settings is described in the following sections.
Authenticators vs devices
The Web Authentication specification talks about authenticators, which are the pieces of software or devices used to authenticate the user (e.g. Windows Hello or an external key-fob). To avoid confusion with the Curity Identity Server's authenticators, the name
devices will be used in this document and in the admin UI settings when referring to WebAuthn's authenticators.
The mode can be set to either
passkeys-or-user-verifying-devices. The former option should be selected when you want to allow the user to authenticate with single-factor devices, such as a laptop fingerprint reader or a key-fob without a PIN number configured. The latter option is recommended, since it strengthens security further, by enforcing multi-factor devices.
Allow Registration During Login
In order to be able to log in with a WebAuthn device the Curity Identity Server need to have a device registered. During the registration process, the device creates a new credential - a pair of private and public keys. The Curity Identity Server must be aware of the created public key in order to be able to log in a user. When this option is enabled, then the registration process can be performed straight from the authenticator screen. The user can register new devices, which can subsequently be used to perform authentication. When this option is disabled then the credentials have to be created out-of-band and saved in the user's profile. This scenario is out of scope of this tutorial. The Preregister Devices in a WebAuthn Authenticator tutorial presents possibilities of achieving this.
When this option is enabled, the WebAuthn authenticator must have a registration authenticator in its prerequisites. This is an authenticator which will be used to sign in a user before they can register a WebAuthn device. This can be any authenticator, but you have to make sure that the logged-in user has an account created in the Curity Identity Server, so you will have to use an authenticator which allows registration or takes care of creating user accounts. The credentials from a WebAuthn device have to be stored in the database and must be assigned to a user account.
In the image below you can see the HTMLSQL (a plain old HTML form) authenticator used as a prerequisite to the WebAuthn authenticator.
Allow Platform Devices
Two types of devices can be used with Web Authentication - platform devices and cross-platform devices. Platform devices are single-factor so only work when the
any-devices mode is selected. They are built-in into the operating system from which the user logs in. These can be features of the computer, laptop, tablet or phone used to log in to your website. E.g. on an iOS phone this can be FaceID, on a laptop a fingerprint reader, or, on a device with Windows, Windows Hello can be used for this purpose. Cross-platform devices are things like key-fobs, which the user has to connect to their computer in order to authenticate.
When this option is enabled, then platform devices can be used to authenticate a user with the WebAuthn authenticator, otherwise only cross-platform devices can be used.
An important feature of the cross-platform devices is that, once registered, they can be used with multiple computers or browsers. The user needs to register their key-fob only once, and they will be able to log in from any computer, browser or phone which can connect to the key-fob. In case of platform devices it is actually the browser which is registered as a device (the browser acts as a WebAuthn client). So even on one computer, when the user registers a platform device, but then tries to log in from a different browser, they will have to register the new browser as another device.
Ask to Register Additional Platform Device
In situations where the user logs in using a cross-platform device, the Curity Identity Server can ask them automatically to also register a platform device. Logging in using a platform device is much simpler for the user, as they don't have to connect the external device. In order to use this option Allow Platform Devices has to be enabled as well.
Browser support for WebAuthn
Support for WebAuthn is pretty good across the major browsers and platforms, but still some features are missing sometimes. For example, at the time of writing this article, Firefox on a Mac does not support any platform devices. You should take that into consideration when testing WebAuthn, as well as when making decision about which authenticators should be available to your users. In a corporate scenario you can require your employees to use WebAuthn and have them use a concrete browser which supports your chosen device. If you want to enable Web Authentication to your public user base however, you will have to make it an opt-in option, so that users which do not want to or can't go passwordless yet, can still log in to your service.
You can have a look at the FIDO Alliance page to check the current status of browser support.
Common scenarios for WebAuthn
As WebAuthn can be used in browsers on desktops, laptops, tablets or mobile phones - and offers the possibility to authenticate a user with different devices, like key-fobs or fingerprints readers, it proves itself useful for various user authentication scenarios. The specification also provides other options which can further extend the variety of implementations - e.g. the WebAuthn device can be attested by the application, or the application can allow only for a specific type of devices to be used, for example it can accept only credentials from cross-platform devices.
Below are a few examples of common scenarios which can be used with Web Authentication, each accompanied by a demo video of the scenario implemented using the Curity Identity Server.
Log In From a Mobile Device
One common scenario will be a user logging in from their mobile device. In this scenario they can use the features of Android or iOS to be able to log in to a website without having to provide a password (once they registered the device). This scenario will work with the default settings of the WebAuthn authenticator.
In this scenario the whole process of registering and logging a user in is performed without any passwords at all. As a result there is no password stored for the user account in the Curity Identity Server. In the demo sign-in with Apple is used as a way of authenticating the user before they can register a WebAuthn device. You can follow this tutorial to learn how to set up this authentication method in the Curity Identity Server. Then you can use the Apple authenticator as the registration prerequisite for your WebAuthn authenticator. Alternatively you can allow your users to register and authenticate with a Google account, or any social account, e.g. with a Facebook authenticator.
Mixing Cross-Platform and Platform Devices
Cross-platform devices give you a different login experience. You only need to register the device once to be able to log in from different browsers - you can register from your laptop and then log in from your phone - this is not possible using platform devices. On the other hand, they slightly degrade user experience - you need to have the key physically with you every time you log in. To combine the level of security of a cross-platform device with high UX, you can allow the user to register a platform device once they have registered and authenticated with a cross-platform device.
To achieve that in the Curity Identity Server, you will have to first preregister the cross-platform device (the Preregister Devices in a WebAuthn Authenticator tutorial covers this). In your WebAuthn authenticator you should disable the Allow Registration During Login option and keep enabled options Allow Platform Devices and Ask to Register Additional Platform Device.
Another demo shows a scenario where you register a cross-platform device on a laptop and then use the same device to log in to the website on a mobile phone.
passkeys-or-user-verifying-devices mode is used, the user experience is similar. The main behaviors are explained in the using multi-factor WebAuthn devices tutorial. Screenshots are provided of built-in browser and dialog behavior when using passkeys, and some web and mobile technical differences are explained. For mobile apps that use the Hypermedia Authentication API (HAAPI), the app itself can act as the WebAuthn client, using native APIs, and the system browser can be avoided. The tutorial explains the technical configurations needed for a working setup.
The WebAuthn specification is a great way to create a secure login experience for your users, which is additionally prone to phishing attacks. Using WebAuthn can also help us transition to a passwordless web. Implementing Web Authentication in the Curity Identity Server is straightforward thanks to a dedicated WebAuthn authenticator, which can be easily set up and configured.