FIDO2 Sample Relying Party Web App

The FIDO2 Sample Relying Party Web App is a stand-alone component that allows you to test and simulate the end-to-end capabilities of the FIDO2 FIDO2 is a standard for strong authentication in the web. FIDO2 is comprised of the WebAuthn specification and the corresponding Client-to-Authenticator Protocols (CTAP). It allows users to use their devices and authenticators to authenticate to online services without the need for entering a password. It can be accomplished both on their desktop and mobile environments. ceremonies: registration and authentication. Additionally, the FIDO2 Sample Relying Party Web App can also deregister all the user keys from the FIDO2 Server. This allows you to simulate the FIDO2 flows before you implement them in your Relying Party web application for the Production environment.

On the client side, the FIDO2 Sample Relying Party Web App demonstrates the interaction between the web browser and the available FIDO2 authenticators.

On the back-end side, the FIDO2 Sample Relying Party Web App forwards the data structures that were processed by the authenticator to the OneSpan Trusted Identity platform. These data structures are then further processed and validated by the FIDO2 Server.

For more information about FIDO concepts, refer to the specifications and technical glossary provided by the FIDO Alliance.

Prerequisites

Before you can start using the FIDO2 Sample Relying Party Web App, ensure that FIDO2 has been enabled for your tenant.

For more information about how to configure FIDO2 for the Sandbox environment, see FIDO2 in the Sandbox environment.

Once FIDO2 has been enabled, you can access the FIDO2 Sample Relying Party Web App via https://yourtenant.sdb.tid.onespan.cloud/v1/fido-sample-relying-party.

To use the FIDO2 Sample Relying Party Web App, you must load it in a browser or platform that supports WebAuthn.

The following browsers and platforms support WebAuthn:

• Chrome
• Firefox
• Edge
• Safari
• Windows 10
• Android

Set up a FIDO2 authenticator

To be able to work with the FIDO2 Sample Relying Party Web App you need to set up a FIDO2-compliant authenticator. Two types of authenticators can be used for the FIDO2 ceremonies:

• Platform authenticator A platform authenticator is integrated in a device and capable of capturing an authentication factor. In this case, the authentication factor refers to some physical characteristics of the user (biometrics), such as a fingerprint, eye, voice, typing speed, pattern in key press intervals, etc.

• Cross-platform authenticator A cross-platform authenticator is a hardware authenticator that can be connected to another device or service. These types of authenticators are not part of the same platform or operating system as the primary device. They communicate with the web browser via the CTAP1/CTAP2 protocol.

For a detailed list of supported FIDO2-supported authenticators, see FIDO2-supported authenticators.

Set up the authenticator

In this article, the Windows Hello platform authenticator is used to explain how to test the FIDO2 ceremonies.

To set up the Windows Hello authenticator for Windows 10 and 11

• Click the Windows Start button and navigate to Settings>Accounts>Sign-in options.

• (For Windows 10) In the Manage how you sign in to your device section, the following sign in options are available with Windows Hello:

  1. Select Windows Hello Face to set up facial recognition authentication with your device's infrared camera or an external infrared camera.
  2. Select Windows Hello Fingerprint to set up authentication via fingerprint reader.
  3. Select Windows Hello PIN to set up authentication with a PIN.

• (For Windows 11) In the Ways to sign in section, the following sign in options are available with Windows Hello:

  1. Select Facial recognition (Windows Hello) to set up facial recognition sign-in with your device's infrared camera or an external infrared camera.
  2. Select Fingerprint recognition (Windows Hello) to set up authentication via fingerprint reader.
  3. Select PIN (Windows Hello) to set up authentication with a PIN.

Register the Windows Hello authenticator

To register the Windows Hello authenticator

1. In your web browser, enter the URL of the FIDO2 Sample Relying Party Web App and select the REGISTER tab.
2. Enter a user name and a display name.

3. For the attestation field select one of the following options:

   • NONE. The server does not collect attestation data.
   • DIRECT. The server receives attestation data from the authenticator.
   • INDIRECT. The server allows for anonymized attestation data.
4. From the authenticatorAttachment list, select PLATFORM.

5. For the userVerification field select one of the following options:

   • REQUIRED. This value indicates that the Relying Party requires user verification for the FIDO operation. The operation will fail if the response does not have the AuthenticatorDataFlags.UV flag set.
   • PREFERRED. This value indicates that the Relying Party prefers user verification for the FIDO operation if possible, but the operation will not fail, even if the response does not have the AuthenticatorDataFlags.UV flag set.
   • DISCOURAGED. This value indicates that the Relying Party does not perform user verification during the FIDO operation.
6. (Optional) Select the requireResidentKey check box if you need to store the private key and associated metadata in persistent memory on the authenticator.
7. Click the SEND button in the INITIALIZE REGISTRATION section. If everything has been correctly configured, a JSON document will appear in the green response field. This represents the registration request and serves only for informational and debugging purposes.
8. Click the SEND button in the FINALIZE REGISTRATION section. A Windows Security dialog window opens where you need to authenticate.
9. Use the authentication method that you have previously selected in Windows Hello (face, fingerprint, PIN) and press OK.
10. Confirm that you are registering with the correct tenant and user name. The authenticator is now registered.

For more information on the FIDO2 Sample Relying Party Web App interaction with the web browser, see Registration flow code samples. The code samples in this article serve as examples on how to use the WebAuthn API for the registration flow.

Authenticate with the Windows Hello authenticator

To authenticate with the Windows Hello authenticator

1. In your web browser, enter the URL of the FIDO2 Sample Relying Party Web App and select the AUTHENTICATE tab.
2. Enter the user name and display name that you have previously used in the authenticator registration step.
3. Click the SEND button in the INITIALIZE AUTHENTICATION section. If everything has been correctly configured, a JSON document will appear in the green response field. This represents the authentication request and serves only for informational and debugging purposes.
4. Click the SEND button in the FINALIZE AUTHENTICATION section. A Windows Security dialog window opens where you need to authenticate.
5. Use the authentication method that you have previously set up in Windows Hello (face, fingerprint, PIN) and press OK.
6. Confirm that you are logging in with the correct tenant and user name. Your have now successfully logged in.

For more information on the FIDO2 Sample Relying Party Web App interaction with the web browser, see Authentication flow code samples. The code samples in this article serve as examples on how to use the WebAuthn API for the authentication flow.

Deregister the Windows Hello authenticator

FIDO2 does not have a deregistration ceremony that allows a request from the Relying Party to the FIDO authenticator to delete authentication keys that are bound to a user account. For the FIDO2 Sample Relying Party Web App, the DEREGISTER tab allows you to delete the public keys of a user that are stored on the FIDO2 Server. Note that this action will also delete the user!

To deregister the Windows Hello authenticator

1. In your web browser, enter the URL of the FIDO2 Sample Relying Party Web App. To deregister, select the corresponding tab.
2. Enter the user name you want to deregister.
3. To send the call, click the corresponding button. If the deleteUser call was successful, a JSON document will be displayed in the green response field with the message: "status": "success".

For more information about the code sample for the FIDO2 deregistration flow, see Deregister the authenticator.

Troubleshooting

Authenticator not configured properly

When testing the registration with INITIALIZE REGISTRATION where:

• the authenticatorAttachment field is set to PLATFORM, and
• the No Authentication window is prompted.

the following error message can be displayed:

NotAllowedError: The operation either timed out or was not allowed. See https://www.w3.org/TR/webauthn-2/#sctn-privacy-considerations-client.

This error usually means that the platform authenticator is not enabled or properly configured. In this scenario, you need to revisit the steps in Set up the authenticator.