Skip to content

Passkey Setup (WebAuthn)

Guide to setting up passwordless authentication using passkeys/security keys.

Overview

Passkeys provide passwordless authentication using: - Biometrics (Face ID, Touch ID, Windows Hello) - Security keys (YubiKey, Titan Key) - Device PIN (as fallback)

Benefits: - No passwords to remember - Phishing-resistant - Faster login - More secure

Standards: FIDO2/WebAuthn

Requirements

Browser Support

Desktop: - Chrome/Edge 108+ ✓ - Firefox 119+ ✓ - Safari 16+ (macOS 13+) ✓

Mobile: - Chrome Android ✓ - Safari iOS 16+ ✓

Device Support

Platform authenticators (built-in): - iPhone/iPad (Face ID, Touch ID) - Mac (Touch ID) - Windows 10+ (Windows Hello) - Android 9+ (biometric)

Cross-platform authenticators (external): - YubiKey 5 series - Google Titan Security Key - Feitian ePass FIDO2 - Any FIDO2-certified key

Setting Up Passkey

Via Web Interface

  1. Navigate: Profile → Security → Passkeys
  2. Click "Add Passkey"
  3. Choose authenticator:
  4. This device (Touch ID, Face ID, Windows Hello)
  5. Security key (YubiKey, USB key)
  6. Follow browser prompts:
  7. Touch sensor
  8. Scan face
  9. Insert and tap key
  10. Name the passkey: e.g., "MacBook Touch ID", "YubiKey 5"
  11. Click "Save"

Passkey now available for login.

Multiple Passkeys

Add multiple passkeys for: - Different devices (work laptop, personal phone) - Backup keys - Different locations

Recommended: At least 2 passkeys

Using Passkey to Login

Login flow: 1. Navigate to login page 2. Click "Sign in with passkey" 3. Browser shows available passkeys 4. Select passkey 5. Authenticate (touch sensor, scan face, etc.) 6. Logged in

No password required!

With Password Backup

Optional: Keep password as backup - Use passkey for regular login - Use password if passkey unavailable

Remove password: (passkey only) Profile → Security → Remove Password (requires admin permission)

Managing Passkeys

List Passkeys

Profile → Security → Passkeys

Shows: - Passkey name - Device type (platform/cross-platform) - Added date - Last used - Actions

Rename Passkey

  1. Click passkey
  2. Edit name
  3. Save

Use descriptive names: - "Work Laptop Touch ID" - "Personal YubiKey" - "iPhone 13 Face ID"

Remove Passkey

  1. Find passkey in list
  2. Click "Remove"
  3. Confirm removal

Cannot remove last passkey if password disabled!

Passkey Types

Platform Authenticators

Built into device: - Touch ID (Mac, iPhone, iPad) - Face ID (iPhone, iPad) - Windows Hello (Windows 10+) - Android biometric

Pros: - Always available - No extra hardware - Fast and convenient

Cons: - Device-specific - Lost if device lost

Cross-Platform Authenticators

External security keys: - YubiKey 5 - Google Titan - Feitian ePass

Pros: - Works across devices - Physical backup - Very secure - Portable

Cons: - Must carry key - Can be lost - Costs money

Recommendation

Best setup: 1. Primary: Platform authenticator (Touch ID/Face ID) 2. Backup: Cross-platform security key (YubiKey) 3. Optional: Password as emergency backup

Troubleshooting

Browser Not Supporting Passkeys

Update browser: - Chrome: Update to 108+ - Firefox: Update to 119+ - Safari: macOS 13+, iOS 16+

Check browser: 

chrome://version
firefox --version

Passkey Not Working

Common causes:

  1. Browser fingerprint changed
  2. New browser profile
  3. Cleared data

  4. Solution: Use different passkey or password

  5. Device not recognized

  6. New computer
  7. Incognito mode

  8. Solution: Add passkey for this device

  9. Security key not detected

  10. USB port issue
  11. Driver issue
  12. Solution: Try different port, update drivers

Lost Security Key

If primary key lost: 1. Use backup passkey 2. Or use password 3. Remove lost key from account 4. Add new passkey

If all passkeys lost AND password disabled: - Contact administrator - Admin resets via: sudo mb-admin-reset --email user@example.com

Security Considerations

Passkey Security

How passkeys are secure: - Private key never leaves device - Unique per website (no reuse) - Phishing resistant - Man-in-the-middle resistant

What's stored: - Server: Public key only - Device: Private key (encrypted)

Best Practices

  1. Enable passkey for all admins
  2. Add backup passkey
  3. Store security key securely
  4. Name passkeys clearly
  5. Remove old/unused passkeys
  6. Don't share security keys

Recovery Planning

  1. Multiple passkeys per account
  2. Password backup (optional)
  3. Document admin contacts
  4. CLI access for emergencies

CLI Commands

List user's passkeys: 

sudo mb-passkey-list --email user@example.com

Remove passkey: 

sudo mb-passkey-remove --email user@example.com --credential-id abc123

Disable password (passkey only): 

sudo mb-config set authentication.require_passkey true

Enforcing Passkeys

Require for admins:

Settings → Authentication → Passkeys - Check "Require passkeys for admins" - Set grace period: 30 days

Users prompted to add passkey on next login.

Migration from Password

Gradual migration:

  1. Week 1-2: Enable passkeys, encourage adoption
  2. Week 3: Require passkeys for new users
  3. Week 4: Require for all users (grace period)
  4. Week 5+: Passwords optional backup only

See Also