How to set up two factor with WebAuthn OTP

From version 5.8, we add support for Web Authentication (WebAuthn) as another second factor method besides Email, SMS, Authenticator, and OS2faktor. The new method offers clients such as Windows Hello, Apple’s Touch ID, and FIDO2 keys as a second factor option.

OTP Connection settings


Select the "WebAuthn" as the "Second factor method(s)" of the OTP authentication connection you are configuring.

web-authn-configuration-select-otp-method

When you select the WebAuthn method, you can configure several settings:

web-authn-configuration-settings

The disabled settings are kept for future versions. For now, you can configure the "Authenticator type" and "Prompt timeout" settings:

  • "Authenticator type": This setting specifies what type of authenticators (aka devices) that your users can use.
    • "Platform": This option only allows platform/internal authenticators that are implemented directly on the WebAuthn client devices such as a fingerprint scanner built into a smartphone (e.g. TouchID or Windows Hello). This means that you cannot use any other devices - than the one you have registered as second factor - to log in to your applications.
    • "Cross Platform": This option only allows cross-platform/external authenticators such as hardware security keys (e.g. FIDO2 keys). If you use a Yubikey to register for the second factor, you can plug that key in to any compatible machine and log in to your applications.
  • "Prompt timeout": The time (in seconds) that you have to respond to a prompt by interacting with your WebAuthn-compatible devices when you need to onboard or authenticate.

WebAuthn settings are represented in the OTP authentication connection’s json format for REST API as follows:

Set up two factor authentication with WebAuthn OTP


After completing configuration for OTP authentication connection, you can set it as a second factor of an authentication connection such as U&P, SAML 2.0, WSFederation etc.

web-authn-configuration-set-as-second-factor

Onboarding


After you performed a first factor login, Safewhere Identify will ask you to register a WebAuthn authenticator:
web-authn-registration-register

Click on "Register" button and the system prompts you for a previously configured authorization gesture (PIN, biometric, etc.):

  • If the authenticator type is "Platform" and you, for example, have set up Windows Hello's PIN, Identify will show a Windows Hello PIN dialog to ask you for your PIN.web-authn-registration-register-clicked
  • If the authenticator type is "Cross platform" and you e.g. have a FIDO2-compliant Yubikey, Identify will show a Windows dialog to ask you to insert the key and touch it.web-authn-registration-register-clicked-fido2keys

After onboarding succeeds, the system will ask you to save a recovery code as a backup second factor method. You need tick the "I have safely recorded this number" checkbox and click the "Continue" button to finish onboarding.

web-authn-registration-recovery-code

Authentication


After you have registered your WebAuthn authenticator, the next time you log in, the system will prompt you for an authorization gesture (PIN, biometric, etc.). If you are using Windows Hello PIN, the prompt will be:

web-authn-authentication-windows-hello-pin

If you are using a FIDO2 key, the prompt will be:

web-authn-authentication-fido2_keys

If you are not using or do not have your authenticator devices with you, you can click "Cancel" to use your recovery code instead.

web-authn-authentication-recovery-code

Offboarding


As an administrator, you can navigate to the Security tab on the Admin Portal and reset WebAuthn registrations for your users.

web-authn-off-boarding-webauthn-of-a-user

You can also offboard yourself from the My Profile page:

web-authn-off-boarding-webauthn

Hosted forms


Identify supports hosted forms for all the WebAuthn views. You can find, enable, and customize these views from the Admin portal:

  • Onboarding WebAuthn view
    web-authn-hosted-form-enable-webauthn
  • Authentication WebAuthn view
    web-authn-hosted-form-login-with-webauthn
  • WebAuthn common errors view
    web-authn-hosted-form-webauthn-error

Security settings


Per the WebAuthn specification, the attestation is how authenticators prove to the relying party that the keys they generate originate from a genuine device with certified characteristics and establish a hardware root of trust. Identify provides you an ability to configure your instance to collect and validate attestation certificates.

webauthn-security-settings

Although performing attestation is good for security purposes, it does come with some drawbacks. As per Yubico's documentation:

If your service does not have specific needs for attestation information, well defined policy for what to do with it and why, you should not verify authenticator attestations. The reasons for this is that it takes more work for the RP to do, your users may not be able to use the authenticator(s) they have, and you risk being incompatible with future authenticators unless you keep your attestation certificate store up to date.

Therefore, verifying authenticator attestations is disabled by default in Identify. When this setting is true, Identify verifies authenticator attestations against Fido Metadata to enhance security.

The validation process needs to download metadata from external locations. To improve verification time, Identify provides you another setting to prefetch and cache metadata from the Fido Metadata services at startup time as well as after every 24 hours. You should only enable it for instances that need to use WebAuthn since prefetching data does cause overhead to your server.

For the FIDO Alliance Metadata Service, to retrieve metadata or TOC (Table of Contents for all metadata statements), you will have to first register for a MDS Access Token. You can visit https://fidoalliance.org/metadata/ for more detail about this metadata service.

Known issues


Currently, only three main browsers support Web Authentication:

  • Chrome
  • Firefox
  • Edge Chromium (although the old Edge browser has support for WebAuthn to some extent, it no longer receives updates)

As a side note, Safari 14 will have full support for WebAuthn as well. To see a full list, visit this website.

WebAuthn is still in its early stage of adoption, so there are still known issues. Below is a list of known issues that you should check out before rolling out WebAuthn to your users:

  • Count down is not shown while Identify is prompting users for gestures.
  • Browser: Firefox browser on Windows 10
  • Description: The countdown message (which is highlighted in the image below) does not count down and the prompt shows until you finish interacting with your WebAuthn authenticator or cancel.
    web-authn-know-issues-time-out-registration
    web-authn-know-issues-time-out-authentication
  • You cannot onboard platform authenticators in incognito or InPrivate browsers.
  • The WebAuthn second factor method requires users to be created in Identify's user store. Therefore, you need to set "Update unknown users from login" to Yes for the first factor authentication connection. This action is not necessary if the authentication connection is done via Username & Password.
    web-authn-know-issues-set-update-unknow-user