FIDO2 policy

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 Cloud Authentication 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.

For the purpose of simplicity, OneSpan Cloud Authentication provides the Default policy, which is automatically applied to all newly created Relying Party resources. According to this Default policy, all FIDO2 authenticators are allowed, however, these must be certified by the FIDO Alliance. The Default policy can easily be replaced with a custom created policy that fits exactly the security needs of the application.

Policy concepts

The following sections outline some of the key concepts necessary to define a secure policy in OneSpan Cloud Authentication.

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 {
  uuid string
  name string
  default boolean
  fido {
     fido2 {
        allowSelfAttestation boolean
        accepted MatchCriterion[]
        disallowed MatchCriterion[]
     }
     u2f {
        accepted MatchCriterion[]
        disallowed MatchCriterion[]
     }
  }  
}

A policy JSON resource has a name, a default flag, and child objects for the FIDO2 and U2F policies. The default flag states whether the given policy is the Default policy (see Default policy). 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 RelyingParty accepts self-signed certificates instead of an attestation certificate that chains back to some root certificate. For more details see FIDO2 match criteria fields and 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. For a list of valid values, see userVerification.
• keyProtection: This criterion describes the methods used by an authenticator to protect the private key. For a list of valid values, see keyProtection.
• authCertLevel: This criterion describes the certification level. For a list of valid values, see authCertLevel.

For a more detailed description of the match criteria fields, see FIDO2-Based Authentication and Registration (FIDO2 Policy).

For a definition of the metadata statements fields, refer to the FIDO documentation on 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, see Sample FIDO2 policies.

Default policy

OneSpan Cloud Authentication provides a Default policy for FIDO2-based registration and authentication operations. This Default policy is defined to allow all FIDO-certified authenticators.

{
  "name": "Default Policy",
  "fido": {
    "fido2": {
     "allowSelfAttestation":true,
     "accepted": [{}],
      "disallowed": [{"authCertLevel":["NOT_FIDO_CERTIFIED"]}]
     },
     "u2f": {
      "accepted": [{}],
      "disallowed": [{"authCertLevel":["NOT_FIDO_CERTIFIED"]}]
     }
  }
}

The Default policy is automatically applied, unless a custom policy is created and activated. A custom policy is activated by assigning it to the default Relying Party resource via the policyID field. For more information, see Create and activate a new FIDO2 policy.

Existing Relying Parties resources will automatically be assigned a default policy.

Create and activate a new FIDO2 policy

If the Default policy does not meet your security requirements, you can create a custom policy via the OneSpan Trusted Identity platform API.

Sequence to create a new FIDO2 policy

1. Call the POST ​/policies endpoint via the OneSpan Trusted Identity platform API to create a new policy.
2. (Optional) To accelerate the policy creation process, you can use the contents of the Default policy as a template, and adjust the necessary fields.
3. To activate the policy, you must locate the default Relying Party resource via the GET /fido2-relying-parties endpoint. The default Relying Party resource contains the field isDefault=true.
4. Update this Relying Party resource with a call to the PATCH /fido2-relying-parties/{uuid}) endpoint. The policyID field must be updated with the UUID of the custom policy.

Update a FIDO2 policy

If you need to make amendments to an existing FIDO2 policy, this can be performed via the OneSpan Trusted Identity platform API.

Sequence to update a FIDO2 policy

1. Call the PATCH ​/policies/{uuid} endpoint via the OneSpan Trusted Identity platform API.
2. Provide only the fields in the request body that need to be updated.

The Default policy cannot be updated.

Manage policies

OneSpan Cloud Authentication enables you to perform the following policy management operations via the OneSpan Trusted Identity platform API.

Create new policy

Update a policy

Query all policies

Retrieve a specific policy by ID

Delete a policy