WebAuthnMetadata

Owned by Philip Smart
Last updated: Dec 05, 2024
4 min read

Overview

The plugin supports two sources of Authenticator Metadata. The first source is the official FIDO metadata from the FIDO Metadata Service (FIDO Alliance Metadata Service - FIDO Alliance). The second source provides basic authenticator metadata from a locally configured JSON file, which aims to capture limited information about authenticators not in the FIDO Metadata Service—suitable for enhancing the registration interface.

FIDO Metadata Service

The official FIDO Alliance Metadata Service is a central repository of metadata statements about authenticator models. When enabled, this provides the following additional features:

  1. Validation of authenticator attestations during registration. Specifically, only allowing credentials to be registered from ‘trusted’ authenticators that are contained within the metadata.

  2. Enhancing the registration interface to display information about the user’s Authenticator: the device description and organisational icon.

Globally enabling the feature requires setting the idp.authn.webauthn.metadata.enabled property. Then, you have a choice of either downloading the metadata blob from the FIDO alliance Metadata Service URL (currently https://mds3.fidoalliance.org/), or, downloading the blob yourself, storing it locally, and pointing to the local file. The metadata does not change very often, but the FIDO guidelines suggest obtaining a new copy every month. Currently, this would require a restart of the IdP to pick up the new metadata.

For an authenticator to transmit an attestation statement to the IdP, which includes details about itself for matching with metadata entries, the IdP must initiate the registration request with an AttestationConveyancePreference. This can be set using the idp.authn.webauthn.registration.attestationConveyancePreference property. This defaults to ‘none’ (do not send an attestation statement), however a value of ‘direct’ or ‘enterprise’ would be needed to ensure this feature operated reliably (see the specification for more information). Please note that during registration, users must consent to sending the attestation statement to the IdP, and knowing the authenticators users are using may raise privacy concerns for the IdP.

Downloading the metadata blob from the FIDO metadata service URL

If you want to download metadata from the FIDO Alliance’s centralised repository when the IdP starts, you must specify a cache file (ending .bin) using the property idp.authn.webauthn.metadata.cacheFile, and the URL to fetch the metadata from using the property idp.authn.webauthn.metadata.metadataBlobUrl (by default this is https://mds3.fidoalliance.org/, although that can change, see https://fidoalliance.org/metadata/ ).

Downloading the metadata blob manually

As an alternative to downloading the metadata blob from a URL on startup of the IdP, you can choose to manage the metadata blob yourself. Download the blob JWT from the FIDO metadata service https://fidoalliance.org/metadata/ (currently, https://mds3.fidoalliance.org/) and load it using the property idp.authn.webauthn.metadata.metadataBlobFile.

Metadata Blob Trust Validation

To verify the integrity and authenticity of the metadata blob, you must download the metadata’s trust root certificate and load it using the property idp.authn.webauthn.metadata.trustRootFile. This is important because the metadata blob provides the trust roots for Authenticator Attestations and hence we need to first bootstrap trust for the metadata itself (as you would with SAML Metadata).

Revocation Checking

According to the FIDO MDS Specification, the revocation status of the certificates used in the metadata blob’s digital signature MUST be checked for the metadata to load. If you enable metadata support but do not enable revocation checking, the IdP will fail to start. There are two ways to enable this:

  1. Download and manage the CRLs present in the Metadata blob certificate path manually, and point to them using the idp.authn.webauthn.metadata.crls property.

    1. For the current signing certificate, these are at http://crl.globalsign.com/root-r3.crl and http://crl.globalsign.com/gs/gsextendvalsha2g3r3.crl. You’d need to keep these up to date to a) prevent them from expiring, and b) perform meaningful revocation checks.

  2. Comment out the idp.authn.webauthn.metadata.crls property and enable automated CRL checking from an online distribution point via the system property com.sun.security.enableCRLDP (as described in the CertPathDocs).

    1. This will enable CRL distribution points for the Sun PKIX engine across the IdP. So be careful this is what you want to do before enabling it.

Supplementary Passkey Provider Metadata

Without an additional source of metadata, authenticators/providers that are not part of the FIDO Metadata Service will remain ‘unknown’ to the registration/admin user interfaces. Typically, these are software authenticators that cannot provide "trusted" attestations (they self-attest) that can be verified by a trust anchor in the FIDO metadata service.

However, if you want the end-user to see a name and icon for ‘software’ authenticators they register in the registration inteferface e.g. ‘Bitwarden’, or ‘Windows Hello’, you will need to enable the supplementary passkey provider metadata support. To do this you must first download a suitable AAGUID JSON file based on the JSON schema attached. Next, enable support in the plugin by setting the property idp.authn.webauthn.metadata.aaguid.enabled to true and point to the AAGUID JSON file using the property idp.authn.webauthn.metadata.aaguid.passkeyAaguidFile.

The attached have been taken from the passkey-authenticator-aaguid GitHub repository.

 

 

Reference

 

Â