Skip to main content

FIDO2 Authenticator Metadata

FIDO2 authenticator metadata can be managed in two distinct manners depending on the specific customer needs. The differences are as follows:

FeatureFIDO Alliance Metadata ServiceLocal authenticator metadata
Metadata updatesautomated, monthlymanual
Metadata endpoint root certificate validation✅-
Certificate chain validation✅❌
Certificate revocation list check (CRL)✅❌
Attestation root certificate validation✅✅
Authenticator allow-listing✅✅

MDS3 - FIDO Alliance Metadata Service​

nevisFIDO supports the official FIDO Alliance Metadata Service providing organizations deploying FIDO Authentication with a centralized and trusted source of information about FIDO authenticators.

  • Nevis recommends using the official MDS3 service for most use cases and scenarios.
  • Usually it's sufficient to use singular official MDS3 metadata endpoint https://mds3.fidoalliance.org/. In case you have special needs, additional URLs can be configured.
  • The metadata root certificate is required in the nevisFIDO configuration to ensure metadata endpoints are trusted.

Caching and reloading​

The nevisFIDO component caches and updates the retrieved metadata according to the specification. It uses the nextUpdate attribute of the JWT BLOB for scheduling as well as a minimum (1 day) and maximum (30 days) caching period.

In the event of a failure to retrieve data from the defined endpoint URLs the system will retry reloading the cache at a configurable interval which defaults to 10 minutes.

Failed loading of MDS3 on component startup

The nevisFIDO component will start up successfully even failing to load the MDS3 data from the defined endpoint URLs. A failure in loading the MDS3 data is indicated in the component log as warning: Failed to refresh MetadataBLOB from MDS3 endpoint.

We consider improving the readiness endpoint in the future to indicate component readiness based on successful metadata retrieval.

How to configure the metadata service​

Configuring the metadata service is straightforward:

  1. Visit FIDO Alliance Metadata Service
  2. Download the root certificate
  3. Configure the metatadata URL in nevisFIDO
  4. Configure the truststore in nevisFIDO
  5. Add the root certificate to the truststore

Using nevisAdmin4 simplifies the configuration process.

Configuration

Local authenticator metadata​

As an alternative to the official metadata provided by the FIDO alliance, you are able to use local metadata files.

Local authenticator metadata is trusted, therefore no additional checks are performed regarding the certificate chain or the certificate revocation lists. As the local authenticator metadata is not fetched from a remote endpoint, a root certificate validation is not necessary.

Local metadata files are supported in two formats:

  1. "Plain" JSON files containing the authenticator metadata. The structure either has to be a single metadataStatement object or an array of metadataStatement objects.
  2. As BLOB - for example when directly downloaded from the FIDO Alliance Metadata Service.

In addition, you have three choices in how to provide the metadata:

  1. Providing a path to a directory. This is useful if you want to store multiple individual metadata files.
  2. Providing a path to a metadata file directly in case you only have one specific metadata file or BLOB.
  3. Providing the metadata inline as part of the nevisFIDO YAML file. Only a JSON array of metadataStatement objects is supported even if a single object is supplied.
Configuration

Using FIDO2 Authenticator allow-listing​

If you're an integrator wanting to use the FIDO2 allow-listing feature you'll generally have to execute the following steps:

Optional steps

Step 2 and 3 are optional as nevisFIDO supports directly using MDS3 BLOBs as local file system based metadata sources. Use these steps if you want to strip or simplify a BLOB.

  1. Download the latest FIDO Alliance Metadata BLOB from the official FIDO Alliance Metadata Service.

  2. Decode the JWT blob with tools of your choice. For example with the following bash function using the JQ utility:

    JWT Decode function
    jwt-decode() {
      jq -R 'split(".") |.[0:2] | map(gsub("-"; "+") | gsub("_"; "/") | gsub("%3D"; "=") | @base64d) | map(fromjson)' <<< $1
    }
    Example usage
    jwt-decode `cat blob.jwt` > fido-metadata.json

  3. Extract the metadata entries of your authenticators to a new JSON file. You can "strip out"/simplify the entry as only the "aaguid" and "attestationRootCertificates" are strictly required. We recommend keeping the "description"as well to easier distinguish the metadata records.

  4. Provide the JSON file as configuration option of the nevisFIDO component in the fido2.metadata.path property and enable the allow-listing by setting fido2.metadata.allow-listing-enabled to true. This can be done in the FIDO2 Instance pattern. Don't forget to restart/redeploy the nevisFIDO instance.

  5. In the FIDO2 onboarding pattern set the Attestation to direct.