Passkeys in the Guard Dog plugin 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
- 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
- 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
- Log in to WordPress with your current method (password + 2FA)
- Go to Profile – Navigate to Users → Profile
- Find Passkeys Section – Scroll to “Passkeys” area
- Enter Friendly Name – Give your passkey a recognizable name
- Examples: “MacBook Pro”, “iPhone”, “YubiKey”, “Work Laptop”
- Click “Register Passkey”
- Complete Device Verification
- Touch fingerprint sensor, or
- Look at Face ID camera, or
- Enter Windows Hello PIN, or
- Touch hardware security key
- Success! – Your passkey appears in the list
Logging In with Passkeys
- Go to Login Page – Standard WordPress login URL
- Click “Sign in with Passkey” – Button below login form
- Select Passkey – Browser shows available passkeys
- Verify Identity
- Touch fingerprint, or
- Face ID scan, or
- Enter PIN, or
- Touch security key
- 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:
- Click “Rename” next to the passkey
- Enter new name
- Save changes
Delete a Passkey:
- Click “Delete” next to the passkey
- Confirm deletion
- Passkey is permanently removed
Important: Keep at least one passkey or ensure you can still log in with password!
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
- Cryptographic Keys – Uses public key cryptography, not shared secrets
- Device-Bound – Private key never leaves the device’s secure enclave
- Phishing-Resistant – Passkeys are bound to specific domain names
- No Password Database – Only public keys stored on server
- 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:
- Log in with password + 2FA
- Register new passkey
- 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:
- HTTPS Required
- WebAuthn only works over HTTPS
- Check your site uses
https://
- Browser Support
- Try Chrome, Firefox, Safari, or Edge
- Update to latest version
- Device Support
- Verify device has biometric or PIN capability
- Check security key is FIDO2 compatible
- JavaScript Errors
- Open browser console (F12)
- Check for error messages
Passkey Login Button Missing
Symptoms: No “Sign in with Passkey” on login page
Check:
- Feature Enabled
- Go to Guard Dog → Login Security → Passkeys
- Verify “Enable Passkeys” is checked
- User Has Passkeys
- Button may only show for users with registered passkeys
- Browser Support
- Button hidden if browser doesn’t support WebAuthn
Passkey Login Fails
Symptoms: Biometric works but login fails
Check:
- Correct Account
- Make sure passkey belongs to correct WordPress user
- Each passkey is tied to specific user account
- Passkey Not Disabled
- Check passkey is still in your profile
- May have been deleted
- 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:
- Password Reset
- Use WordPress password reset
- Passkeys don’t affect password reset
- Admin Creates New Password
- Admin resets user’s password from dashboard
- User logs in with new password
- Database Direct
- As last resort, admin can delete passkeys from database
- Table:
wp_guard_dog_passkeys
Best Practices
- Encourage but don’t require – Make passkeys optional initially
- Recommend multiple passkeys – Register on 2+ devices for backup
- Keep password as fallback – Don’t delete password capability
- Enable 2FA bypass – Passkeys provide equivalent security
- Educate users – Explain benefits and how to set up
- Test before rollout – Verify passkeys work in your environment
- Monitor adoption – Check Activity Log for passkey usage
- 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.