FIDO Conformance

Introduction

The FIDO® Alliance offers a suite of tests known as the "Conformance Self-Validation Testing". These tests enable developers to verify their Relying Party's (RP) adherence to FIDO specifications.

The WebAuthn API is built on top of FIDO2, and so implementations of WebAuthn can also become FIDO conformant. WebAuthn implementers that go this extra mile add an additional level of validation of the authenticators that interact with their RP.

As of v0.7.0, the @simplewebauthn/server package is FIDO conformant! Support for this additional level of authenticator scrutiny is opt-in - see usage instructions for MetadataService for more information.

Validating FIDO conformance

It is important that the SimpleWebAuthn project remains FIDO conformant. To enable others to validate conformance and keep the project honest, a step-by-step list of instructions for running FIDO conformance tests against the library are included below.

Downloading FIDO Conformance Tools

FIDO conformance testing requires downloading the FIDO Conformance Tools application. If you don't already have it, you can submit a download request by filling out the Test Tool Access Request form.

note

For the "FIDO Specification" dropdown, select "FIDO2"

After submitting the form, an email response will (eventually) arrive with a download link and username and password. Navigate to the link, enter the username and password, and then download and install the latest release version for your OS from the Desktop UAF FIDO2 U2F/ directory.

You can now verify FIDO conformance of SimpleWebAuthn by following these steps:

Setting up the Example Project

Follow the instructions in the Example Project's Getting Started section.

important

Make sure the example project is available at http://localhost:8000 before continuing!

Activating additional routes

Create a .env file and add the following environment variable:

example/.env

ENABLE_CONFORMANCE=true

This will add additional routes on the /fido route.

Loading metadata statements

You will next need to load "metadata statements" from the FIDO Conformance Tools to ensure that all required tests pass.

Open up the FIDO Conformance Tools and click the Run button on the FIDO2 Tests card:

Next, scroll down and click the DOWNLOAD SERVER METADATA button on the right-hand column, under TESTS CONFIGURATION:

This will download a metadata.zip folder to your computer. Unzip the JSON files within and place them into the example/fido-conformance-mds/ directory:

Starting the server

Start the server once everything is in place:

./example/ $> npm start

An API request will be triggered by the activation of the conformance routes that pulls in additional metadata information required for the Metadata Service Tests. When the example server is ready for testing, you should see the following console output:

🚀 Server ready at http://0.0.0.0:8000
ℹ️ Initializing metadata service with 20 local statements
🔐 FIDO Conformance routes ready

Initiating conformance tests

To start conformance testing, open up the FIDO Conformance Tools and click the Run button on the FIDO2 Tests card:

On the right-hand column, under SELECT TESTS TO RUN, check the box next to Server Tests:

Next, scroll down and look for the Server URL text box on the right-hand column, under TESTS CONFIGURATION:

Enter the following URL into this text box:

http://localhost:8000/fido

It's finally time! Click the Run button on the bottom-right corner of the window to start conformance testing:

Confirming results

When the tests are completed, results for FIDO Conformance Tools v1.3.4 should look like this:

Troubleshooting

Below are errors you may see while trying to run tests, and potential solutions to them:

"Failed to fetch"

You may see a series of "Failed to fetch" errors:

Solution: Make sure the server is available at http://localhost:8000, and that you've activated the additional FIDO Conformance-specific routes.

"Unexpected token < in JSON at position 0"

You may see a series of "Unexpected token" errors:

Solution: Make sure that you've activated the additional FIDO Conformance-specific routes.

"Unlisted aaguid...in TOC"

You may see a series of "Unlisted aaguid" errors:

Solution: Make sure that you've loaded the metadata statements from the FIDO Conformance Tools