Skip to main content

Authenticator trust model

When registering a new credential a relying party can request an attestation statement. Attestation serves the purpose of providing a cryptographic proof of the authenticator attributes to the relying party in order to ensure that credentials originate from a trusted device with verifiable characteristics. For this reason, an attestation statement contains an attestation certificate that chains to some attestation root certificate(s). When requesting an assertion, the Hanko API can use an authenticator device identifier to lookup authenticator metadata statements in an external service that serves as an additional source of trust. This metadata contains data about the security characteristics of an authenticator as well as the attestation root certificates such that trust decisions can be made on the basis of whether the attestation statement certificate can be validated against the root certificate chain. This allows relying parties with high security requirements to establish a policy that defines allowed authenticator devices based on their security characteristics.

Defining an authenticator policy with the Hanko API#

The Hanko Authentication API allows relying parties to set up a such a policy. If security requirements are low and a relying party is not interested in attestation, it can allow registration with all types of authenticators. In this case, no attestation verfication is performed and a relying party cannot make any guarantees regarding security characteristics of an authenticator.

If security requirements are high, a relying party can also restrict registration to specific authenticators by setting up an allowlist from known and trusted authenticators. Relying parties can manage this policy through the FIDO settings in the Hanko Console.

Configuring an authenticator allowlist in the Hanko Console
Figure 1: Configuring an authenticator allowlist in the Hanko Console

Requesting attestation with the Hanko API#

When initializing a registration with the Hanko API an attestation conveyance preference can be set through the options.attestation attribute:

  • "none": indicates that the relying party is not interested in authenticator attestation.
  • "indirect": indicates that the relying party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements.
  • "direct": indicates that the relying party wants to receive the attestation statement as generated by the authenticator.

Attestation is disabled per default, i.e. if an attestation conveyance preference is omitted, WebAuthn will default to a none value, indicating that no attestation is required during registration.

Direct attestation conveyance preference on registration initialization - /v1/webauthn/registration/initialize
{
"options": {
"authenticatorSelection": {
"userVerification": "required",
"authenticatorAttachment": "platform",
"requireResidentKey": false
},
"attestation": "direct"
},
"user": {
"id": "e3be22a7-13cf-4235-a09c-380dfd44ac04",
"name": "john.doe@example.com",
"displayName": "John Doe"
}
}
info

Do not use none as your attestation conveyance preference if you have whitelisted authenticators through a policy. Whitelisting authenticators presupposes a verifiable attestation. Authenticator responses do not contain an attestation if none is set as a value and registration will fail (even if it was performed using a whitelisted authenticator).