The WebAuthn authenticator implements the WebAuthn specification to enable strong, public key-based credentials for user authentication. Curity Identity Server supports most types of authenticator devices. The communication with the device is handled by the browser, thus the devices supported will be limited by the browser support. Current browser support can be found at the Fido Alliance Browser Support page.
Passkeys are WebAuthn credentials that require user verification and are available across different contexts/devices. As such, they can be used with the WebAuthn authenticator, in which case the Curity Identity Server ensures that only user-verifying authenticator devices are allowed (e.g. devices that authorize their usage via biometric recognition gestures).
The WebAuthn specification refers to an authentication device as authenticator. An authenticator has a different meaning in the Curity Identity Server, and thus we use the word device.
authenticator
device
The WebAuthn specification allows for many types of devices to be used for authenticating users. Devices can be grouped into two groups: platform devices and cross-platform devices. Platform devices are attached to the computer, phone or tablet, and can only used for authentication on that specific device, like a fingerprint reader or face recognition hardware. Cross-platform devices are removable devices that you can use to roam between units, like USB- or NFC keys. To make it easier for the end user to tell what is asked of them, Curity Identity Server use the terms Built-in Device for Platform Devices and Security Keys for Cross-platform devices. Since these therms are user facing, they can also be changed using the message files.
When creating a WebAuthn authenticator, there are some configuration options that can be used to alter the logic of the authenticator.
allow-registration-during-login
account-manager
Mode
passkeys-or-user-verifying-devices
any-device
Users can register and authenticate using any devices, regardless of user verification.
any-device/allow-platform-devices
Allow the user to register platform devices like Face- or Touch ID. Cross-platform devices are always allowed.
ask-to-register-additional-platform-device
platform-device-cookie-name
When allowing registration for an authenticator, a prerequisite authenticator is mandatory to configure. This authenticator is used to establish a subject by which lookup an account using the configured Account Manager. If passkeys-or-user-verifying-devices is enabled, the authenticator doesn’t place any restriction on the device type, and the different options should be presented via a browser-specific user interface. If any-device/allow-platform-devices is enabled, the user will get a choice to register either a built-in device, or a security key.
If the user authenticates using a cross-platform device and no platform device has been registered for the user’s current browser, the authenticator can be configured to ask the user to register an additional platform device. Platform devices are often more convenient for the user to use, so by allowing the addition of such device it might make the login process a lot simpler for the user. If the user decides to say no to this request, they have three options:
No, not now
Don't ask me again for this browser
Don't ask me again
webauthn.dontAskToRegisterAdditionalPlatformDevice
This behavior can be disabled altogether by setting ask-to-register-additional-platform-device to false.
false
Note
Since each browser is seen as a separate client by the WebAuthn API, platform devices are not necessarily shared, and might need to be registered once per browser.
The WebAuthn specification leaves it open for browsers to require user interaction before using platform devices like fingerprint or face recognition. Currently, the only browser that requires user interaction is Safari, so when a user is authenticating and has such devices registered, they will have to click a button to start the authentication process. All other browsers automatically start the authentication. If this changes, and other browsers start requiring interaction, or if Safari drops the requirement, the template authenticators/webauthn/js/common-js.vm contains the logic to detect the need to show the button. Overriding this template allows the developer to decide when to require interaction.
authenticators/webauthn/js/common-js.vm
The WebAuthn authenticator supports the Hypermedia Authentication API on iOS devices. HAAPI model contains two WebAuthn specific client-operation - webauthn-registration and webauthn-authentication. Android and web clients should utilize the fallback mechanism triggering an external browser flow in the form of an error action.
client-operation
webauthn-registration
webauthn-authentication
The iOS domain association allows for the creation of a connection between Identity Server and mobile application for WebAuthn key generation. To serve the apple-app-site-association (association) file from Identity Server, application details needs to be configured in environments/environment/service/zones/{appropriate zone}/mobile-app-association/ios-app-configuration alternatively the file can be placed in dist/usr/share/webroot/.well-known/ directory.
apple-app-site-association
environments/environment/service/zones/{appropriate zone}/mobile-app-association/ios-app-configuration
dist/usr/share/webroot/.well-known/
The Android domain association allows for the creation of a connection between Identity Server and android application for WebAuthn key generation. To serve the assetlinks.json file from Identity Server, application details needs to be configured in environments/environment/service/zones/{appropriate zone}/mobile-app-association/android-app-configuration alternatively the file can be placed in dist/usr/share/webroot/.well-known/ directory.
assetlinks.json
environments/environment/service/zones/{appropriate zone}/mobile-app-association/android-app-configuration
The following limitations are known about the WebAuthn authenticator