Web & Ontwikkeling

Passkeys en WebAuthn in 2026: Een Praktische Implementatiegids voor Webontwikkelaars

Passkeys and WebAuthn in 2026: A Practical Implementation Guide for Web Developers

Passkeys beloven een wachtwoordloze inlog zonder wachtwoordgeheimen op te slaan, maar het correct implementeren van WebAuthn vereist meer dan het aanroepen van een browser-API. Leer hoe registratie, authenticatie, server-side verificatie, ontdekkingsbare referenties en accountherstel samenkomen in een veilige webapplicatie.

Wachtwoorden zijn al decennia het standaardauthenticatiemechanisme voor webtoepassingen geweest. Ook zijn het een blijvende bron van beveiligingsproblemen.

Gebruikers hergebruiken ze. Aanvallers stelen ze via phishing. Servers moeten wachtwoordhashes beschermen, resets beheren en zich verdedigen tegen credential-stuffing-aanvallen.

Passkeys bieden een fundamenteel ander aanpak.

In plaats van gebruikers vragen om een gedeeld geheim te onthouden, gebruiken passkeys openbare-sleutelcryptografie en een authenticator die door de gebruiker wordt beheerd. De browser biedt via WebAuthn een standaardinterface, terwijl de server cryptografische bewijzen verifieert dat de juiste credential is gebruikt.

De technologie is niet langer experimenteel. WebAuthn is tegenwoordig goed beschikbaar in moderne browsers, en de JSON-voordiensten hebben de integratie aanzienlijk vereenvoudigd.

Maar het bouwen van een beveiligde passkey-login vereist nog steeds zorgvuldige backendontwerpen.

Deze gids legt de architectuur uit, demonstreert de browserzijde van de flow en identificeert de serverzijde checks die ontwikkelaars niet mogen negeren.

1. Wat is een passkey precies?

Een passkey is een ontdekbare FIDO-credential dat wordt gebruikt om een gebruiker te authenticeren via openbare-sleutelcryptografie.

Tijdens registratie maakt een authenticator een cryptografisch sleutelpaar.

De privésleutel blijft beschermd door de authenticator of diens credential-management-ecosysteem. De website ontvangt de bijbehorende openbare sleutel en koppelt deze aan het account van de gebruiker.

Tijdens authenticatie geeft de server een verse uitdaging. De authenticator tekent gegevens die aan die uitdaging zijn gekoppeld, en de server verifieert de handtekening met behulp van de opgeslagen openbare sleutel.

Er wordt geen herbruikbaar wachtwoord naar de website verzonden.

Een authenticator kan een smartphone, een computer met Windows Hello, een hardware-securitykey of een credential manager die gesynchroniseerde passkeys ondersteunt.

Niet elke passkey is over apparaten heen gesynchroniseerd. Sommige credentials blijven apparaatgebonden, terwijl anderen veilig kunnen worden back-ups en beschikbaar gemaakt via een credential provider.

De FIDO-specificaties zijn ontworpen om phishing te weerstaan door het koppelen van credentials aan het domein van de relying party. Biometrische gegevens, wanneer gebruikt, worden lokaal door het apparaat verwerkt en niet naar de website verzonden.

2. WebAuthn is de API in de browser achter passkeys

WebAuthn is de webplatform-API die websites in staat stelt om openbare-sleutelcredentials aan te maken en te gebruiken.

Twee browsermethoden vormen de basis:

navigator.credentials.create()
navigator.credentials.get()

De eerste maakt een credential. De tweede vraagt authenticatie aan met behulp van een bestaande credential.

Beide methoden werken met de publicKey-optie en vereisen een secure context, meestal HTTPS.

Belangrijk is dat de browser niet beslist of de gebruiker is geauthenticeerd. Het geeft gegevens terug die de backend moet verifiëren.

Een succesvolle browserprompt is geen bewijs dat een login moet worden geaccepteerd.

De server blijft verantwoordelijk voor het verifiëren van de uitdaging, oorsprong, relying-party identifier en cryptografische bewijzen.

3. Begrijp de complete architectuur

Een typische implementatie bevat vier componenten:

  • De frontend van de webtoepassing, die WebAuthn aanroept.
  • De toepassingsbackend, die uitdagingen genereert en antwoorden verifieert.
  • De authenticator of passkey provider, die de privésleutel beschermt.
  • De database, die credentialmetadata en openbare sleutels opslaat.

