Passkeys og WebAuthn i 2026: En praktisk implementeringsguide for webutviklere
Passkeys lover passordløs pålogging uten å lagre passordhemmeligheter, men korrekt implementering av WebAuthn krever mer enn å kalle en nettleser-API. Lær hvordan registrering, autentisering, server-side verifikasjon, oppdagelige legitimasjoner og kontogjenoppretting passer sammen i en sikker webapplikasjon.
Passkeys og WebAuthn i 2026: En praktisk implementasjonsguide for webutviklere
Passord har vært standardmekanismen for godkjenning inettstedet for lenge. De er også en vedvarende kilde til sikkerhetsproblemer.
Brukere gjenbruker dem. Angripere stjeler dem gjennom phishing. Servere må beskytte passordhasher, håndtere tilbakestillinger og forsvare seg mot kreditiv-innholdningsangrep.
Passkeys byr på en heltannen tilnærming.
I stedet for å be brukere huske et felles hemmelig, bruker passkeys offentlig-nøkkel-kryptografi og en autentisering kontrollert av brukeren. Nettleseren gir et standardkort gjennom WebAuthn, mens serveren verifiserer kryptografisk bevis for at riktig kreditiv ble brukt.
Teknologien er ikke lenger eksperimentell. WebAuthn er bredt tilgjengelig i moderne nettlesere, og dens JSON-metoder har gjort integrasjon mye enklere.
Men å bygge en sikker passkey-innlogging krever fortsatt forsiktig backend-design.
Denne guiden forklarer arkitekturen, demonstrerer nettleser-siden strømmene og identifiserer server-siden sjekker som utviklere ikke bør overside.
1. Hva er en passkey egentlig?
En passkey er en oppdagbar FIDO-kreditiv brukt til å godkjenne en bruker gjennom offentlig-nøkkel-kryptografi.
Under registrering oppretter en autentisering en kryptografisk nøkkelpar.
Den private nøkkelen forblir beskyttet av autentiseringen eller dens kreditivhåndteringsøkosystem. Nettstedet mottar den tilhørende offentlige nøkkelen og knytter den til brukerens konto.
Under autentisering utfører serveren en frisk utfordring. Autentiseringen signerer data knyttet til denne utfordringen, og serveren verifiserer signaturen ved hjelp av den lagrede offentlige nøkkelen.
Det er ingen gjenbrukbar passord sendt til nettstedet.
En autentisering kan være en smarttelefon, en PC med Windows Hello, en maskinvare-sikkerhetsnøkkel eller en kreditivhåndterer som støtter synkroniserte passkeys.
Ikke alle passkeys er synkronisert på tvers av enheter. Noen kreditiv bleer enhetsknyttet, mens andre kan sikkert kopieres og gjøres tilgjengelige gjennom en kreditivleverandør.
FIDO-spesifikasjonene er designet for å motvirke phishing ved å knytte kreditiv til pålitelig-vertens domene. Biometisk data, når brukt, håndteres lokalt på enheten i stedet for å bli sendt til nettstedet.
2. WebAuthn er nettleser-API-en bak passkeys
WebAuthn er nettplatform-API-en som gjør det mulig for nettsteder å opprette og bruke offentlig-nøkkel-kreditiver.
To nettlesermetoder danner grunnlaget:
navigator.credentials.create()
navigator.credentials.get()
Den første oppretter en kreditiv. Den andre ber om godkjenning ved hjelp av en eksisterende kreditiv.
Begge metodene arbeider med publicKey-alternativet og krever en sikkert kontekst, vanligvis HTTPS.
Viktig, nettleseren bestemmer ikke om brukeren er godkjent. Den returnerer data som backend må verifisere.
En vellykket nettleserprompt er ikke bevis for at innlogging skal aksepteres.
Serveren er fortsatt ansvarlig for å verifisere utfordlingen, opprinnelsen, pålitelig-vertens ID og kryptografisk bevis.
3. Forstå komplett arkitektur
En typisk implementering inneholder fire komponenter:
- Webapplikasjonsfrontend, som kaller WebAuthn.
- Applikasjonsbackend, som genererer utfordringer og verifiserer svar.
- Autentisering eller passkey-leverandør, som beskytter den private nøkkelen.
- Databasen, som lagrer kreditiv-metadata og offentlige nøkler.
Registreringstrømmen er: webapplikasjonen ber om registreringsoptioner; backenden genererer en utfordring og brukerdata; nettleseren og autentiseringen oppretter en kreditiv og nøkkelpar; og backenden verifiserer resultatet og lagrer den offentlige nøkkelen.
Serveren må aldri stole på registreringsdata bare fordi den ble returnert av nettleseren.
En ondsig klient kan sende vilkårlige HTTP-forespørsler uten å bruke det forventede frontendet i det hele.
Det er derfor verifisering hører til på serveren.
4. Generer registreringsoptioner på serveren
Før kalling av WebAuthn, genererer backenden en registreringutfordring og -optioner.
Et typisk optioner-objekt ser slik ut:
{
"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
}
Dette er illustrativt JSON, ikke en komplett produksjonsrespons.
Flere felt er viktige.
rp.id identifiserer pålitelig-vert. For eksempel kan example.com bli brukt for passende underdomener av det domenet, underlagt WebAuthn's RP ID-valideringsregler.
user.id bør være en stabil, opaque konto-ID kodet som base64url for JSON-transport. Den bør ikke eksponere unødvendig personlig informasjon.
challenge må genereres ved hjelp av en kryptografisk sikkert tilfeldig kilde på serveren.
residentKey: "required" ber om en oppdagbar kreditiv, som er nødvendig for passkey-opplevelsen.
userVerification: "required" ber om lokal brukerverifisering, slik som en enhets-PIN eller biometisk godkjenning. Backenden må senere sjekke at verifisering faktisk skjedde.
Googles serversides registreringguide beskriver disse feltene og anbefaler bruk av en vedlikeholdt WebAuthn-bibliotek for å generere og validere registreringsdata.
5. Opprett passkey i JavaScript
Moderne nettlesere gir en nyttig metode:
PublicKeyCredential.parseCreationOptionsFromJSON()
Den konverterer en JSON-representasjon med base64url-kodet binære felt til strukturen forventet av WebAuthn.
Dette unngår å skrive kode for base64url-til-ArrayBuffer-konvertering for hvert felt.
Her er en forenklet nettleser-side registreringfunksjon:
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();
}
csrfToken-variabelen representerer en applikasjonslevert anti-CSRF-token. Serveren må validere den. Eksemplet antar også at siden allerede er knyttet til en sikkert autentisert bruker.
credential.toJSON() gir en JSON-vennlig representasjon av den returnerte kreditiv, unngår en annen lag med manuell binær serialisering.
Disse behagelighetene er tilgjengelige i nåværende nettlesere, selv om applikasjoner som støtter eldre nettleserversjoner bør gi kompatibilitetsbehandling.
Koden ovenfor er kun nettleser-siden. Den er ikke en komplett godkjenningsimplementering.
6. Hva serveren må verifisere under registrering
Når nettleseren returnerer den nye kreditiv, må backenden validere den før lagring.
Minimum må verifiseringsprosessen Fastslå at:
- Returnerte utfordringen matcher den som ble generert for dette registreringforsøket.
- Utfordringen er frisk og ikke allerede brukt.
- Rapporterte opprinnelsen matcher en eksplisitt pålitelig applikasjonsorigo.
- Autentiseringsdataen tilsvarer forventet RP ID.
- Krevede bruker-tilstedethet- og bruker-verifiseringsbetingelser er oppfylt.
- Kreditivens offentlige nøkkel og ID kan trekkes ut og valideres.
- Registreringen er knyttet til riktig autentisert konto.
Avhengig av applikasjonspolitikken, kan ytterligere sjekker inkludere støttede algoritmer, kreditivunikthet og attesteringskrav.
En vellykket registrering lagrer vanligvis:
| felt | Formål |
|---|---|
credential_id |
Identifiserer kreditiv |
user_id |
Knytter den til en konto |
public_key |
Verifiserer fremtidige signaturer |
sign_count |
Sporer autentiserings-tellerdata |
transports |
Valgfritt autentiserings-transport-hint |
created_at |
Registrerings-tidsstempel |
last_used_at |
Kontohåndtering og revisjon |
backup_eligible / backup_state |
Valgfritt sikkerhetskopieringsrelatert metadata |
Den nøyaktige databaserepresentasjonen avhenger av verifiseringsbiblioteket og applikasjonen.
Ikke implementer CBOR-analyse, attesteringsverifisering eller kryptografisk signaturverifisering fra bunnen med mindre du har en god grunn og kompetanse til å vedlikeholde den.
W3C-spesifikasjonen definerer detaljerte registrering- og godkjenningsverifiseringsrutiner.
7. Godkjenn en eksisterende bruker
Godkjenning følger en liknende struktur, men oppretter ikke et nytt nøkkelpar.
Serveren genererer en ny utfordring og sender godkjenningsoptioner til nettleseren.
For en oppdagbar passkey-innlogging, kan disse optionene inneholde:
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
Nettleseren kan deretter be om en kreditiv:
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();
}
Dette eksemplet antar at backenden knytter den utstedte utfordlingen til en kortvarig, anonym innloggtransaksjon, anvender passende hastighetsbegrensning og etablerer en ny autentisert økt bare etter vellykket verifisering.
Serveren må slå opp kreditiv-ID-en, verifisere signatur med lagret offentlig nøkkel, bekrefte utfordlingen og opprinnelsen, og håndheve brukerverifiserings-politikken.
Bare da skal den etablerer brukerens økt.
parseRequestOptionsFromJSON() er en del av moderne WebAuthn API og fjerner behovet for manuell avkoding av binære felt i vanlige nettleser-side-integrasjoner.
8. Legg til passkeys i eksisterende innloggingsformer med betinget mediatin
En av de mest nyttige WebAuthn-funksjonene er betinget mediatin, noe som også kalles passkey-automatfylling.
I stedet for å vise en egen passkey-dialog med en gang, kan nettleseren tilby en tilgjengelig passkey sammen med andre lagrede kreditiver når brukeren interagerer med et innloggingsfelt.
HTML-inndata kan bruke:
<input
type="text"
name="username"
autocomplete="username webauthn"
>
Applikasjonen kan sjekke for støtte:
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
Når du kaller navigator.credentials.get(), bruker applikasjonen:
{
publicKey,
mediation: 'conditional'
}
For oppdagbar kreditiv-automatfylling, bør serverens optioner ikke begrense forespørselen til en spesiell liste over kreditiv-ID-er.
Betinget mediatin er spesielt nyttig under en gradvis migrering fra passord fordi brukere ikke trenger å huske om en bestemt konto har en passkey.
Nettleseren kan presenter en passende valg i den kjente innloggingsopplevelsen.
9. Hvorfor utfordring- og opprinnelsessjekker er avgjørende
Passkeys er mot phishing, men det betyr ikke at en applikasjon kan ignorere sin godkjenningsprotokoll.
Utfordringen beskytter mot gjenbruk.
Uten en frisk, uforutsigbar utfordring, kan en angriper forsøke å gjenbruke godkjenningsdata fra en tidligere økt.
Opprinnels- og RP ID-sjekkene sikrer at kreditiver brukes i riktig nettstedskontekst.
For eksempel kan en passkey opprettet for example.com ikke bare bli gjenbrukt av en lignende phishing-side som examp1e.com.
Nettleseren og autentiseringen håndhever viktige deler av dette domenebindinget, mens backenden uavhengig validerer det resulterende beviset.
En god implementering bruker kortvarige utfordringer, bruker hver utfordring én gang og aksepterer aldri vilkårlige opprinnelser bare fordi de deler en kjent ser ut som vertsnavn.
MDN anbefaler å generere utfordringer i en pålitelig miljø og ugyldiggjøre dem etter en kort periode, vanligvis ikke mer enn omtrent ti minutter.
10. Ikke misforstå signatur-tellere
WebAuthn-autentiseringer kan inkludere en signatur-teller.
Historisk har tellere hjulpet til å oppdage potensielt kløddede autentiseringer. Hvis en teller uventet stopper å øke, kan pålitelig-vert vurdere dette som en risikosignal.
Men ikke alle autentiseringer vedlikeholder en meningsfull teller.
Noen kreditiver rapporterer alltid null. Synkroniserte kreditiver kan også komplisere tellerinterpetering fordi flere enheter kan bruke kopier av samme kreditiv.
W3C-spesifikasjonen behandler eksplisitt uventet telleratferd som et mulig signal, ikke som entydig bevis på klødd.
Utviklere bør derfor ikke blindt avvise hver innlogging hvis telleren er null eller uendret.
Bruk telleren i henhold til autentiseringens oppførsel, WebAuthn-verifiseringsbibliotekets anvisning og applikasjonens sikkerhetspolicy.
11. Konto-gjenoppretting er en del av passkey-sikkerhet
En passkey-implementering er usammenstendelig uten en gjenoppretningsstrategi.
Hva skjer når en bruker mistet en enhet?
Hva hvis de sletter sin eneste passkey?
Hva hvis de bytter kreditivleverandør eller ikke kan få tilgang til en synkronisert kreditiv?
En fornuftig design tillater brukere å registrere flere passkeys og administrere dem fra kontoinnstillinger.
Administrasjonsgrensesnittet bør vise gjenkjennelige kreditivnavn, opprettelsesdatoer og nylig brukt informasjon der tilgjengelig.
Brukere bør kunne trekke tilbake kreditiver de ikke lenger stoler på.
Men gjenoppretningsmekanismen fortjener spesiell forsiktighet.
Hvis en angriper kan omgå passkey-godkjenning ved hjelp av en svak e-post-gjenoppretningsprosess, er den ålåne kontoen bare like sikkert som den gjenoppretningsveien.
For høyere-risiko-kontoer, vurder sterkere gjenoppretningsverifisering, gjenoppretningskoder, flere registrert autentiseringer og varsler om sensitive kontoweddinger.
Googles passkey UX-veiledning anbefaler å etablere en gjenoppretningsmetode og støtte flere passkeys der det er passende.
12. Vanlige implementeringsfeil
Flere feil undergraver gjentatte ganger ellers lover promise passkey-integrasjoner.
Å behandle nettleser-suksess som server-godkjenning. En løst navigator.credentials.get() promise er ikke erstatning for server-sides kryptografisk verifisering.
Generering av utfordringer i JavaScript. Utfordringer bør komme fra en pålitelig server og knyttes til riktig godkjennings-transaksjon.
Å bruke feil RP ID. Domene-omfattelse er en sikkerhetsfunksjon, ikke en kosmetisk innstilling. Produksjon, testing og lokal utvikling krever bevisst konfigurering.
Å anta at alle passkeys synkroniseres. Enhetsknyttne kreditiver er fortsatt en viktig del av økosystemet.
Å glemme kreditivtilbakekalling. Brukere trenger en måte å fjerne en mistet eller kompromittert autentisering fra kontoen sin.
Å skape en svak fallback. En phishing-motstålig innlogging mister mye av verdien hvis konto-gjenoppretning kan udnyttes lettert.
Å ignorere gamle nettlesere. Moderne JSON-metoder reduserer kompleksitet, men applikasjoner med eldre nettleserkrav må fortsatt ha kompatibilitetskode.
Å hoppe over CSRF og øksproteksjon. Registrering og kreditivhåndteringsoperasjoner er følsomme kontoendringer. De trenger samme beskyttelse som andre høy-innvirkningskonto-aksjoner.
Å skrive egendefinert kryptografisk verifisering unødvendig. Et vedlikeholdt WebAuthn-serverbibliotek er vanligvis en tryggere valg enn å implementere spesifikasjonen direkte.
13. Skal hver nettside erstatte passord med en gang?
Ikke nødvendig.
Passkeys kan forbedre både brukervennlighet og sikkerhet, men migreringsstrategi er viktig.
For en ny applikasjon kan passordløs registrering være en rimelig standard hvis produktet har en god designet gjenoppretningsstrøm og støtter sine målnettlesere.
For en eksisterende applikasjon med tusenvis av brukere er gradvis adoptering ofte tryggere.
Start ved å tillate autentiserte brukere å registrere passkeys i kontoinnstillinger.
Legg deretter til passkey-innlogging ved siden av det eksisterende godkjenningssystemet.
Introduser betinget mediatin der støttet.
Mål registreringssukksess, godkjenningsfeil, enhetskompatibilitet og gjenoppretningsforespørsler.
Til slutt, vurter å gjøre passkeys til det foretrukne godkjenningsmetoden når brukererfaringen og gjenoppretningsmekanismene er tilstrekkelig moden.
En fasefull rulling også gjør det letterig å identifisere nettleser-spesifikke problemer uten å låse ut lovlige brukere ute.
14. Produksjonsklarhet sjekkliste
Før å aktivere passkeys i produksjon, verifiser følgende:
- Alle WebAuthn-operasjoner kjører i en passende sikkert kontekst.
- RP ID-er og pålitelige opprinnelser er eksplisitt konfigurert.
- Utfordringer er kryptografisk tilfeldig, kortvarig og brukes én gang.
- Registrering krever passende kontoautorisering.
- Server-sides verifisering følger WebAuthn-spesifikasjonen.
- Offentlige nøkler og kreditiv-ID-er lagres trygt.
- Innlogging etablerer en økt bare etter vellykket verifisering.
- Bruker-verifiseringskrav er håndhevet på serveren.
- Kreditivfjerning og konto-gjenoppretning er beskyttet.
- Flere kreditiver per konto støttes der det er passende.
- Godkjenningsfeil og sikkerhetsfølsomme kontoweddinger overvakes.
- Mobil, desktop, tvers-enhet og maskinvare-nøkkel-scenarier tester.
Disse sjekkene er viktigere enn om frontenden kan vise en tiltrkkelig biometrisk innloggingsmelding.
Konklusjon: Passkeys er en godkjenningsarkitektur, ikke bare en nettleser-funksjon
WebAuthn gjør offentlig-nøkkel-godkjenning tilgjengelig for vanlige web-applikasjoner.
Moderne nettleser API-er har fjernet mye av serialiseringen som tidligere gjorde passkey-integrasjon tung.
Men nettleseren er kun en del av systemet.
Den ekte implementeringsarbeidet ligger i utfordringshåndtering, server-sides verifisering, kreditivlagring, domene-konfigurering, konto-gjenoppretning og sikker bruker-reise.
For utviklere som bygger moderne applikasjoner i PHP, JavaScript, Python eller andre backend-miljøer, er passkeys ofte verdt å vurdere som en praktisk alternativ til tradisjonelle passord.
Den beste startpunktet er ikke å erstatte en hele godkjenningssystem i én natt.
Det er å implementere én komplett, korrekt verifisert registrering og innloggstrøm, deretter bygge en sikker migreringsstrategi rundt den.