Implement: Quick Start

@lwe: Is there a “quick start” even? There may not really be, as authentication is riddled with caveats, so I suggest we focus on clear use cases “Passkey onboarding” and “Signing-in with passkeys”. Whatever I've tried I've more or less I returned to the existing high-level structure, though we should put more emphasis on the server-side too. So I think having a "quickstart" can be missleading, I'd rather just talk about "Implementing passkeys" and focus on the two use-cases: onboarding to passkeys and signing-in with passkeys. The sections for "Server considerations" and "Browser considerations", maybe we can add them or a summary for more detailed things as part of "Implementation hints".

@lwe: Current stage, huge mix between bullet points, phrases and ideas. This is currently also just everything on a single page, but easier to edit right now.

Proposed pages

• Implementing passkeys
  • Passkey onboarding
  • Signing-in with passkeys
• Implementation hints
• Security considerations

Terminology

• Sign-in vs. authenticate vs. login
• Registration vs. onboarding vs. sign-up

Other Q's

• How many explanations and side-notes are necessary, within the content. To explain things like "what is a discovery credential" and why should I be creating one etc.
• Should we create a GH project with a small, real implementation, maybe a python/Flask or Node thingy, but also then: Should we use a library - or not?
• Explain fallback method, i.e. e-mail OTP - also for onboarding / registration?

---

Implementing passkeys

Passkeys are a simpler and more secure alternative to passwords, so your users don’t need to remember complex passwords or suffer through undelivered SMS OTPs. Passkeys are phishing resistant, unique across every website, and are encrypted digital keys created using fingerprint, face, or screen lock. (From https://simplewebauthn.dev/docs/advanced/passkeys, FIDO Alliance and adapted…)

This guide provides an overview of how to implement onboarding and signing-in with passkeys. For simplicity it focuses on the passkey experience, which is perfect for digital commerce and simple login scenarios.

[Note] The FIDO Alliance UX guide on passkeys suggests to use one-time-passwords (OTP) sent by e-mail as a fallback option.

[TODO: Add (clickable?) drawing: high-level onboarding flow & sign-in with passkeys]

Implement your flow

• Passkey onboarding
• Signing-in with passkeys

Prerequisites

• You need to implement passkeys on your existing sign-in flows.
• See the [Support matrix] for where passkeys are currently supported.
• ...

Passkey onboarding

Be it during the creation of a new user account or nudging existing users to switch to passkeys: both follow the same implementation. In this tutorial we are going to learn how to create passkeys for new - or existing users.

[TODO: Add drawing: Current sign-in / sign-up, with e-mail verification what not -> Passkey onboarding]

1. Your current onboarding flow or sign-in. Ensure the users successfully complete these steps, based on your current implementation. It’s an important step to ensure that users are properly authenticated, before starting a registration process. If not, it’s possible that user impersonation can happen.
2. Start of the passkey onboarding experience, which we’ll implement in this chapter.
3. 🎉 The user is onboarded to passkeys.

1. Check for passkey support

Before trying to onboard users to passkeys, it’s sensible to check if their current browser supports passkeys. Execute the following check on the browser:

• This also skips if only hybrid mode is available, maybe relax this check to allow hybrid mode too?

if (typeof window.PublicKeyCredential !== 'undefined' && PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()) {
   // Yes, we have passkeys -> continue / do nothing.
}
else {
   // Skip passkey setup, as this browser doesn’t seem to support it.
   location.href = '...';
} 

2. Create registration options on the server

• Registration options:
  • user -> how to correctly set the name, displayName + handle/ID
  • challenge: a (secure) random challenge
  • authenticatorSelection: residentKey=required, userVerification=preferred
• Keep the challenge and the required information in the current users sessions, to later finalize the registration.
• Return these options to the onboarding page.

3. Creating a passkey with the browser

[Content from https://passkeys.dev/docs/use-cases/bootstrapping/#opting-the-user-into-passkeys]

• Call to navigator.credentials.create (with the registration options)
• Explanation of what happens (maybe also a GIF?)

4. Finalize onboarding on the server

• Send response back to the server
• Server to verify the server data and persists the public key
• Notify the user that passkey registration was successful - and redirect them to the next page

Summary

• Summarize this page - and what we did.
• Next: Learn how to accept passkeys on sign-in

Signing-in with passkeys

[TODO: but same general structure as the onboarding part, with emphasis on conditional UI / mediation etc.]