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.

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.

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.

  • Mode

    • passkeys-or-user-verifying-devices

      • Users must register and authenticate using a passkey or another user-verifying device, regardless of its type.

    • 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

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

Adding additional platform devices

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

Hypermedia Authentication API

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.

iOS Domain Association

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.

Android Domain Association

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 $IDSVR_HOME/usr/share/webroot/.well-known/ directory and file generation disabled by configuring environment/services/service-role/<service-role>/disable-android-assetlinks-generation.

Known limitations

The following limitations are known about the WebAuthn authenticator

  • Native HAAPI support is limited to iOS and Android clients. Web clients are currently not supported using HAAPI, and should use the external browser flow as a fallback mechanism.