De registratiestroom is: de webtoepassing vraagt registratieopties aan; de backend genereert een uitdaging en gebruikersgegevens; de browser en authenticator maken een credential en sleutelpaar; en de backend verifieert het resultaat en slaat de openbare sleutel op.

De server mag nooit registratiedata vertrouwen alleen maar omdat deze van de browser is geretourneerd.

Een kwaadwillende client kan willekeurige HTTP-verzoeken indienen zonder de verwachte frontend überhaupt te gebruiken.

Daarom behoort verificatie naar de server.

4. Genereer registratieopties op de server

Voordat WebAuthn wordt aangeroepen, genereert de backend een registratieuitdaging en -opties.

Een voorbeeld van een optiesobject ziet er als volgt uit:

{
  "rp": {
    "name": "Example Application",
    "id": "example.com"
  },
  "user": {
    "id": "dXNlci0xMjM",
    "name": "alex@example.com",
    "displayName": "Alex"
  },
  "challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "required"
  },
  "attestation": "none",
  "timeout": 300000
}

Dit is illustratieve JSON, geen complete productierespons.

Verschillende velden zijn belangrijk.

rp.id identificeert de relying party. Bijvoorbeeld kan example.com worden gebruikt voor passende subdomains van dat domein, onder voorwaarde van de WebAuthn RP ID-validatieruimte.

user.id moet een stabiele, ongeknoopbare accountidentificator zijn die is gecodeerd als base64url voor JSON-transport. Het mag geen onnodige persoonsgegevens blootleggen.

challenge moet worden gegenereerd met een cryptografisch beveiligde willekeurige bron op de server.

residentKey: "required" vraagt om een ontdekbare credential, wat noodzakelijk is voor de passkey-ervaring.

userVerification: "required" vraagt om lokale gebruikersverificatie, zoals een apparaat-PIN of biometrische authenticatie. De backend moet later controleren of die verificatie daadwerkelijk heeft plaatsgevonden.

De servergids voor registratie van Google beschrijft deze velden en raadt aan om een onderhouden WebAuthn-bibliotheek te gebruiken voor het genereren en valideren van registratiedata.

5. Maak de passkey aan in JavaScript

Moderne browsers bieden een nuttig methodenummer aan:

PublicKeyCredential.parseCreationOptionsFromJSON()

Het zet een JSON-representatie die base64url-gecodeerde binarium velden bevat in de structuur die WebAuthn verwacht.

Dit voorkomt het schrijven van aangepaste base64url-naar-ArrayBuffer-conversielogica voor elk veld.

Hier is een vereenvoudigde functie aan de browserzijde:

async function registerPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/register/options',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            }
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start registration');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseCreationOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.create({
        publicKey
    });

    if (!credential) {
        throw new Error('No credential was created');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/register/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': csrfToken
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Registration verification failed');
    }

    return await verifyResponse.json();
}

De variabele csrfToken vertegenwoordigt een anti-CSRF-token van de applicatie. De server moet deze valideren. De voorbeelden gaan er ook van uit dat de pagina al aan een veilig geauthenticeerd gebruiker is gekoppeld.

credential.toJSON() biedt een JSON-vriendelijke weergave van de geretourneerde credential, waardoor een extra laag handmatige binarium serialisatie wordt vermeden.

Deze gemakken zijn beschikbaar in huidige browsers, hoewel applicaties die oudere browserververs ondersteunen compatibiliteitsafhandeling moeten bieden.

De bovenstaande code is alleen de browserzijde. Het is geen complete authenticatieimplementatie.

6. Wat de server tijdens registratie moet verifiëren

Wanneer de browser de nieuwe credential retourneert, moet de backend deze verifiëren voordat er iets wordt opgeslagen.

In ieder geval moet het verificatieproces vastleggen dat:

  1. De geretourneerde uitdaging overeenkomt met degene die voor deze registratiepoging is gegenereerd.
  2. De uitdaging fris is en nog niet is gebruikt.
  3. De gerapporteerde oorsprong overeenkomt met een expliciet vertrouwde applicatie-origine.
  4. De authenticatordata overeenkomt met het verwachte RP ID.
  5. De vereiste user-presence en user-verification voorwaarden zijn vervuld.
  6. Het public key en identifier van de credential kunnen worden geëxtraheerd en gevalideerd.
  7. De registratie aan het juiste geauthenticeerde account is gekoppeld.

