User verification¶

User verification is a WebAuthn feature that confirms the identity of the actual user, not just possession of the authenticator. It answers the question: "Is the person using this authenticator really the authorized user?"

What is user verification?¶

User verification requires the user to prove their identity through:

🔐 PIN code - Entering a secret code on the authenticator
👆 Biometric recognition - Fingerprint, facial recognition, iris scan
🔑 Password entry - Entering a password on the device
🔒 Combined methods - Touch + PIN, or other combinations

The goal is to distinguish individual users and ensure that the person authenticating is the legitimate account owner, not just someone who stole or found the authenticator.

User presence vs user verification¶

It's important to understand the difference:

Feature	User Presence (UP)	User Verification (UV)
What it proves	Someone is there	Who is there
How	Simple button press, touch	PIN, biometric, password
Flag	`UP` flag in authenticator data	`UV` flag in authenticator data
Security level	Basic	Enhanced
Requirement	Always required	Optional (configurable)

User Presence is always enforced by WebAuthn - it simply confirms someone physically interacted with the authenticator (like touching a button).

User Verification goes further by confirming the specific identity of that person.

User verification requirements¶

You can configure the user verification requirement when creating credential options. There are three possible values:

`required`¶

The operation requires user verification and will fail if the authenticator does not set the UV flag.

use Webauthn\AuthenticatorSelectionCriteria;
use Webauthn\PublicKeyCredentialCreationOptions;

$authenticatorSelection = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED
);

$publicKeyCredentialCreationOptions = PublicKeyCredentialCreationOptions::create(
    rp: $rpEntity,
    user: $userEntity,
    challenge: random_bytes(32),
    authenticatorSelection: $authenticatorSelection
);

Use when: * High-security applications (banking, healthcare) * Privileged operations (admin actions, financial transactions) * Compliance requirements mandate biometric authentication

`preferred`¶

The operation prefers user verification but will not fail if the authenticator doesn't provide it.

$authenticatorSelection = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
);

This is the recommended default for most applications. It uses user verification when available but doesn't exclude authenticators that don't support it.

Use when: * General-purpose authentication * You want security when available without limiting device compatibility * Balancing security and user experience

`discouraged`¶

The operation discourages user verification to minimize disruption to the user flow.

$authenticatorSelection = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_DISCOURAGED
);

Use when: * Low-risk operations * Maximizing speed and convenience * Simple presence verification is sufficient * Testing or demonstration purposes

Checking the UV flag¶

The userVerification setting in the credential options is a request sent to the authenticator, not a guarantee. The CheckUserVerification ceremony step enforces it against the options that were actually emitted to the client — so if those options were built with a weaker requirement than your profile (for example, because Client Override Policy is configured to allow a client to lower it), the ceremony will pass even though no verification took place.

Warning

Mandatory for sensitive operations. Do not rely solely on userVerification: required in the profile to gate access to privileged actions (admin, payment, secret rotation, AAL2/AAL3 compliance). Always re-check the UV flag on the returned authenticator data after a successful ceremony. This is your final, authoritative signal that user verification actually occurred.

After authentication or registration, inspect the flag on the response's authenticator data and decide whether to proceed:

// $authenticatorResponse is the AuthenticatorAssertionResponse or
// AuthenticatorAttestationResponse that was just successfully validated.
$authenticatorData = $authenticatorResponse instanceof AuthenticatorAssertionResponse
    ? $authenticatorResponse->authenticatorData
    : $authenticatorResponse->attestationObject->authData;

if (! $authenticatorData->isUserVerified()) {
    // Only user presence was confirmed (button press / touch).
    // Reject for sensitive flows even if the ceremony succeeded.
    throw new AccessDeniedHttpException('User verification is required for this action.');
}

// Safe to proceed with the privileged operation

You can also read the raw flags if you need fine-grained checks (for example combining UV with BS/BE for backup-eligibility policies):

$flags = $authenticatorData->getFlags();
$uvFlag = (ord($flags) & 0x04) !== 0;  // UV flag is bit 2

Practical examples¶

Example 1: High-security banking app¶

// Require user verification for all operations
$authenticatorSelection = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED
);

// This ensures only authenticators with PIN/biometric can be used
$options = PublicKeyCredentialCreationOptions::create(
    rp: $rpEntity,
    user: $userEntity,
    challenge: random_bytes(32),
    authenticatorSelection: $authenticatorSelection
);

Example 2: General web application¶

// Prefer user verification but don't require it
$authenticatorSelection = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
);

// Works with all authenticators, uses UV when available
$options = PublicKeyCredentialCreationOptions::create(
    rp: $rpEntity,
    user: $userEntity,
    challenge: random_bytes(32),
    authenticatorSelection: $authenticatorSelection
);

Example 3: Fast re-authentication¶

// For quick re-auth on already logged-in user, discourage UV
$options = PublicKeyCredentialRequestOptions::create(
    challenge: random_bytes(32),
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_DISCOURAGED
);

Device capabilities¶

Different authenticators have different user verification capabilities:

Authenticator Type	User Verification Methods
Touch ID / Face ID (macOS/iOS)	Fingerprint, facial recognition
Windows Hello	Fingerprint, facial recognition, PIN
Android Platform	Fingerprint, facial recognition, pattern, PIN
YubiKey 5 Series	PIN (must be set up)
YubiKey Bio	Fingerprint
Basic security keys	None (only user presence)

Info

When you set userVerification: required, only authenticators capable of user verification will be available to the user during registration or authentication.

Best practices¶

For registration¶

Use preferred as default - Balances security and compatibility
Use required for sensitive accounts - Banking, healthcare, admin accounts
Inform users - Explain that biometric/PIN improves security

For authentication¶

Match registration settings - If registered with required, authenticate with required
Allow preferred for convenience - Users can choose faster auth if device supports it
Document your policy - Make clear what level of verification is expected

Conditional logic¶

// Require UV only for privileged operations
$isAdminAction = ($user->getRole() === 'ROLE_ADMIN');

$userVerification = $isAdminAction
    ? AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED
    : AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED;

$options = PublicKeyCredentialRequestOptions::create(
    challenge: random_bytes(32),
    userVerification: $userVerification
);

Common issues¶

Issue: "User verification not supported"¶

Cause: User's authenticator doesn't support UV, but you set required.

Solution: Use preferred instead, or provide alternative authentication methods.

Issue: Users complain about entering PIN repeatedly¶

Cause: Setting required for all operations, even low-risk ones.

Solution: Use discouraged or preferred for routine operations, save required for sensitive actions.

Security considerations¶

✅ Higher assurance - UV provides stronger identity verification than UP alone
✅ Phishing resistant - Even if an attacker steals the authenticator, they need the PIN/biometric
⚠️ Not foolproof - Biometric systems can have false positives; PINs can be observed
⚠️ Device dependent - Relying solely on UV limits compatible devices

Constants reference¶

The library provides convenient constants in the AuthenticatorSelectionCriteria class:

use Webauthn\AuthenticatorSelectionCriteria;

// For registration (attestation)
AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED
AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_DISCOURAGED

// These same constants can be used for authentication (assertion)
// in PublicKeyCredentialRequestOptions