Passkeys și WebAuthn în 2026: Ghid practic de implementare pentru dezvoltatori web
Passkeys promit autentificare fără parolă fără a stoca secretele parolei, însă implementarea corectă a WebAuthn necesită mai mult decât apelarea unei API-uri de browser. Aflați cum înregistrarea, autentificarea, verificarea pe server, credențialele descoperabile și recuperarea contului se combină într-o aplicație web sigură.
Passkeys și WebAuthn în 2026: Un ghid practic de implementare pentru dezvoltatori web
Parolele au fost mecanismul de autentificare implicit pentru aplicațiile web de decenii. De asemenea, sunt o sursă persistentă de probleme de securitate.
Utilizatorii le reutilizează. Atacatorii le fură prin phishing. Serverele trebuie să protejeze hash-urile parolelor, să gestioneze resetările și să apere împotriva atacurilor de tip credential stuffing.
Passkeys oferă o abordare fundamentală diferită.
În loc să ceră utilizatorilor să înceapă un secret comun, passkeys utilizează criptografia cu cheie publică și un autentificator controlat de utilizator. Browserul oferă o interfață standard prin WebAuthn, în timp ce serverul verifică dovezile criptografice că a fost folosită credențiala corectă.
Tehnologia nu mai este experimentală. WebAuthn este disponibil în mod larg în browserele moderne, iar metodele sale de comoditate JSON au simplificat integrarea considerabil.
Dar construirea unui login securizat cu passkey necesită încă o proiectare atentă a backend-ului.
Acest ghid explică arhitectura, demonstrează fluxurile din partea browserului și identifică verificările din partea serverului pe care dezvoltatorii nu le pot ignora.
1. Ce este exact un passkey?
Un passkey este o credențială FIDO descoperibilă folosită pentru autentificarea unui utilizator prin criptografia cu cheie publică.
Înregistrarea, un autentificator creează o pereche de chei criptografice.
Cheia privată rămâne protejată de autentificator sau de ecosystemul său de gestionare a credențialelor. Site-ul web primește cheia publică corespunzătoare și o asociază cu contul utilizatorului.
În timpul autentificării, serverul emite o provocare proaspătă. Autentificatorul semnează datele asociate acelei provocării, iar serverul verifică semnatura folosind cheia publică stocată.
Nu există o parolă reutilizabilă trimisă către site-ul web.
Un autentificator poate fi un smartphone, un computer folosind Windows Hello, o cheie de securitate hardware sau un gestionar de credențiale care suportă passkeys sincronizate.
Nu fiecare passkey este sincronizat între dispozitive. Unele credențiale rămân legate de dispozitiv, în timp ce altele pot fi stocate în siguranță și puse la dispoziție printr-un furnizor de credențiale.
Specificațiile FIDO sunt proiectate să reziste phishingului prin legarea credențialelor de domeniul partidului de încredere. Datele biometrice, atunci când sunt folosite, sunt procesate local de dispozitiv, în loc să fie trimise către site-ul web.
2. WebAuthn este API-ul browserului din spatele passkey-urilor
WebAuthn este API-ul platformei web care permite site-urilor web să creeze și să folosească credențiale cu cheie publică.
Două metode browser formează baza:
navigator.credentials.create()
navigator.credentials.get()
Prima creează o credențială. A doua solicită autentificarea folosind o credențială existentă.
Ambele metode funcționează cu opțiunea publicKey și cer un context securizat, în mod normal HTTPS.
Importativ, browserul nu decide dacă utilizatorul este autentificat. Returnează date pe care backend-ul trebuie să le verifice.
Un prompt browser reușit nu este o dovadă că un login ar trebui acceptat.
Serverul rămâne responsabil pentru verificarea provocării, originii, identificatorului partidului de încredere și a dovezilor criptografice.
3. Înțelegi arhitectura completă
O implementare tipică conține patru componente:
- Aplicația web frontend, care invocă WebAuthn.
- Backend-ul aplicației, care generează provocări și verifică răspunsuri.
- Autentificatorul sau furnizorul de passkey, care protejează cheia privată.
- Baza de date, care stornează metadatele credențialei și cheile publice.
Fluxul de înregistrare este: aplicația web solicită opțiuni de înregistrare; backend-ul generează o provocare și date ale utilizatorului; browserul și autentificatorul creează o credențială și o pereche de chei; iar backend-ul verifică rezultatul și storează cheia publică.
Serverul nu trebuie să aibă încredere în datele de înregistrare doar pentru că au fost returnate de browser.
Un client rău intenționat poate trimite cereri HTTP arbitrare fără a folosi frontend-ul așteptat.
De aceea verificarea aparține serverului.
4. Generează opțiuni de înregistrare pe server
Înainte de a apela WebAuthn, backend-ul generează o provocare de înregistrare și opțiuni.
Un obiect opțiuni reprezentativ arată astfel:
{
"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
}
Acesta este un JSON ilustrativ, nu un răspuns complet de producție.
Mai multe câmpuri sunt importante.
rp.id identifică partidul de încredere. De exemplu, example.com poate fi folosit pentru subdomeniile corespunzătoare ale acelui domeniu, supus regulilor de validare RP ID ale WebAuthn.
user.id ar trebui să fie un identificator de cont stabil, opac, codat ca base64url pentru transport JSON. Nu ar trebui să expună informații personale necesar.
challenge trebuie generat folosind o sursă aleatoare criptografic securizată pe server.
residentKey: "required" solicită o credențială descoperibilă, care este necesară pentru experiența passkey.
userVerification: "required" solicită verificarea locală a utilizatorului, cum ar fi un PIN dispozitiv sau autentificare biometrică. Backend-ul mai târziu trebuie să verifice că verificarea a avut loc cu adevărat.
Ghidul de înregistrare de partea serverului Google descrie aceste câmpuri și recomandă folosirea unei biblioteci WebAuthn întreținute pentru generarea și validarea datelor de înregistrare.
5. Creați passkey în JavaScript
Browserele moderne oferă o metodă utilă:
PublicKeyCredential.parseCreationOptionsFromJSON()
Aceasta convertește o reprezentare JSON conținând câmpuri binare codate base64url în structura așteptată de WebAuthn.
Aceasta evită scrierea logicii de conversie personalizate base64url-to-ArrayBuffer pentru fiecare câmp.
Iată o funcție de înregistrare simplificată din partea browserului:
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();
}
Variabila csrfToken reprezintă un token anti-CSRF furnizat de aplicație. Serverul trebuie să îl validateze. Exemplul presupune, de asemenea, că pagina este deja asociaată cu un utilizator autentificat securizat.
credential.toJSON() oferă o reprezentare prietenoasă JSON a credențialei returnate, evitând un alt strat de serializare binară manuală.
Aceste comodități sunt disponibile în browserele actuale, deși aplicațiile care suportă versiuni mai vechi de browser ar trebui să furnizeze gestionarea compatibilității.
Codul de mai sus este doar partea browser. Nu este o implementare completă de autentificare.
6. Ce trebuie verificat de server înregistrarea
Când browserul returnează noua credențială, backend-ul trebuie să o validate înainte de a stora orice.
La minim, procesul de verificare trebuie să stabilească că:
- Returnata provocare corespunde cu cea generată pentru această încercare de înregistrare.
- Provocarea este proaspătă și nu a fost deja consumată.
- Originea raportată corespunde unei origini de aplicație explicit de încredere.
- Datele autentificatorului corespund RP ID-ului așteptat.
- Condițiile de prezență a utilizatorului și de verificare a utilizatorului sunt îndeplinite.
- Cheia publică și identificatorul credențialei pot fi extrase și validate.
- Înregistrarea este asociață cu contul autentificat corect.
În funcție de politica aplicației, verificări suplimentare pot include algoritmii suportati, unicitatea credențialei și cerințele de atestare.
O înregistrare reușită stornează de obicei:
| Field | Purpose |
|---|---|
credential_id |
Identifies the credential |
user_id |
Links it to an account |
public_key |
Verifies future signatures |
sign_count |
Tracks authenticator counter data |
transports |
Optional authenticator transport hints |
created_at |
Registration timestamp |
last_used_at |
Account management and auditing |
backup_eligible / backup_state |
Optional backup-related metadata |
Reprezentarea exactă a bazei de date depinde de biblioteca de verificare și a aplicației.
Nu implementați analiza CBOR, verificarea atestării sau validarea semnaturilor criptografice de la zero, dacă aveți un motiv convingător și experiența să o mențineți.
Specificația W3C definește proceduri detaliate de verificare a înregistrării și a autentificării.
7. Autentifică un utilizator existent
Autentificarea urmează o structură similară, dar nu creează o nouă pereche de chei.
Serverul generează o nouă provocare și trimite opțiuni de autentificare către browser.
Pentru un login cu passkey descoperibil, aceste opțiuni ar putea conține:
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
Browserul poate atunci să solicite o credențială:
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();
}
Acest exemplu presupune că backend-ul asociază provocarea emisă cu o tranzacție de login anonimă cu durata scurtă, aplică limitarea corespunzătoare a ratei și stabilește o sesie autentificată nouă numai după verificarea cu success.
Serverul trebuie să caute ID-ul credențialei, să verifice afirmația semnată cu cheia publică stocată, să confirme provocarea și originea și să-și impună politica de verificare a utilizatorului.
Abia atunci ar trebui să stabilească sesia utilizatorului.
parseRequestOptionsFromJSON() face parte din API-ul modern WebAuthn și elimină necesitatea de a decod manual câmpurile binare în integrări comune din partea browserului.
8. Adăugați passkey-uri la formele de login existente cu mediere condițională
Una dintre cele mai utile funcții WebAuthn este medierea condițională, uneori numită autofill passkey.
În loc să afișeze imediat un dialog separat de passkey, browserul poate oferi un passkey disponibil alături de alte credențiale salvate atunci când utilizatorul interacționează cu un câmp de login.
Intrarea HTML poate folosi:
<input
type="text"
name="username"
autocomplete="username webauthn"
>
Aplicația poate verifica suportul:
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
Atunci când apelează navigator.credentials.get(), aplicația folosește:
{
publicKey,
mediation: 'conditional'
}
Pentru autofill-ul credențialei descoperibile, opțiunile serverului nu ar trebui să restrângă cererea la o listă specifică de ID-uri de credențiale.
Medierea condițională este deosebit utilă în tiempo unei migrări graduale de la parole, deoarece utilizatorii nu trebuie să își amintească dacă un anumit cont are un passkey.
Browserul poate prezenta opțiuni corespunzătoare în experiența de login familiară.
9. De ce verificările provocării și ale originii sunt esențiale
Passkey-urile sunt rezistente la phishing, dar asta nu înseamnă că o aplicație poate ignora protocolul său de autentificare.
Provocarea protejează împotriva atacurilor de replay.
Fără o provocare proaspătă și imprevizibilă, un atacator ar putea încerca să reutilizeze date de autentificare dintr-o sesiune precedentă.
Verificările originii și RP ID asigură că credențialele sunt folosite în contextul site-ului web intenționat.
De exemplu, un passkey creat pentru example.com nu poate fi simplu reutilizat de un site phishing similar cum ar fi examp1e.com.
Browserul și autentificatorul impun părți importante ale acestei legături de domeniu, în timp ce backend-ul validate independent dovezile rezultate.
O bună implementare folosește provocări cu durata scurtă, consumă fiecare provocare o dată și nu acceptă niciodată origini arbitrare doar pentru că partajă un nume de gazdă familiar.
MDN recomandă generarea provocărilor într-un încrezător mediu și anularea lor după o perioadă scurtă, în general nu mai mult de zece minute.
10. Nu înțelegeți greșit numărătoarele de semnătură
Autentificatoarele WebAuthn pot include un numărător de semnături.
Istoric, numărătoarele au ajutat la detectarea autentificatorilor potential clonați. Dacă un numărător oprește brusc creșterea, partidul de încredere poate considera acela un semnal de risc.
Cu toate acestea, nu fiecare autentificator menține un numărător semnificativ.
Unele credențiale raportează întotdeauna zero. Credențialele sincronizate pot complica, de asemenea, interpretarea numărătorului, deoarece mai multe dispozitive pot folosi copii ale aceleiași credențiale.
Specificația W3C tratează explicit comportamentul neașteptat al numărătorului ca un posibil semnal, nu ca o dovadă definitivă de clonare.
Prin urmare, dezvoltatorii nu ar trebui să respingă orb orice login la care numărătorul este zero sau neschimbat.
Folosiți numărătorul în funcție de comportamentul autentificatorului, îndrumarea bibliotecii de verificare WebAuthn și politica de securitate a aplicației.
11. Recuperarea contului face parte din securitatea passkey
O implementare a passkey este incompletă fără o strategie de recuperare.
Ce se întâmplă când un utilizator își pierde dispozitivul?
Ce dacă își șterge singurul passkey?
Ce dacă își schimbă furnizorii de credențiale sau nu pot accesa o credențială sincronizată?
Un design sensibil permite utilizatorilor să înregistreze mai multe passkey-uri și să le gestioneze din setările contului lor.
Interfața de gestionare ar arăta nume recunoștibile de credențiale, date de creștere și informații de utilizare recentă, acolo unde este disponibil.
Utilizatorii ar trebui să poată revoca credențialele pe care nu le mai doresc.
Dar mecanismul de recuperare merită o atenție deosebită.
Dacă un atacator poate ocoli autentificarea passkey folosind un proces slab de recuperare pe email, contul general este atât de securizat cât și calea de recuperare.
Pentru conturi cu risc mai ridicat, considerați verificare de recuperare mai puternică, coduri de recuperare, autentificatoare suplimentare înregistrate și notificări despre modificări sensibile ale contului.
Ghidul UX passkey Google recomandă stabilirea unei metode de recuperare și sprijinirea mai multor passkey-uri acolo unde este potrivit.
12. Erori comune de implementare
Mai multe erori submin repetat integrări promițătoare de passkey.
Tratarea succesului browserului ca autentificare server. O promisiune navigator.credentials.get() rezolvată nu înlocuiește verificarea criptografică de partea serverului.
Generarea provocărilor în JavaScript. Provocările ar trebui să vină dintr-un server de încredere și să fie legate de tranzacția de autentificare corespunzătoare.
Folosirea RP ID-ului greșit. Scopearea domeniului este o funcție de securitate, nu o setare cosmetică. Mediile de producție, staging și dezvoltare locală cer o configurare deliberată.
Presupunerea că toate passkey-urile se sincronizază. Credențialele legate de dispozitiv rămân o parte importantă a ecosystemului.
Uitarea revocării credențialei. Utilizatorii au nevoie de o modalitate de a înlătra un autentificator pierdut sau compromise din contul lor.
Crearea unei rezerve slabe. Un login rezistent la phishing își pierde mult din valoare dacă recuperarea contului poate fi exploatată ușor.
Ignorarea browserelor vechi. Metodele de comoditate JSON modernă reduc complexitatea, dar aplicațiile cu cerințe de browser mai vechi ar putea avea nevoie de cod de compatibilitate.
Sări peste protecția CSRF și a sesiunii. Înregistrarea și operațiile de gestionare a credențialelor sunt modificări sensibile ale contului. Au nevoie de aceleași protecții ca și alte acțiuni de înaltă impact asupra contului.
Scrierea unei verificări criptografice personalizate în mod inutil. O bibliotecă server WebAuthn întreținută este de obicei o alegere mai sigură decât implementarea directă a specificației.
13. Ar trebui fiecare site să înlocuiască imediat parolele?
Nu neapărat.
Passkey-urile pot îmbunătăți atât utilizabilitatea, cât și securitatea, dar strategia de migrare este importantă.
Pentru o nouă aplicație, înregistrarea fără parolă arpute fi o implicită rezonabilă, dacă produsul are un flux de recuperare bine proiectat și suportă platformele țintă.
Pentru o aplicație existentă cu mii de utilizatori, adoptarea incrementală este adesea mai sigură.
Începeți prin a permite utilizatorilor autentificați să înregistreze passkey-uri în setările contului.
Apoi adăugați login cu passkey alături de sistemul de autentificare existent.
Introduceți medierea condițională acolo unde este suportat.
Măsurați succesul înregistrării, eșecurilor de autentificare, compatibilitatea dispozitivelor și cererile de recuperare.
În cele din urmă, considerați faceți passkey-urile metoda de autentificare preferată odată ce experiența utilizatorului și mecanismele de recuperare sunt suficient mature.
O lansare făcută pe faze face mai ușor să identificați probleme specifice browserului, fără a exclude utilizatorii legitimi.
14. O listă de verificare pentru pregătirea producției
Înainte de a activa passkey-urile în producție, verificați următorul:
- Toate operațiile WebAuthn rulează într-un context securizat corespunzător.
- RP ID-urile și originile de încredere sunt configurate explicit.
- Provocările sunt criptografic aleatorii, cu durata scurtă și unică.
- Înregistrarea necesită autorizarea corespunzătoare a contului.
- Verificarea de partea serverului urmează specificația WebAuthn.
- Cheile publice și identificatorii credențialei sunt stocați în siguranță.
- Loginul stabilește o sesie numai după verificarea cu success.
- Cerințele de verificare a utilizatorului sunt impuse pe server.
- Ștergerea credențialei și recuperarea contului sunt protejate.
- Mai multe credențiale pe cont sunt suportate acolo unde este potrivit.
- Eșecurile de autentificare și modificările sensibile ale contului sunt monitorizate.
- Scenariile mobil, desktop, cross-device și hardware-key sunt testate.
Aceste verificări mai mult decât dacă frontend-ul poate afișa un prompt biometric atractiv.
Concluzia: passkey-urile sunt o arhitectură de autentificare, nu doar o funcție browser
WebAuthn face autentificarea cu cheie publică accesibilă aplicațiilor web obișnuite.
API-urile browser moderne au înlăturat mult din munca de serializare care anterior făcea integrarea passkey-urilor cuminoasă.
Dar browserul este doar o parte a sistemului.
Munca reală de implementare constă în gestionarea provocărilor, verificarea de partea serverului, stocarea credențialelor, configurația domeniului, recuperarea contului și traseelor securizate ale utilizatorului.
Pentru dezvoltatorii care construiesc aplicații moderne în PHP, JavaScript, Python sau alte medii backend, passkey-urile din ce în ce mai mult merită considerate ca o alternativă practică la parolele tradiționale.
Cel mai bun punct de start nu este să înlocuiești un sistem de autentificare complet peste noapte.
Este să implementezi un flux complet, corect verificat de înregistrare și login, apoi să construiești o strategie de migrare securizată în jurul său.