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[bot]]

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-19 18:33:34)

[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.

[torgo]

Hi @timcappalli one of the ethoses (ethii?) of Open Web Docs (who are doing this work) is to bring the web documentation to the places where the web developers are present - and right now that's MDN. (And also - through maintenance of the browser compatibility data - places like CanIUse.com.) I'd encourage you to consider the advantages of having high quality, cross-platform documentation where developers are actually looking for it.

[wbamberg]

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.

I'm not sure whether this comment is suggesting that we should not document passkeys on MDN, or that we should also document passkeys on passkeys.dev.

MDN does have inclusion guidelines, and among other things they say:

Our mission statement is "to provide developers with the information they need to easily build projects on the open web".

Helping web developers understand how to work with passkeys seems straightforwardly included in that. I do agree that there are aspects of passkeys that are not in scope for MDN (in particular, documentation for other audiences such as authenticator/OS/browser vendors), but that's not the subject of this article.

I'm not against contributing to passkeys.dev, but we're a small team with limited resources and have to decide where we can maximise the effect of our work. The advantage of contributing docs to MDN is that it is a very popular and trusted docs site, and we are likely to reach a lot of web developers by contributing to it. Please also note that MDN content is CC-BY-SA licensed, so it's fine to include MDN content elsewhere, subject to the terms of that license.

I hope we will get input from subject matter experts, to help ensure our docs are giving web developers the best possible guidance. We've benefited greatly from such involvement in our other security docs work such as the guides on XSS, XS-leaks, prototype pollution, etc.

[nadalin]

Appreciate the comments but this out of the scope of the WebAuthn WG or specification, I also encourage people withing the passkey eco system to contribute