FIDO Conformance

Introduction

The FIDO® Alliance offers a suite of tests known as the "Conformance Self-Validating 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 https://localhost before continuing!

Activating additional routes

Un-comment the following lines in the example project to activate additional routes:

example/index.js
// const { fidoRouteSuffix, fidoConformanceRouter } = require('./fido-conformance');
// app.use(fidoRouteSuffix, fidoConformanceRouter);

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:

FIDO2 Tests card

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

FIDO2 Metadata download button

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:

Code editor showing placement of metadata JSON files

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 https://0.0.0.0:443
ℹ️ 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:

FIDO2 Tests card

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

Showing selected FIDO2 server tests

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

FIDO2 Metadata download button

Enter the following URL into this text box:

https://localhost/fido

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

FIDO2 Tests run button

Confirming results

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

FIDO2 test results showing 160 passes and zero failures in approximately 19 seconds

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:

FIDO2 test failed to fetch error

Solution: Make sure the server is available at https://localhost, 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:

FIDO2 test failed to fetch error

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:

FIDO2 test failed to fetch error

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

Can't copy-paste text

You try in vain to copy-paste error messages, test results, or anything else from the the FIDO Conformance Tools window but nothing ever makes it to the clipboard.

Solution: Welcome to conformance testing, fellow macOS user - that's just how it is for now 🙃