A Practical Guide to Implementing Passkey

Passwords are "shared secrets"—vulnerable and outdated. Passkeys replace them with cryptographic signatures. The "secret" (private key) never leaves your device hardware.

Registration: The Handshake

Registration creates a new cryptographic identity on your device and shares the public part with the server.

• Server Challenge: The server generates unique creation arguments, including a one-time "challenge". This random string is critical— it prevents replay attacks where an old creation request is reused.

• Create credential: The browser calls navigator.credentials.create(). The device (TPM or Security Chip) generates a public/private key pair and asks for biometrics or a PIN.

Alternatively, you can use a third-party password manager if preferred.

• Verification: The browser sends the public key and attestation data back. The server verifies the signature and stores the credential id and public key in the database.

For visualization, view this AI generated interactive sequence diagram.

Authentication: The Signature

Logging in uses the key created during registration in a simple loop:

• Request: Server sends a fresh challenge and a list of accepted IDs.

• Sign: Browser calls `navigator.credentials.get()`. TPM (or third-party software) signs the challenge with the private key.

The response contains:

• clientDataJSON: Browser context like origin and the original challenge.
• authenticatorData: Metadata from the device (e.g., signature counter).
• signature: The cryptographic proof of identity.
  

• Verify: The server validates the response to grant access:
  • Check Challenge: Confirms the challenge in clientDataJSON matches the one it issued.
  • Validate Signature: Uses your stored public key to verify the cryptographic signature.
  • Security Check: Updates the signature counter to detect if the credential has been cloned.

For visualization, view this AI generated interactive sequence diagram.

Why it’s secure

• Isolated Keys: Private keys are locked in the TPM. They can't be extracted even if the OS is breached.
• No Shared Secrets: Server only knows public keys. Database leaks reveal nothing useful to attackers.
• Clone Detection: Signature counters track usage to flag duplicated credentials.
• Reliable Hardware: Even older chips using aged algorithms stay secure because keys are immutable.

Conclusion

Passkeys provide a frictionless experience with much stronger protection. Many modern libraries now simplify this implementation; for example, this blog uses better-auth. You can experience it yourself by logging in and adding a passkey in your settings.

Or check the code for this demo on my github 🚀.