Skip to content

Adam Greenwell

Passkeys (WebAuthn)

Passkeys enable passwordless authentication using biometrics (Face ID, Touch ID, fingerprint) or hardware security keys. This modern authentication method is more secure and convenient than traditional passwords.

Overview

What are Passkeys?

Passkeys are a passwordless authentication technology built on the WebAuthn standard. Instead of typing a password, users authenticate using:

  • Biometrics – Face ID, Touch ID, Windows Hello, fingerprint readers
  • Hardware Keys – YubiKey, Titan Security Key, other FIDO2 devices
  • Device PINs – Fallback when biometrics unavailable

Benefits over passwords:

  • Phishing-resistant – Passkeys are bound to specific websites
  • No password reuse – Each passkey is unique per site
  • No password theft – Nothing to steal from server breaches
  • Easier for users – Just touch fingerprint or look at camera
  • Can bypass 2FA – Single authentication step with strong security

How Passkeys Work

  1. Registration – User creates a passkey on their device

    • Device generates public/private key pair
    • Public key sent to server and stored
    • Private key never leaves the device

  2. Authentication – User logs in with passkey

    • Server sends challenge
    • Device signs challenge with private key
    • User verifies with biometric/PIN
    • Server validates signature with public key

The private key is protected by the device's secure enclave and never transmitted.

Requirements

Server Requirements

  • HTTPS required – WebAuthn only works over secure connections
  • Modern PHP – PHP 8.1+ (Guard Dog requirement)
  • WordPress 5.9+ – For compatibility

Browser Requirements

Passkeys are supported in all modern browsers:

Browser Minimum Version
Chrome 67+
Firefox 60+
Safari 13+
Edge 79+
Opera 54+

Device Requirements

  • macOS – Touch ID or password
  • iOS/iPadOS – Face ID, Touch ID, or passcode
  • Windows – Windows Hello (face, fingerprint, or PIN)
  • Android – Fingerprint or screen lock
  • Hardware Keys – Any FIDO2/WebAuthn compatible key

Configuration

Navigate to Guard Dog → Login Security → Passkeys to configure:

Basic Settings

Enable Passkeys:

  • Default: Disabled
  • Description: Allow users to register and use passkeys
  • Recommendation: Enable for modern, security-conscious sites

Bypass 2FA with Passkeys:

  • Default: Enabled
  • Description: Users with passkeys skip the 2FA step
  • Rationale: Passkeys already provide strong authentication
  • Recommendation: Enable for better user experience

Require User Verification:

  • Default: Enabled
  • Description: Require biometric or PIN for each login
  • Recommendation: Keep enabled for security

User Guide: Setting Up Passkeys

Registering a Passkey

  1. Log in to WordPress with your current method (password + 2FA)

  2. Go to Profile – Navigate to Users → Profile

  3. Find Passkeys Section – Scroll to "Passkeys" area

  4. Enter Friendly Name – Give your passkey a recognizable name

    • Examples: "MacBook Pro", "iPhone", "YubiKey", "Work Laptop"

  5. Click "Register Passkey"

  6. Complete Device Verification

    • Touch fingerprint sensor, or
    • Look at Face ID camera, or
    • Enter Windows Hello PIN, or
    • Touch hardware security key

  7. Success! – Your passkey appears in the list

Logging In with Passkeys

  1. Go to Login Page – Standard WordPress login URL

  2. Click "Sign in with Passkey" – Button below login form

  3. Select Passkey – Browser shows available passkeys

  4. Verify Identity

    • Touch fingerprint, or
    • Face ID scan, or
    • Enter PIN, or
    • Touch security key

  5. Logged In! – Redirected to admin dashboard

Managing Passkeys

View Your Passkeys:

  • Go to Users → Profile → Passkeys
  • See all registered passkeys with:
    • Friendly name
    • Created date
    • Last used date

Rename a Passkey:

  1. Click "Rename" next to the passkey
  2. Enter new name
  3. Save changes

Delete a Passkey:

  1. Click "Delete" next to the passkey
  2. Confirm deletion
  3. Passkey is permanently removed

