WebAuthnMetadata
- Philip Smart
Overview
The plugin supports two sources of Metadata about FIDO authenticators. The first source is the official FIDO metadata from the FIDO Metadata Service (FIDO Alliance Metadata Service - FIDO Alliance). The second source provides basic metadata about authenticators from a locally configured JSON file. This file captures limited information regarding authenticators not included in the FIDO Metadata Service, making it 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 features:
Validation of authenticators (via their attestation statements) during registration. Specifically, only allowing credentials to be registered from ‘trusted’ authenticators that are contained (and not revoked) within the metadata. Importantly, the metadata only includes hardware authenticators which have had their secure, hardware-bound, attestation private keys signed by an intermediate certificate authority (CA) (chained to a trusted root specified in the metadata) during the manufacturing process.
Improving the registration interface to show details about the user's authenticator, including the device description and organizational icon.
Software authenticators cannot provide trusted attestation because they cannot meet the security, trust, and certification requirements of the FIDO standards. For example, they cannot protect the attestation private key, which is necessary to verify that a credential belongs to a trusted device.
Globally enabling the feature requires setting the idp.authn.webauthn.metadata.enabled property to true. 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 send 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 that is not 'none' (do not send an attestation statement). A value of ‘direct’ or ‘enterprise’ would be needed to ensure this feature operated reliably (see the specification for more information). This can be set using the idp.authn.webauthn.registration.attestationConveyancePreference property.
Users must consent to send the attestation statement to the IdP during registration and knowing which authenticators users are using may raise privacy concerns.
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 JWT blob from the FIDO metadata service https://fidoalliance.org/metadata/ (currently, https://mds3.fidoalliance.org/) and specify it to the IdP 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:
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.
For the current signing certificate, these are at
http://crl.globalsign.com/root-r3.crlandhttp://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.
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).
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 a trust anchor in the FIDO metadata service can verify.
However, if you want the end-user to see a name and icon for ‘software’ authenticators they register in the registration interface 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.
