Add Passkey Security Cheat Sheet - #2369
Conversation
jmanico
left a comment
jmanico
left a comment
There was a problem hiding this comment.
Great work, There are many things we can add or clarify, but this is a great starting point and I want to get it live.
|
|
||
| Passkeys are [WebAuthn public key credentials](https://www.w3.org/TR/webauthn-3/#sctn-use-cases) that let a user authenticate without sending a shared secret to the application. The authenticator keeps the private key and the relying party stores a public key. A passkey is scoped to a relying party identifier (RP ID), which provides phishing resistance when the ceremony and server-side verification are implemented correctly. | ||
|
|
||
| This cheat sheet is for developers who build the relying-party side of passkey registration, authentication, credential management, and account recovery. The main recommendations are: |
There was a problem hiding this comment.
Why is this a passkey Cheat Sheet and not a WebAuthn cheet sheet?
There was a problem hiding this comment.
@randomstuff - Excellent point. All newly purchased passkeys today support WebAuthn, but they can support other things like FIDO2 (which is broader than WebAuthn). In fact, I have a really old Yubico Yubi Key that supports FIDO (now, FIDO1) but predated WebAuthn and all I use if for now is to with my password manager for some of the password vaults where I just using it as a 2FA mechanism. If this were truly about passkeys, this would have to be broader than what it is and cover use cases beyond just WebAuthn. But renaming the cheat sheet as WebAuthn can solve this.
There was a problem hiding this comment.
Hi @randomstuff , I am not sure whether can I reply to your comment in this PR , because this PR is not related to me. But I totally and definitely agree to your question, because most of the security controls here are fundamentally related to WebAuthn implementation controls. Especially passkey describes user facing category of WebAuthn credientials.
There was a problem hiding this comment.
OK, I'll clarify the intent of my question. 🙇
My understanding was that passkey was defined as "WebAuthn credentials stored in software" (eg. stored in the browser) in contrasted to backed by a FIDO2 hardware. Apparently, some people out there might use the term passkey for both "software" and "FIDO2-backed" WebAuth credentials. So my question was whether this Cheat Sheet was intending to covered only software implementations and whether it should cover both software and FIDO2 WerbAuthn credentials.
In any case, maybe it might be useful to clarify that this covers both forms of WebAuthn credentials (or not).
There was a problem hiding this comment.
Thanks for clarifying. I kept the Passkey Security scope approved in #2365, but made the protocol boundary explicit. The introduction now states that this covers the WebAuthn relying-party side of passkey deployment across platform and roaming authenticators, including security keys that support discoverable credentials, and both synced and device-bound passkeys. It also distinguishes legacy FIDO U2F/CTAP1 second-factor credentials as out of scope and explains the WebAuthn/FIDO2/CTAP relationship.
|
|
||
| ### Handle Signature Counters Conservatively | ||
|
|
||
| An increasing signature counter can provide a signal that some authenticators have been cloned. The WebAuthn [signature counter considerations](https://www.w3.org/TR/webauthn-3/#sctn-sign-counter) explain why it is not a universal clone-detection mechanism. Some authenticators do not implement a counter, and a synced credential may be used from multiple authenticator instances whose counter behavior is not strictly monotonic. |
There was a problem hiding this comment.
An increasing signature counter can provide a signal
Shouldn't that be "decreasing" (or more correctly "non-increasing")?
There was a problem hiding this comment.
Good catch. I changed this to “non-increasing” and aligned the explanation with the WebAuthn verification guidance: it is a signal, not proof, and may also indicate an authenticator malfunction or out-of-order assertion processing.
kwwall
left a comment
kwwall
left a comment
There was a problem hiding this comment.
Agree with @randomstuff that this should be renamed WebAutn_Security_Cheat_Sheet.md. And I meant to get to submit this yesterday, but my wife and I went out for dinner and when I got back, I forgot to finish it.
|
|
||
| Passkeys are [WebAuthn public key credentials](https://www.w3.org/TR/webauthn-3/#sctn-use-cases) that let a user authenticate without sending a shared secret to the application. The authenticator keeps the private key and the relying party stores a public key. A passkey is scoped to a relying party identifier (RP ID), which provides phishing resistance when the ceremony and server-side verification are implemented correctly. | ||
|
|
||
| This cheat sheet is for developers who build the relying-party side of passkey registration, authentication, credential management, and account recovery. The main recommendations are: |
There was a problem hiding this comment.
@randomstuff - Excellent point. All newly purchased passkeys today support WebAuthn, but they can support other things like FIDO2 (which is broader than WebAuthn). In fact, I have a really old Yubico Yubi Key that supports FIDO (now, FIDO1) but predated WebAuthn and all I use if for now is to with my password manager for some of the password vaults where I just using it as a 2FA mechanism. If this were truly about passkeys, this would have to be broader than what it is and cover use cases beyond just WebAuthn. But renaming the cheat sheet as WebAuthn can solve this.
|
Kevin, I think we may be conflating a passkey with an authenticator. A YubiKey is an authenticator that can store and use a passkey; it is not itself a passkey. Users do not necessarily need to purchase a dedicated hardware authenticator. Passkeys can also be managed by platform authenticators built into phones and laptops, and they may be device-bound or even synchronized across several devices. For that reason, I do not think we should rename this as a WebAuthn-only cheat sheet. The document covers substantially more than invoking the WebAuthn API. It addresses the full lifecycle required to deploy passkeys securely, including server-side verification and credential storage, registration and authentication, credential enrollment and revocation, account recovery, and the security differences between synchronized and device-bound passkeys. Passkey Security Cheat Sheet therefore describes the intended scope more accurately. |
|
@jmanico - FIDO2 is the more general authentication spec, an if I'm not
mistaken, Passkeys can also be used with general FIDO2, not just WebAuthn,
but I don't think this proposed Cheat Sheet even mentions FIDO2. That's
probably why @randomstuff, @sujalavnelavai, and I are questioning it.
Maybe name it Passkeys for WebAuthn, then.
--
Blog: https://off-the-wall-security.blogspot.com/ | GitHub: @kwwall
<https://github.com/kwwall>| OWASP ESAPI Project
<https://owasp.org/www-project-enterprise-security-api/>co-lead | OWASP and
ACM lifetime member
NSA: All your crypto bit are belong to us.
…On Mon, Aug 17, 2026, 12:38 AM Jim Manico ***@***.***> wrote:
*jmanico* left a comment (OWASP/CheatSheetSeries#2369)
<#2369 (comment)>
Kevin, I think we may be conflating a passkey with an authenticator. A
YubiKey is an authenticator that can store and use a passkey; it is not
itself a passkey. Users do not necessarily need to purchase a dedicated
hardware authenticator. Passkeys can also be managed by platform
authenticators built into phones and laptops, and they may be device-bound
or even synchronized across several devices.
For that reason, I do not think we should rename this as a WebAuthn-only
cheat sheet. The document covers substantially more than invoking the
WebAuthn API.
It addresses the full lifecycle required to deploy passkeys securely,
including server-side verification and credential storage, registration and
authentication, credential enrollment and revocation, account recovery, and
the security differences between synchronized and device-bound passkeys.
Passkey Security Cheat Sheet therefore describes the intended scope more
accurately.
—
Reply to this email directly, view it on GitHub
<#2369?email_source=notifications&email_token=AAO6PG7FA4U5VMYAHPEH6R35KKD2ZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZRGE4DQMJYGM42M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5311881839>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAO6PGZVAUF5NFZI3C77YDL5KKD2ZAVCNFSNUABFKJSXA33TNF2G64TZHMYTMMRXGIZTCMBUHNEXG43VMU5TKMJVGU3DIMBWGU3KC5QC>
.
Triage notifications, keep track of coding agent tasks and review pull
requests on the go with GitHub Mobile for iOS
<https://github.com/notifications/mobile/ios/AAO6PG7HIH56LFDSX7NH74D5KKD2ZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZRGE4DQMJYGM42M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJKTGN5XXIZLSL5UW64Y>
and Android
<https://github.com/notifications/mobile/android/AAO6PGYR22T6A2IC34B6AHL5KKD2ZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZRGE4DQMJYGM42M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>.
Download it today!
You are receiving this because you commented.Message ID:
***@***.***>
|
|
Thanks everyone. I pushed a focused scope clarification rather than renaming the file while the naming discussion remains split. The sheet now explicitly covers WebAuthn RP deployment of passkeys across platform and roaming authenticators, synced and device-bound credentials, and distinguishes legacy U2F/CTAP1 second-factor credentials. I also corrected the signature-counter condition. Markdown, terminology, and link checks all pass. @kwwall, would you please re-review whether this clarification addresses your change request? |
|
Kevin, I think we are conflating the credential with the authenticator. More precisely, a passkey is a discoverable FIDO public-key credential. A YubiKey is a FIDO authenticator/security key that can create and store device-bound passkeys. The YubiKey itself is not a passkey. It is also important to distinguish passkeys from FIDO2 credentials generally. FIDO2 supports both discoverable and non-discoverable credentials; the discoverable credentials are what the current standards terminology calls passkeys. FIDO2 is the umbrella consisting of WebAuthn and CTAP. WebAuthn defines the registration and authentication ceremonies used by the relying party and client, including the server-side verification model. CTAP is used when the client platform communicates with an external authenticator such as a YubiKey. Therefore, I do not think “Passkeys for WebAuthn” makes the title more accurate. Passkeys are already WebAuthn discoverable credentials. The Cheat Sheet should explain the complete passkey implementation model: WebAuthn, relevant CTAP concepts, relying-party validation, credential-record storage, account recovery, credential lifecycle, user verification, attestation, and support for multiple passkeys. |
5 participants
Description
This PR adds a vendor-neutral Passkey Security Cheat Sheet for developers implementing the WebAuthn relying-party lifecycle.
It follows the scope approved in #2365 and the earlier maintainer request for a cheat sheet that covers the entire passkey topic rather than credential binding alone.
What this covers
The guidance is architecture-first, language-independent, and uses no implementation-specific code. Technical claims are linked inline to W3C WebAuthn, NIST SP 800-63B-4, and related OWASP guidance.
Validation
markdown-link-checkScope and sourcing
Passkey_Security_Cheat_Sheet.md.AI Tool Usage Disclosure
This PR fixes issue #2365.