Important: Keep at least one passkey or ensure you can still log in with password!

Frontend Shortcodes and Blocks

Guard Dog includes passkey surfaces for classic shortcode templates and block-based themes.

Passkey Login Button

Use the standalone login primitive when a custom login page already owns the username/password form but needs Guard Dog passkey sign-in:

[guard_dog_passkey_login username_selector="#user_login" redirect_to="/account/"]

The matching dynamic block is Guard Dog Passkey Login (guard-dog/passkey-login).

Useful attributes:

Attribute Default Purpose
username_selector #user_login CSS selector for the username or email field.
redirect_to empty URL to send the user to after successful passkey login.
show_icon true Show or hide the button icon.
wrapper_class guard-dog-passkey-login Wrapper classes for theme styling.
button_class button button-secondary guard-dog-passkey-login__button Button classes for theme styling.
status_class guard-dog-passkey-login__status Status message classes for theme styling.

The passkey login button only renders for logged-out visitors when passkeys are enabled. Each instance receives unique IDs and data hooks, so it can safely appear beside the full Guard Dog login form or inside a custom login layout.

Passkey Account Management

Use the passkey management primitive on logged-in account pages:

[guard_dog_passkeys style="default"]

The matching dynamic block is Guard Dog Passkeys (guard-dog/passkeys). The style attribute accepts default, minimal, or compact.

Passkey management lets users register, rename, and delete passkeys from the frontend. It shows a login-required message to logged-out visitors and returns no output when passkeys are disabled globally.

For all account-security controls in one panel, use the composite shortcode:

[guard_dog_account_security show_passkeys="true" show_sessions="true"]

Multiple Passkeys

Users can register multiple passkeys for different devices:

Recommended Setup:

  • Primary Device – Main laptop/desktop (e.g., "MacBook Pro")
  • Mobile Device – Phone for on-the-go (e.g., "iPhone 15")
  • Backup Device – Secondary device or security key (e.g., "YubiKey")

Benefits:

  • Access from any registered device
  • Backup if one device is lost
  • Different devices for different locations

Passkeys and 2FA

Default Behavior (Bypass Enabled)

When "Bypass 2FA with Passkeys" is enabled:

Login Method Authentication Steps
Password only 1. Password → 2. 2FA Code → Logged in
Passkey only 1. Biometric → Logged in
Password + Passkey available User chooses method

Bypass Disabled

When "Bypass 2FA with Passkeys" is disabled:

Login Method Authentication Steps
Password 1. Password → 2. 2FA Code → Logged in
Passkey 1. Biometric → 2. 2FA Code → Logged in

Most sites should enable bypass since passkeys already provide strong authentication.

Security Considerations

Why Passkeys Are Secure

  1. Cryptographic Keys – Uses public key cryptography, not shared secrets

  2. Device-Bound – Private key never leaves the device's secure enclave

  3. Phishing-Resistant – Passkeys are bound to specific domain names

  4. No Password Database – Only public keys stored on server

  5. User Verification – Requires biometric or PIN for each use

What's Stored on Your Server

Guard Dog stores:

  • Credential ID – Unique identifier for the passkey
  • Public Key – Used to verify signatures (safe to store)
  • Metadata – Friendly name, creation date, last used

Not stored:

  • Private key (never leaves device)
  • Biometric data (stays on device)
  • Any sensitive cryptographic material

Account Recovery

Passkeys don't replace passwords entirely. Users should:

  • Keep password as backup
  • Register multiple passkeys on different devices
  • Have recovery codes for 2FA

If a user loses all passkeys:

  1. Log in with password + 2FA
  2. Register new passkey
  3. Delete old passkeys if lost device

Activity Logging

Passkey events are logged in the Activity Log:

Event Description
passkey_registered New passkey created
passkey_login User authenticated with passkey
passkey_login_failed Passkey authentication failed
passkey_deleted Passkey removed from account
passkey_renamed Passkey friendly name changed

View logs in Guard Dog → Activity Log.

Common Use Cases

Security-Conscious Organization

