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

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

  • 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 as the second factor, you can plug that key in to any compatible machine and log in to your applications.
    • Unspecified: This option allows both platform and cross platform authenticators. Safewhere Identify asks users to register Platform authenticators first. If they choose to not register Platform authenticators, they will be asked to register Cross Platform authenticators.
  • Attestation conveyance type: This setting specifies whether Safewhere Identify wants to receive the attestation statement of an authenticator while registering a second factor.
    • None: This option indicates that Safewhere Identify is not interested in an authenticator attestation statement. The values of AaGuid and CredType of the stored credential(used to do authentication) will look like below.
      web-authn-registration-attestation-conveyance-none
    • Indirect: This option indicates that Safewhere Identify prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements.
    • Direct: This option indicates that Safewhere Identify wants to receive an attestation statement as generated by the authenticator. The values of AaGuid and CredType of the stored credential (used to do authentication) will look like below (same for Indirect).
      web-authn-registration-attestation-conveyance-direct-indirect

    Note: CredType is WebAuthn Attestation Statement Format Identifier.

  • Acceptable attestation types: This setting specifies that Safewhere Identify limits some authenticators that are allowed to do registration. Each authenticator has its own WebAuthn Attestation Statement Format Identifier value.
    The list of WebAuthn Attestation Statement Format Identifiers that each Acceptable attestation type supports are:

      • none
        • Attestation types supported: None.
      • packed
        • Attestation types supported: Basic, Self, AttCA.
      • tpm
        • Attestation types supported: AttCA.
      • android-key
        • Attestation types supported: Basic.
      • android-safetynet
        • Attestation types supported: Basic.
      • fido-u2f
        • Attestation types supported: Basic, AttCA.
      • apple
        • Attestation types supported: AnonCA.

    Below examples illustrate the use of this setting:

    • To only allows cross-platform/external authenticators such as hardware security keys (e.g. FIDO2 keys) to do registration:
      web-authn-registration-attestation-acceptable-attestation-types-allows-tpm-devices
    • To allow all kinds of authenticators to do registration:web-authn-registration-attestation-acceptable-attestation-types-allows-all-devices
  • User verification: User verification can take various forms of authorization gesture, such as password, PIN, fingerprint, biometric, etc. The point is to distinguish one user from any others, i.e., uniquely identify the user.
    • Discouraged: This value indicates that Identify does not want user verification employed during registration or authentication (for example, to minimize disruption to the user interaction flow).
    • Preferred: This value indicates that Identify prefers user verification for registration or authentication if possible, but will not fail the operation if the response does not have the user verification.
    • Required: This value indicates that Identify requires user verification for registration or authentication and will fail the operation if the response does not have the user verification.
  • 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.

Note: The Register with resident key setting is not applicable in Identify because Identify does not support the usernameless and passwordless login use cases. Currently, Identify only uses WebAuthn as a second factor method.

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 Safewhere Identify 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:

  • Countdown 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-registrationweb-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
  • The WebAuthn registration using Windows Hello (Pin, Face or Fingerprint) fails because the attestation format in the returned AttestationObject is always none although Attestation conveyance type is Direct or Indirect.

    web-authn-know-issues-attestation-always-none-on-firefox

    • Our expectation is that the attestation format in the returned AttestationObject must be tpm.
  • Registration and authentication are not supported on Chrome for iOS. You must use Safari 14.web-authn-not-support-for-ios