WebAuthn

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. The WebAuthn specification calls an authenticator device authenticator. An authenticator has a different meaning in the Curity Identity Server, and thus we use the word device.

Device Types

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.

Configuring a WebAuthn authenticator

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
    • Toggle to enable registration for the authenticator. If disabled, none of the registration possibilities will be available, and the authenticator device will have to be registered out of band.
  • account-manager
    • An account manager holding the accounts that have the devices, and if registration is allowed, where to store new devices.
  • allow-platform-devices
    • Allow the user to register platform devices like Face- or Touch ID.
  • ask-to-register-additional-platform-device
    • If a user authenticates using a cross-platform device, ask the user if they want to register an additional platform device.
  • platform-device-cookie-name
    • The name of the cookie to store information that a platform device is already registered for this browser.

Registering devices

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 allow-platform-devices is enabled, the user will get a choice to register either a built-in device, or a security key.

Adding additional platform devices

If the user authenticates using a security key 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
    • This option will prompt the user again next time they login using a security key
  • Don't ask me again for this browser
    • Will set a cookie in the browser, and the third will set an attribute to the account so the user won’t be prompted again in any browser.
  • Don't ask me again
    • Will apply for all authenticators using the same account. The attribute used to store this information is webauthn.dontAskToRegisterAdditionalPlatformDevice.

This behavior can be disabled altogether by setting ask-to-register-additional-platform-device to 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.

User Interaction for platform devices

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 starts 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.