Add passkeys guide

[wbamberg]

Here's a draft page on passkeys.

It's not yet finished, major missing sections are:

• stuff about migrating users away from passwords, including techniques like conditional mediation
• something about passkey portability, addressing the question of whether passkeys tend to lock users in
• more detail about the security properties of passkeys and potential weaknesses
• some more signposty stuff explaining the structure of this document

But it's mostly there.

[github-actions]

Preview URLs

• /en-US/docs/Web/Security/Authentication/Passkeys

Flaws (3)

URL: /en-US/docs/Web/Security/Authentication/Passkeys
Title: Passkeys
Flaw count: 3

• macros:
  • Macro glossary produces link /en-US/docs/Glossary/biometric which doesn't resolve
  • Macro glossary produces link /en-US/docs/Glossary/biometric which doesn't resolve
  • Macro glossary produces link /en-US/docs/Glossary/registrable_domain which doesn't resolve

External URLs (5)

URL: /en-US/docs/Web/Security/Authentication/Passkeys
Title: Passkeys

• https://bitwarden.com/ (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Touch_ID (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Windows_10 (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/YubiKey (1 time) (Note! This may be a new URL 👀)
• https://www.lastpass.com/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-12-15 05:01:49)

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
error search-replace Custom rule [bad-gfm-alert: Use the correct GFM syntax: > [!NOTE]] [Context: "column: 1 text:'> [!NOTE]'"]

[wbamberg]

Some questions.

Attestation

Spec says (https://w3c.github.io/webauthn/#sctn-attestation-limitations):

However, it is important to note that an attestation statement, on its own, provides no means for a Relying Party to verify that an attestation object was generated by the authenticator the user intended, and not by a man-in-the-middle attacker. For example, such an attacker could use malicious code injected into Relying Party script. The Relying Party must therefore rely on other means, e.g., TLS and related technologies, to protect the attestation object from man-in-the-middle attacks.

...In all cases it is possible for a man-in-the-middle attacker to replace the PublicKeyCredential object, including the attestation statement and the credential public key to be registered, and subsequently tamper with future authentication assertions scoped for the same Relying Party and passing through the same attacker.

I don't understand this. If the attestation is signed by a key rooted in "ACME Authenticator Inc", how can an attacker replace the public key credential in the attestation without breaking the signature (or at least replacing iut with a new signature whose key is not rooted in "ACME Authenticator Inc")?

Also, what should our recommendation be about attestation? Some docs I've read basically un-recommend it for websites. Is that what we should do?

Credential loss

Spec says (https://w3c.github.io/webauthn/#sctn-credential-loss-key-mobility)

In general, it is expected that a credential private key never leaves the authenticator that created it

...but I read a lot about authenticators backing up credential private keys to the cloud. Is this a situation where the spec and the current reality diverge, or am I misunderstanding things?

Should we recommend that people implement a "lost all credentials" flow, falling back to an email?

Language around "user verification"

I struggle not to call this "authentication", like "the user authenticates themselves to the authenticator". Is this OK?

Passkey portability/transferring passkeys

I haven't really looked into this yet but I'd be happy to get any pointers about what to say here.

[timcappalli]

Hi! Typically MDN covers the web platform components, not the entire ecosystem. Passkeys are just one type of credential that can be created via the Web Authentication API.

We would love for you to contribute some of this content to passkeys.dev, which is the ecosystem level developer resource for passkeys. This site is maintained by members of W3C and FIDO Alliance, who work within the wider passkeys ecosystem.