Afhankelijk van het beleid van de applicatie kunnen aanvullende checks ook ondersteunde algoritmes, credential-uniekheid en attesteringsvereisten omvatten.

Een succesvolle registratie slaat meestal op:

Veld Doel
credential_id Identificeert de credential
user_id Koppelt deze aan een account
public_key Verifieert toekomstige handtekeningen
sign_count Volgt authenticator counter gegevens bij
transports Optionele authenticator transport hints
created_at Registratietimestamp
last_used_at Accountbeheer en auditing
backup_eligible / backup_state Optionele back-up gerelateerde metadata

De exacte database-representatie hangt af van de verificatiebibliotheek en de applicatie.

Implementeer CBOR-parsing, attesteringsverificatie of cryptografische handtekenenvalidatie niet vanafaf zomaar, tenzij je een overtuigende reden en de expertise hebt om het onderhouden.

De W3C-specificatie definieert gedetailleerde registratie- en authenticatieverificatieprocedures.

7. Authenticeer een bestaand gebruiker

Authenticatie volgt een soortgelijke structuur, maar maakt geen nieuw sleutelpaar aan.

De server genereert een nieuwe uitdaging en stuurt authenticatieopties naar de browser.

Voor een ontdekbare passkey-login kunnen die opties bevatten:

{
  "challenge": "NEW_SERVER_GENERATED_CHALLENGE",
  "rpId": "example.com",
  "userVerification": "required",
  "timeout": 300000
}

De browser kan dan een credential aanvragen:

async function authenticateWithPasskey() {
    const optionsResponse = await fetch(
        '/api/passkeys/login/options',
        {
            credentials: 'same-origin'
        }
    );

    if (!optionsResponse.ok) {
        throw new Error('Unable to start authentication');
    }

    const optionsJson = await optionsResponse.json();

    const publicKey =
        PublicKeyCredential.parseRequestOptionsFromJSON(
            optionsJson
        );

    const credential = await navigator.credentials.get({
        publicKey
    });

    if (!credential) {
        throw new Error('Authentication was cancelled');
    }

    const verifyResponse = await fetch(
        '/api/passkeys/login/verify',
        {
            method: 'POST',
            credentials: 'same-origin',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credential.toJSON())
        }
    );

    if (!verifyResponse.ok) {
        throw new Error('Authentication failed');
    }

    return await verifyResponse.json();
}

Dit voorbeeld neemt aan dat de backend de uitgegeven uitdaging koppelt aan een korte, anonieme login transactie, past passende rate limiting toe en stelt pas na succesvolle verificatie een nieuwe geauthenticeerde sessie op.

De server moet de credential ID opzoeken, de ondertekende bewijzen verifiëren met de opgeslagen openbare sleutel, de uitdaging en oorsprong bevestigen en het gebruikersverificatiebeleid handhaven.

Alleen dan moet het de gebruikersessie vaststellen.

parseRequestOptionsFromJSON() is onderdeel van de moderne WebAuthn API en verwijdert het need om handmatig binarium velden te decoderen in veelgebruikte browserzijde integraties.

8. Voeg passkeys toe aan bestaande loginformulieren met conditional mediation

Een van de meest bruikbare WebAuthn-functies is conditional mediation, soms passkey autofill genoemd.

In plaats van direct een aparte passkey-dialog te tonen, kan de browser tijdens het interactie met een inlogveld een beschikbare passkey aanbieden naast andere opgeslagen credentials.

De HTML-input kan gebruiken:

<input
    type="text"
    name="username"
    autocomplete="username webauthn"
>

De applicatie kan controleren op support:

const supported =
    await PublicKeyCredential.isConditionalMediationAvailable();

if (supported) {
    // Request authentication with mediation: 'conditional'.
}

Wanneer je navigator.credentials.get() aanroept, gebruikt de applicatie:

{
    publicKey,
    mediation: 'conditional'
}

Voor ontdekbare-credential autofill moeten de opties van de server de request niet beperken tot een specifieke lijst met credential IDs.

Conditional mediation is vooral nuttig tijdens een geleidelijke migratie van wachtwoorden omdat gebruikers niet hoeven te onthouden of een bepaald account een passkey heeft.

