Overview
The plugin supports Authenticator Metadata obtained from the FIDO metadata service (FIDO Alliance Metadata Service - FIDO Alliance). When enabled, this provides the following additional features during registration:
Validation of authenticator attestations. Specifically, only allowing credentials to be registered from ‘trusted’ authenticators that are contained within the metadata.
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 trust root certificate listed at https://fidoalliance.org/metadata/ 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.