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.
  • If you deploy nevisFIDO with nevisAdmin4, these settings are available in the FIDO2 Metadata category of the nevisFIDO FIDO2 Instance pattern: Metadata Location, Metadata Service URL(s), Metadata Service Trust Store and Local Metadata. Note that Metadata Service Trust Store holds the trust anchors used to validate the MDS BLOB's signing chain, not the TLS certificate of the endpoint.
FIDO MDS root certificate changed from GlobalSign R3 to R46

The FIDO Alliance migrated the MDS BLOB signing chain from the GlobalSign Root CA - R3 to the GlobalSign Root R46 certificate. If your MDS3 truststore only contains the R3 root, nevisFIDO can no longer validate the certificate chain of the MDS BLOB's signing certificate and logs the warning Failed to refresh MetadataBLOB from MDS3 endpoint. As a consequence the metadata cache is no longer updated and eventually expires.

Action required: add the GlobalSign Root R46 certificate to the truststore configured in fido2.metadata.mds3.metadata-truststore. You can download it from https://valid.r46.roots.globalsign.com/.

Add the R46 root to an existing PKCS#12 truststore
keytool -importcert -keystore <your-mds3-truststore>.p12 -storetype PKCS12 \
  -alias mds3-root-r46 -file GlobalSign_Root_R46.pem -noprompt

We recommend keeping the R3 root in the truststore alongside R46 until you are certain that none of your configured metadata endpoints chains to R3 any more. A truststore may contain any number of root certificates; all of them are used as trust anchors.

If you deploy with nevisAdmin4, assign a PEM Trust Store containing the R46 root to the Metadata Service Trust Store property of the nevisFIDO FIDO2 Instance pattern, which generates fido2.metadata.mds3.metadata-truststore.

Note that older nevisFIDO releases additionally fail to parse the current MDS BLOB, independently of the root certificate, because it uses a FIDO registry value they do not know yet. Upgrading nevisFIDO resolves the parsing problem; the R46 root still has to be added to your truststore as described above. If you cannot upgrade right away, see the local metadata workaround appendix.

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

The root certificate currently in use by the FIDO Alliance Metadata Service is the GlobalSign Root R46 certificate. Keep the previously used GlobalSign Root CA - R3 certificate in the truststore as well if you also consume metadata endpoints that still chain to it.

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.

Because local metadata is trusted as-is, it also bypasses the status report filtering that the Metadata Service path applies. A metadata statement whose FIDO certification was revoked or never granted is still accepted when it is supplied locally. Only use local metadata that you obtained from a source you trust, and prefer the Metadata Service wherever possible. If you need local metadata as a temporary workaround because the Metadata Service cannot be used, see the local metadata workaround appendix.

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
  1. 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.
  2. 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.
  3. In the FIDO2 onboarding pattern set the Attestation to direct.