De browser kan passende opties presenteren in de vertrouwde login ervaring.

9. Waarom de checks voor uitdaging en oorsprong essentieel zijn

Passkeys zijn phishingbestendig, maar dat betekent niet dat een applicatie het authenticatieprotocol mag negeren.

De uitdaging beschermt tegen replay-aanvallen.

Zonder een verse, onvoorspelbare uitdaging zou een aanvaller proberen authenticatiedata van een eerdere sessie opnieuw te gebruiken.

De oorsprong en RP ID checks zorgen ervoor dat credentials in de beoogde websitecontext worden gebruikt.

Bijvoorbeeld kan een passkey die is aangemaakt voor example.com niet eenvoudig worden hergebruikt door een op lookalike lijkende phishing-site zoals examp1e.com.

De browser en authenticator handhaven belangrijke onderdelen van deze domeinbinding, terwijl de backend de resulterende bewijzen onafhankelijk valideert.

Een goede implementatie gebruikt korte levensduur uitdagingen, consumeert elke uitdaging één keer en accepteert geen willekeurige oorsprongen alleen maar omdat ze een herkenbaar ogend hostname hebben.

MDN raadt aan om uitdagingen in een vertrouwde omgeving te genereren en ze na een korte periode te ongeldigen, over het algemeen niet meer dan ongeveer tien minuten.

10. Begrijp signature counters niet verkeerd

WebAuthn authenticators kunnen een signature counter bevatten.

Historisch hielpen counters bij het detecteren van mogelijk gekloonde authenticators. Als een counter onverwacht niet meer toeneemt, mag de relying party dat als een risico-signal beschouwen.

Echter, niet elke authenticator onderhoudt een betekenisvolle counter.

Sommige credentials rapporteren altijd een nul. Gesynchroniseerde credentials kunnen de counterinterpretatie ook compliceren omdat meerdere apparaten kopieën van dezelfde credential kunnen gebruiken.

De W3C-specificatie behandelt onverwachte countergedrag expliciet als een mogelijker signaal, niet als definitief bewijs van klonen.

Daarom zouden ontwikkelaars niet elke login met een nul of ongewijzigde counter blindelings moeten afwijzen.

Gebruik de counter volgens het authenticator gedrag, de richtlijnen van de WebAuthn verificatiebibliotheek en het beveiligingsbeleid van de applicatie.

11. Account recovery is onderdeel van passkey security

Een passkey implementatie is incompleet zonder een recovery strategie.

Wat gebeurt er wanneer een gebruiker een apparaat verliest?

Wat als ze hun enige passkey verwijderen?

Wat als ze credential provider wijzigen of een gesynchroniseerde credential niet kunnen openen?

Een logische ontwerpen staat gebruikers toe om meerdere passkeys te registreren en deze te beheren vanuit hun accountinstellingen.

De beheerinterface zou erkennbare credential namen, aanmaakdatums en recente gebruiksinformatie moeten tonen waar beschikbaar.

Gebruikers moeten in staat zijn om credentials in te trekken die ze niet meer vertrouwen.

Maar het recovery mechanisme verdient bijzondere zorg.

Als een aanvaller passkey authenticatie kan omzeilen met een zwak e-mail recovery proces, is het hele account alleen even veilig als die recovery path.

Voor hoogrisico accounts overweeg je sterkere recovery verificatie, recovery codes, extra geregistreerde authenticators en notificaties over gevoelige accountwijzigingen.

De passkey UX richtlijnen van Google raden aan om een recovery methode vast te stellen en meerdere passkeys te ondersteunen waar passend.

12. Veelvoorkomende implementatiefouten

Meerdere fouten ondermijnen herhaaldelijk anders veelbelovende passkey integraties.

Browser succes als server authenticatie behandelen. Een opgeloste navigator.credentials.get() promise vervangt geen serverzijde cryptografische verificatie.

Uitdagingen genereren in JavaScript. Uitdagingen moeten uit een vertrouwde server komen en aan de juiste authenticatietransactie worden gebonden.

Het verkeerde RP ID gebruiken. Domeinscoping is een beveiligingsfunctie, geen decoratieve instelling. Productie-, staging- en lokale ontwiksetilings vereisen een duidelijke configuratie.

