Skip to main content

FIDO2 Authenticator allow-listing

Description​

Configuring an allow list allows you to restrict FIDO2 authenticators for the registration and authentication ceremonies.

This feature is useful if you want to limit the FIDO2 security keys to a specific set of keys from a specific vendor.

Prerequisites​

Allow-listing is based on the Authenticator Attestation Global Unique Identifier (AAGUID) as well as the Attestation root certificate of the authenticator.

This poses requirements regarding the Attestation types which can be used. Those not containing an X509 certificate cannot be used for allow-listing, therefore attestation type none and self are not allowed.

In other terms this means that Attestation formats None and Packed (using self attestation type) are not allowed. Other requirement in this area that the attestation is actually sent by the client which is configured by attestation element of the Registration options service request (Also known as Attestation Conveyance Preference). The attestation option none will cause the client to not transmit the attestation, indirect has the freedom to alter the attestation for anonymization which makes the authenticator non-verifiable. Therefore direct is needed.

Authentication Ceremony

In case of the Authentication ceremony the attestation for validation is taken from the nevisIdm FIDO2 credential which was stored during the Registration ceremony. This is required as in case of Authentication the attestation is no longer sent by the client.

Summary
  • The Registration options service attestation attribute must be set to direct.
  • The authenticators supported attestation format must be Basic or AttCa.
  • Passkeys are not supported as they don't provide attestation.

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:

  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.