Scenario: Company requiring strong authentication

Configuration:

  • Enable passkeys
  • Require user verification: Enabled
  • Bypass 2FA: Enabled (passkeys are sufficient)
  • Encourage all staff to register passkeys

Developer/Tech Site

Scenario: Users comfortable with modern auth

Configuration:

  • Enable passkeys
  • All settings enabled
  • Prominently feature passkey option on login

Mixed User Base

Scenario: Some users tech-savvy, others not

Configuration:

  • Enable passkeys
  • Don't require passkeys
  • Keep password + 2FA as default
  • Passkeys as opt-in for advanced users

Troubleshooting

Passkey Registration Fails

Symptoms: Error when trying to register passkey

Check:

  1. HTTPS Required

    • WebAuthn only works over HTTPS
    • Check your site uses https://

  2. Browser Support

    • Try Chrome, Firefox, Safari, or Edge
    • Update to latest version

  3. Device Support

    • Verify device has biometric or PIN capability
    • Check security key is FIDO2 compatible

  4. JavaScript Errors

    • Open browser console (F12)
    • Check for error messages

Passkey Login Button Missing

Symptoms: No "Sign in with Passkey" on login page

Check:

  1. Feature Enabled

    • Go to Guard Dog → Login Security → Passkeys
    • Verify "Enable Passkeys" is checked

  2. User Has Passkeys

    • Button may only show for users with registered passkeys

  3. Browser Support

    • Button hidden if browser doesn't support WebAuthn

Passkey Login Fails

Symptoms: Biometric works but login fails

Check:

  1. Correct Account

    • Make sure passkey belongs to correct WordPress user
    • Each passkey is tied to specific user account

  2. Passkey Not Disabled

    • Check passkey is still in your profile
    • May have been deleted

  3. Server Time

    • WebAuthn is time-sensitive
    • Check server time is correct

Users Locked Out

Symptoms: User can't log in with passkey or password

Solutions:

  1. Password Reset

    • Use WordPress password reset
    • Passkeys don't affect password reset

  2. Admin Creates New Password

    • Admin resets user's password from dashboard
    • User logs in with new password

  3. Database Direct

    • As last resort, admin can delete passkeys from database
    • Table: wp_guard_dog_passkeys

Best Practices

  1. Encourage but don't require – Make passkeys optional initially

  2. Recommend multiple passkeys – Register on 2+ devices for backup

  3. Keep password as fallback – Don't delete password capability

  4. Enable 2FA bypass – Passkeys provide equivalent security

  5. Educate users – Explain benefits and how to set up

  6. Test before rollout – Verify passkeys work in your environment

  7. Monitor adoption – Check Activity Log for passkey usage

  8. Support plan – Have process for users who lose passkeys

FAQ

Q: Are passkeys more secure than passwords?
A: Yes. Passkeys use cryptographic keys that can't be phished, guessed, or stolen in data breaches.

Q: What if I lose my device?
A: Register passkeys on multiple devices. You can also log in with password and delete the lost device's passkey.

Q: Can I use a hardware security key?
A: Yes. Any FIDO2/WebAuthn compatible key (YubiKey, Titan, etc.) works.

Q: Do passkeys work on mobile?
A: Yes. iOS, iPadOS, and Android all support passkeys.

Q: Can I require passkeys for all users?
A: Currently, passkeys are opt-in. Passwords remain as fallback.

Q: What data is stored on the server?
A: Only the public key and metadata. Private keys never leave your device.

Q: Do passkeys sync across devices?
A: With iCloud Keychain (Apple) or Google Password Manager, yes. Otherwise, register each device separately.

Q: What if biometrics fail?
A: Most devices allow PIN as fallback. You can also use password login.

Q: Can hackers steal my passkey?
A: The private key is stored in secure hardware (Secure Enclave, TPM) and cannot be extracted.

Q: Should I still use 2FA with passkeys?
A: With "Bypass 2FA" enabled, passkeys provide equivalent security. It's your choice.

← Two-Factor Authentication | Documentation Home | Sessions →