FIDO2 policies

FIDO2 is an open protocol and to provide effective security, FIDO2 authenticators have to uphold certain standards. To guarantee that these standards are well implemented, the FIDO Alliance certifies FIDO2 devices grouped in various levels, and maintains a metadata database that contains the security properties of all certified authenticators.

Furthermore, the attestation mechanism of the FIDO2 protocol allows the relying party to identify the type of authenticator that is used in a strong cryptographic way. This ensures that the used FIDO2 device is genuine and the relying party can configure a policy to check that the device safeguards the security characteristics defined in the policy. For example, a site that provides financial services may choose to only accept hardware-backed FIDO2 authenticators, while some other site may allow FIDO2 devices implemented in software.

The attestation mechanism only guarantees the identity of the vendor for a FIDO2 device and the model that is used. To ensure that the device is indeed secure, it must go through a certification process, where the FIDO Alliance inspects the vendor's authenticator implementation. Relying parties can configure a policy to allow only authenticators that are certified according to certain security levels. In absence of such a policy or if the none-attestation option is used, all authenticators, if certified or not, could be used. This may be acceptable for certain applications, but not for others that require higher security standards.

With the FIDO2 Policy, OneSpan FIDO2 SDK allows relying parties to flexibly configure allow and disallow policies to define which authenticators can be used for registrations and authentication operations. It is possible to specify detailed criteria to match certain security properties of the authenticator. In case a relying party does not want to limit any authenticators from being used, it can simply configure an Allow-All policy or use none-attestation.

Policy concepts

This section outlines some of the key concepts necessary to define a policy which can be used by the FIDO2 SDK.

Policy definition

A policy consists of an accepted list and an disallowed list. These contain a list of match criteria each, which are not mandatory.

An authenticator is allowed for an operation (authentication and registration) if it matches any of the match criteria in the allowed list and does not match any of the match criteria in the disallowed list. If the accepted list is empty or null, no authenticator is accepted. An authenticator matches a match criterion if its associated metadata statement matches all fields in the match criterion. For more information about how field matching works, see Field matching.

The AAGUID (Authenticator Attestation Global Unique Identifier), which uniquely identifies the authenticator model, is used to look up the metadata statement for the authenticator. If none-attestation is used during the authenticator registration, no such AAGUID is available, and the policy validation is skipped. That means in case of none-attestation, all authenticators are allowed.

Policy schema

Policy {
  fido {
    fido2 {
      allowSelfAttestation boolean
      accepted MatchCriterion[]
      disallowed MatchCriterion[]
    }
    u2f {
      accepted MatchCriterion[]
      disallowed MatchCriterion[]
    }
  }
}

The policy defined in the fido2 child object is only applied to FIDO2 authenticators, whereas the policy defined in the u2f child object is only applied to U2F authenticators. FIDO2 authenticators are authenticators where the protocolFamily field in their associated metadata statements states fido2. U2F authenticators are authenticators where the protocolFamily field in their associated metadata statements states u2f.

In case of FIDO2, the AAGUID is used as an identifier for the authenticator model, and to look up the metadata statement. However, U2F authenticators do not support AAGUID, and the attestationCertificateKeyIdentifier is used instead to identify the authenticator model and to look up the metadata statement.

Also for FIDO2, the allowSelfAttestation flag controls whether the relying party accepts self-signed certificates instead of an attestation certificate that chains back to some root certificate. For more details, refer to the FIDO Alliance websites.

Match criteria

MatchCriterion {
  aaguid string[]
  attestationCertificateKeyIdentifier string[]
  minAuthenticatorVersion integer
  userVerification string[]
  keyProtection string[]
  authCertLevel string[]
}

The match criterion object has the following fields:

• aaguid: Each FIDO2 authenticator model has an associated AAGUID, which uniquely identifies the type of authenticator.
• attestationCertificateKeyIdentifier: FIDO U2F authenticators do not support AAGUID, however, they use attestation certificates to uniquely identify the authenticator model.
• minAuthenticatorVersion: This criterion describes the minimum required version of the authenticator.
• userVerification: This criterion describes the methods and capabilities of a FIDO2 authenticator for locally verifying a user.
• keyProtection: This criterion describes the methods used by an authenticator to protect the private key.
• authCertLevel: This criterion describes the certification level.

For a more detailed description of the match criteria fields, refer to the OneSpan Cloud Authentication Integration Guide, available at FIDO2-Based Authentication and Registration (FIDO2 Policy).

For a definition of the metadata statements fields, refer to the FIDO documentation about metadata keys.

Field matching

A field in the match criterion matches the corresponding field in the metadata statement if:

1. The field in the match criterion is null, empty, an empty array, or is not provided.
2. The field in the match criterion is an array, and the corresponding field in the metadata statement exists and has a single value and that value equals at least one entry in the match criteria array.
3. The field in the match criterion is an array, and the corresponding field in the metadata statement is an array and at least one value in the match criterion array equals at least one value in the metadata statement array.
4. The field in the match criterion has a single value, and the field in the metadata statement has a single value and they are equal.
5. The field in the match criterion has a single value, and the field in the metadata statement is an array and the value from the match criterion equals at least one entry in the metadata statement array.

6. The field is part of a match criterion that is part of the disallowed list and the field has at least one non-null value, and the corresponding field in the metadata statement is null, empty, or does not exist.

7. The field minAuthenticatorVersion matches, if the value in the metadata statement for authenticatorVersion is equal or larger than the value for minAuthenticatorVersion in the match criterion.
8. The field userVerification in the match criterion matches the corresponding field userVerificationDetails in the metadata statement if it equals any userVerificationMethod in any subarray.

For a list of various FIDO2 policy examples, refer to the OneSpan Cloud Authentication Integration Guide, available at Sample FIDO2 Policies.

For a reference of the FIDO2-based policy used in OneSpan Cloud Authentication, refer to the OneSpan Cloud Authentication Integration Guide, available at FIDO2-Based Authentication and Registration (FIDO2 Policy).