Assumeren dat alle passkeys synchroniseren. Apparaatgebonden credentials blijven een belangrijk onderdeel van het ecosysteem.

Vergetenschap credential revocation. Gebruikers moeten een manier hebben om een verloren of gecompromiteerde authenticator uit hun account te verwijderen.

Een zwakke fallback creëren. Een phishingbestendige login verliest veel van zijn waarde als account recovery eenvoudig kan worden uitgenuteld.

Oudere browsers negeren. Moderne JSON-voordiensten verminderen complexiteit, maar applicaties met oudere browservervingsvereisten hebben mogelijk nog compatibiliteitscode nodig.

CSRF en sessiebeveiliging overslaan. Registratie- en credential-management bezoeken zijn gevoelige accountwijzigingen. Ze hebben dezelfde beschermingen nodig als andere high-impact account acties.

Aangepaste cryptografische verificatie onnodig schrijven. Een onderhouden WebAuthn server bibliotheek is meestal een veiligere keuze dan het specifieer direct implementeren.

13. Moet elke website direct wachtwoorden vervangen?

Niet noodzakelijk.

Passkeys kunnen zowel gebruiksvriendelijkheid als beveiliging verbeteren, maar migratie strategie is belangrijk.

Voor een nieuwe applicatie kan passwordless registratie een redelijke standaard zijn als het product een goed ontworpen recovery flow heeft en de doelplatforms ondersteunt.

Voor een bestaande applicatie met duizenden gebruikers is geleidelijke adoptie vaak veiliger.

Begin met het toestaan dat geauthenticeerde gebruikers passkeys kunnen registreren in de accountinstellingen.

Voeg dan passkey login toe naast het bestaande authenticatiesysteem.

Introduceer conditional mediation waar ondersteund.

Meet registratie succes, authenticatiefouten, apparaatcompatibiliteit en recovery verzoeken.

Bovendien, overweeg om passkeys de voorkeurste authentatiemethode te maken zodra de gebruikerservaring en recovery mechanismen voldoende wiskundig zijn.

Een gefaseerde rollout maakt het ook eenvoudiger om browspecifieke problemen te identificeren zonder legitieme gebruikers uit te sluiten.

14. Checklist voor productie klaar

Voordat passkeys in productie worden ingeschakeld, controleer je de volgende punten:

  • Alle WebAuthn operaties draaien in een passende secure context.
  • RP IDs en vertrouwde oorsprongen zijn expliciet geconfigureerd.
  • Uitdagingen zijn cryptografisch willekeurig, korte levensduur en één keer te gebruiken.
  • Registratie vereist passende accountautorisatie.
  • Serverzijde verificatie volgt de WebAuthn specificatie.
  • Openbare sleutels en credential identifiers worden veilig opgeslagen.
  • Login stelt pas een sessie vast na succesvolle verificatie.
  • Vereisten voor gebruikersverificatie worden op de server doorgevoerd.
  • Het verwijderen van credentials en account recovery zijn beschermd.
  • Meerdere credentials per account worden ondersteund waar passend.
  • Authenticatiefouten en beveiligingsgevoelige accountwijzigingen worden gemonitord.
  • Mobiele, desktop, cross-device en hardware-key scenario's worden getest.

Deze checks zijn belangrijker dan of de frontend een aantrekkelijke biometrische login prompt kan weergeven.

Conclusie: passkeys zijn een authenticatiearchitectuur, geen enkele browserfunctie

WebAuthn maakt openbare-sleutelauthenticatie beschikbaar voor gewone webtoepassingen.

Moderne browser APIs hebben veel van de serialisatiewerk verwijderd dat passkey integratie eerder moeilijk maakte.

Maar de browser is slechts één onderdeel van het systeem.

De echte implementatiewerk ligt in uitdagingsbeheer, serverzijde verificatie, credentialopslag, domeinconfiguratie, account recovery en beveiligde gebruikerservaringen.

Voor ontwikkelaars die moderne applicaties bouwen in PHP, JavaScript, Python of andere backend omgevingen, zijn passkeys steeds meer een praktische vervanging waard om overwegen voor traditionele wachtwoorden.

De beste start is niet om vanavond een volledig authentiesysteem te vervangen.

Het is om één complete, correct geverifieerde registratie- en login flow te implementeren, en er dan een beveiligde migratie strategie omheen te bouwen.