Passkeys e WebAuthn nel 2026: Una Guida Pratica di Implementazione per Sviluppatori Web
I passkeys promettono l'accesso senza password senza memorizzare segreti di password, ma implementare correttamente WebAuthn richiede più di chiamare un'API del browser. Scopri come registrazione, autenticazione, verifica lato server, credenziali scoprite e recupero account si combinano in un'applicazione web sicura.
Chiavi di accesso e WebAuthn nel 2026: Una guida pratica all'implementazione per sviluppatori web
Le password sono stati il meccanismo di autenticazione predefinito per le applicazioni web per decenni. Sono anche una fonte persistente di problemi di sicurezza.
Gli utenti le riutilizzano. Gli attaccanti le rubano attraverso il phishing. I server devono proteggere le hash delle password, gestire i reimpostazioni e difendersi dagli attacchi di tipo credential-stuffing.
Le chiavi di accesso offrono un approccio fondamentalmente diverso.
Invece di chiedere agli utenti di memorizzare un segreto condiviso, le chiavi di accesso utilizzano la crittografia a chiave pubblica e un'autenticatore controllato dall'utente. Il browser fornisce un'interfaccia standard attraverso WebAuthn, mentre il server verifica le prove crittografiche che il credential corretto sia stato utilizzato.
La tecnologia non è più sperimentale. WebAuthn è ampiamente disponibile nei browser moderni, e i suoi metodi di convenienza JSON hanno semplificato notevolmente l'integrazione.
Ma costruire un accesso con chiavi di accesso sicuro richiede comunque un'attenta progettazione del backend.
Questa guida spiega l'architettura, dimostra i flussi lato browser e identifica i controlli lato server che gli sviluppatori non devono mai trascurare.
1. Cos'è esattamente una chiave di accesso?
Una chiave di accesso è un credential FIDO scopribile utilizzato per autenticare un utente attraverso la crittografia a chiave pubblica.
Durante la registrazione, un'autenticatore crea una coppia di chiavi crittografiche.
La chiave privata rimane protetta dall'autenticatore o dal suo ekosistema di gestione dei credential. Il sito web riceve la corrispondente chiave pubblica e la associa all'account dell'utente.
Durante l'autenticazione, il server emette una nuova sfida. L'autenticatore firma i dati associati a quella sfida, e il server verifica la firma utilizzando la chiave pubblica memorizzata.
Non viene inviata alcuna password riutilizzabile al sito web.
Un'autenticatore potrebbe essere uno smartphone, un computer che utilizza Windows Hello, una chiave di sicurezza hardware o un gestore di credential che supporta chiavi di accesso sincronicizzate.
Non tutte le chiavi di accesso sono sincronicizzate tra dispositivi. Alcuni credential rimangono legati al dispositivo, mentre altri possono essere backup in modo sicuro e resi disponibili attraverso un provider di credential.
Le specifiche FIDO sono progettate per resistere al phishing legando i credential al dominio del fornitore di affidabilità. I dati biometrici, quando vengono utilizzati, vengono gestiti localmente dal dispositivo anziché essere inviati al sito web.
2. WebAuthn è l'API del browser dietro le chiavi di accesso
WebAuthn è l'API della piattaforma web che permette ai siti web di creare e utilizzare credential a chiave pubblica.
Due metodi del browser formano la base:
navigator.credentials.create()
navigator.credentials.get()
Il primo crea un credential. Il secondo richiede l'autenticazione utilizzando un credential esistente.
Entrambi i metodi funzionano con l'opzione publicKey e richiedono un contesto sicuro, normalmente HTTPS.
Importante, il browser non decide se l'utente è autenticato. Restituisce dati che il backend deve verificare.
Un prompt riuscito nel browser non è prova che un accesso dovrebbe essere accettato.
Il server rimane responsabile della verifica della sfida, dell'origine, dell'identificatore del fornitore di affidabilità e delle prove crittografiche.
3. Comprendere l'architettura completa
Un'implementazione tipica contiene quattro componenti:
- Il frontend dell'applicazione web, che invoca WebAuthn.
- Il backend dell'applicazione, che genera sfide e verifica le risposte.
- L'autenticatore o il provider di chiavi di accesso, che protegge la chiave privata.
- Il database, che memorizza i metadati del credential e le chiavi pubbliche.
Il flusso di registrazione è: l'applicazione web richiede le opzioni di registrazione; il backend genera una sfida e dati utente; il browser e l'autenticatore creano un credential e una coppia di chiavi; infine il backend verifica il risultato e memorizza la chiave pubblica.
Il server non deve mai fidarsi dei dati di registrazione solo perché sono stati restituiti dal browser.
Un client malizioso può inviare richieste HTTP arbitrarie senza utilizzare affatto il frontend previsto.
Questo è il motivo per cui la verifica appartiene al server.
4. Generare le opzioni di registrazione sul server
Prima di chiamare WebAuthn, il backend genera una sfida di registrazione e opzioni.
Un oggetto opzioni rappresentativo appare così:
{
"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
}
Questo è JSON illustrativo, non una risposta completa pronta per la produzione.
Diversi campi sono importanti.
rp.id identifica il fornitore di affidabilità. Ad esempio, example.com può essere utilizzato per sottodomini appropriati di quel dominio, soggetto alle regole di convalida dell'ID RP di WebAuthn.
user.id dovrebbe essere un identificatore account stabile e opaco codificato come base64url per il trasporto JSON. Non dovrebbe esporre informazioni personali non necessarie.
challenge deve essere generato utilizzando una fonte casuale crittograficamente sicura sul server.
residentKey: "required" richiede un credential scopribile, necessario per l'esperienza delle chiavi di accesso.
userVerification: "required" richiede la verifica dell'utente locale, come un PIN del dispositivo o l'autenticazione biometrica. Il backend deve successivamente verificare che la verifica sia effettivamente avvenuta.
La guida del server di Google per la registrazione descrive questi campi e raccomanda l'uso di una libreria WebAuthn mantenuta per generare e convalidare i dati di registrazione.
5. Creare la chiave di accesso in JavaScript
I browser moderni forniscono un metodo utile:
PublicKeyCredential.parseCreationOptionsFromJSON()
Converte una rappresentazione JSON contenente campi binari codificati in base64url nella struttura prevista da WebAuthn.
Questo evita di scrivere logica di conversione personalizzata da base64url ad ArrayBuffer per ogni campo.
Ecco una semplificata funzione di registrazione lato browser:
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();
}
La variabile csrfToken rappresenta un token anti-CSRF fornito dall'applicazione. Il server deve validarlo. L'esempio assume inoltre che la pagina sia già associata a un utente autenticato in modo sicuro.
credential.toJSON() fornisce una rappresentazione amichevole di JSON del credential restituito, evitando un'altra serie di serializzazione binaria manuale.
Queste comodità sono disponibili nei browser attuali, anche se le applicazioni che supportano versioni più vecchie dei browser dovrebbero fornire gestione della compatibilità.
Il codice sopra è solo il lato browser. Non è un'implementazione completa di autenticazione.
6. Cosa il server deve verificare durante la registrazione
Quando il browser restituisce il nuovo credential, il backend deve convalidarlo prima di memorizzare qualsiasi cosa.
Al minimo, il processo di verifica deve stabilire che:
- La sfida restituita corrisponde a quella generata per questo tentativo di registrazione.
- La sfida è fresca e non è già stata utilizzata.
- L'origine riportata corrisponde a un'origine applicativa esplicitamente attendibile.
- I dati dell'autenticatore corrispondono all'ID RP previsto.
- Le condizioni necessarie di presenza utente e verifica utente sono soddisfatte.
- La chiave pubblica e l'identificatore del credential possono essere estratti e validati.
- La registrazione è associata al account autenticato corretto.
A seconda della politica dell'applicazione, controlli aggiuntivi possono includere algoritmi supportati, unicità del credential e requisiti di attestazione.
Una registrazione riuscita memorizza tipicamente:
| Campo | Scopo |
|---|---|
credential_id |
Identifica il credential |
user_id |
Lo collega a un account |
public_key |
Verifica le firme future |
sign_count |
Traccia i dati del contatore dell'autenticatore |
transports |
Suggerimenti di trasporto dell'autenticatore opzionali |
created_at |
Timestamp di registrazione |
last_used_at |
Gestione account e auditoria |
backup_eligible / backup_state |
Metadati opzionali relativi al backup |
La rappresentazione esatta del database dipende dalla libreria di verifica e dall'applicazione.
Non implementare l'analisi di CBOR, la verifica dell'attestazione o la convalida delle firme crittografiche da zero a meno che non si abbia un motivo compellinge e l'esperienza per mantenerle.
La specifica W3C definisce procedure dettagliate di verifica della registrazione e dell'autenticazione.
7. Autenticare un utente esistente
L'autenticazione segue una struttura simile ma non crea una nuova coppia di chiavi.
Il server genera una nuova sfida e invia le opzioni di autenticazione al browser.
Per un accesso con chiave di accesso scopribile, quelle opzioni potrebbero contenere:
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
Il browser può quindi richiedere un credential:
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();
}
Questo esempio assume che il backend associ la sfida emessa a una transazione di accesso anonima e a breve termine, applichi un limite appropriato e stabilisca una nuova sessione autenticata solo dopo una verifica riuscita.
Il server deve cercare l'ID del credential, verificare l'asserzione firmata con la chiave pubblica memorizzata, confermare la sfida e l'origine, e applicare la sua politica di verifica utente.
Solo dopo allora dovrebbe stabilire la sessione dell'utente.
parseRequestOptionsFromJSON() fa parte dell'API WebAuthn moderna e elimina la necessità di decodificare manualmente i campi binari nelle integrazioni comuni lato browser.
8. Aggiungere chiavi di accesso ai moduli di login esistenti con mediazione condizionale
Una delle funzionalità WebAuthn più utili è la mediazione condizionale, a volte chiamata compilazione automatica delle chiavi di accesso.
Invece di mostrare immediatamente un dialogo separato per le chiavi di accesso, il browser può offrire una chiave di accesso disponibile insieme ad altre credenziali salvate quando l'utente interagisce con un campo di login.
L'input HTML può utilizzare:
<input
type="text"
name="username"
autocomplete="username webauthn"
>
L'applicazione può controllare il supporto:
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
Chiamando navigator.credentials.get(), l'applicazione utilizza:
{
publicKey,
mediation: 'conditional'
}
Per la compilazione automatica dei credential scopribili, le opzioni del server non dovrebbero limitare la richiesta a un elenco specifico di ID credential.
La mediazione condizionale è particolarmente utile durante una migrazione graduale da password perché gli utenti non devono ricordare se un determinato account ha una chiave di accesso.
Il browser può presentare le opzioni appropriate nell'esperienza di login familiare.
9. Perché i controlli della sfida e dell'origine sono essenziali
Le chiavi di accesso sono resistenti al phishing, ma questo non significa che un'applicazione possa ignorare il suo protocollo di autenticazione.
La sfida protegge contro attacchi di riproduzione.
Senza una sfida fresca e imprevedibile, un attaccante potrebbe tentare di riutilizzare i dati di autenticazione da una sessione precedente.
I controlli dell'origine e dell'ID RP garantiscono che i credential vengano utilizzati nel contesto del sito web previsto.
Ad esempio, una chiave di accesso creata per example.com non può semplicemente essere riutilizzata da un sito di phishing simile come examp1e.com.
Il browser e l'autenticatore applicano le parti importanti di questo vincolo di dominio, mentre il backend valida indipendentemente le prove risultanti.
Un'implementazione buona utilizza sfide a breve termine, consuma ogni sfida una volta e non accetta mai origini arbitrarie solo perché condividono un hostname familiare.
MDN raccomanda di generare le sfide in un ambiente attendibile e invalidarle dopo un breve periodo, generalmente non più di circa dieci minuti.
10. Non fraintendere i contatori di firma
Gli autenticatori WebAuthn possono includere un contatore di firma.
Storicamente, i contatori aiutavano a rilevare autenticatori potenzialmente clonati. Se un contatore smette improvvisamente di aumentare, il fornitore di affidabilità potrebbe considerare questo un segnale di rischio.
Tuttavia, non ogni autenticatore mantiene un contatore significativo.
Alcuni credential riportano sempre zero. I credential sincronizzati possono anche complicare l'interpretazione del contatore perché più dispositivi potrebbero utilizzare copie dello stesso credential.
La specifica W3C tratta esplicitamente il comportamento imprevisto del contatore come un possibile segnale, non come prova definitiva di clonazione.
Pertanto, gli sviluppatori non dovrebbero rifiutare all'insguire ogni accesso il cui contatore è zero o rimasto invariato.
Utilizzare il contatore secondo il comportamento dell'autenticatore, le linee guida della libreria di verifica WebAuthn e la politica di sicurezza dell'applicazione.
11. Il recupero account fa parte della sicurezza delle chiavi di accesso
Un'implementazione delle chiavi di accesso è incompleta senza una strategia di recupero.
Cosa succede quando un utente perde un dispositivo?
Cosa succede se elimina la sua unica chiave di accesso?
Cosa succede se cambia provider di credential o non può accedere a un credential sincronizzato?
Un design sensato permette agli utenti di registrare più chiavi di accesso e gestirle dalle impostazioni dell'account.
L'interfaccia di gestione dovrebbe mostrare nomi di credential riconoscibili, date di creazione e informazioni sull'uso recente quando disponibili.
Gli utenti dovrebbero poter revocare i credential in cui non fidano più.
Ma il meccanismo di recupero merita particolare attenzione.
Se un attaccante può aggirare l'autenticazione con le chiavi di accesso utilizzando un processo di recupero email debole, l'account complessivo è solo sicuro quanto quel percorso di recupero.
Per account a rischio elevato, considerare verifiche di recupero più forti, codici di recupero, autenticatori aggiuntivi registrati e notifiche su modifiche sensibili all'account.
Le linee guida UX di Google per le chiavi di accesso raccomandano di stabilire un metodo di recupero e supportare più chiavi di accesso dove appropriato.
12. Errori comuni di implementazione
Diversi errori sottominano ripetutamente le integrazioni promettenti delle chiavi di accesso.
Trattare il successo del browser come autenticazione del server. Una promessa navigator.credentials.get() risolta non sostituisce la verifica crittografica lato server.
Generare sfide in JavaScript. Le sfide dovrebbero provenire da un server attendibile e essere legate alla transazione di autenticazione appropriata.
Utilizzare l'ID RP errato. L'ambito del dominio è una funzionalità di sicurezza, non un'impostazione cosmica. Ambienti di produzione, staging e sviluppo locale richiedono configurazioni deliberata.
Assumere che tutte le chiavi di accesso siano sincronicizzate. I credential legati al dispositivo rimangono una parte importante dell'ecosistema.
Dimenticare la revoca del credential. Gli utenti hanno bisogno di un modo per rimuovere un autenticatore perso o compromesso dal loro account.
Creare un fallback debole. Un accesso resistente al phishing perde gran parte del suo valore se il recupero dell'account può essere sfruttato facilmente.
Ignorare i browser vecchi. I moderni metodi di convenienza JSON riducono la complessità, ma le applicazioni con requisiti di browser più vecchi potrebbero comunque aver bisogno di codice di compatibilità.
Saltare la protezione CSRF e delle sessioni. Le operazioni di registrazione e gestione dei credential sono modifiche sensibili all'account. Hanno bisogno delle stesse protezioni delle altre azioni di account ad alto impatto.
Implementare la verifica crittografica personalizzata senza necessità. Una libreria server WebAuthn mantenuta è generalmente una scelta più sicura che implementare direttamente la specifica.
13. Ogni sito web dovrebbe sostituire le password immediatamente?
Non necessariamente.
Le chiavi di accesso possono migliorare sia l'usabilità che la sicurezza, ma la strategia di migrazione è importante.
Per una nuova applicazione, la registrazione senza password potrebbe essere un'impostazione ragionevole predefinita se il prodotto ha un flusso di recupero ben progettato e supporta le piattaforme target.
Per un'applicazione esistente con migliaia di utenti, l'adozione incrementale è spesso più sicura.
Iniziare permettendo agli utenti autenticati di registrare chiavi di accesso nelle impostazioni dell'account.
Aggiungere quindi l'accesso con chiavi di accesso insieme al sistema di autenticazione esistente.
Introdurre la mediazione condizionale dove supportata.
Misurare il successo della registrazione, i fallimenti di autenticazione, la compatibilità con i dispositivi e le richieste di recupero.
Infine, considerare di rendere le chiavi di accesso il metodo di autenticazione preferito una volta che l'esperienza utente e i meccanismi di recupero siano sufficientemente maturi.
Un rollout frammentato facilita anche l'identificazione di problemi specifici del browser senza bloccare gli utenti legittimi.
14. Un controllo di prontezza per la produzione
Prima di abilitare le chiavi di accesso in produzione, verificare quanto segue:
- Tutte le operazioni WebAuthn vengono eseguite in un contesto sicuro appropriato.
- Gli ID RP e le origini attendibili sono configurati esplicitamente.
- Le sfide sono casuali crittograficamente, a breve termine e monouso.
- La registrazione richiede l'autorizzazione account appropriata.
- La verifica lato server segue la specifica WebAuthn.
- Le chiavi pubbliche e gli identificatori del credential sono memorizzati in modo sicuro.
- L'accesso stabilisce una sessione solo dopo una verifica riuscita.
- I requisiti di verifica utente sono applicati sul server.
- La rimozione del credential e il recupero account sono protetti.
- Sono supportati più credential per account dove appropriato.
- I fallimenti di autenticazione e le modifiche sensibili all'account sono monitorati.
- Vengono testati scenari mobili, desktop, inter-dispositivi e chiavi hardware.
Questi controlli sono più importanti del fatto che il frontend possa mostrare un'interfaccia di login biometrico accattivante.
Conclusione: le chiavi di accesso sono un'architettura di autenticazione, non solo una funzionalità del browser
WebAuthn rende l'autenticazione a chiave pubblica accessibile alle applicazioni web comuni.
Le API moderne del browser hanno rimosso gran parte del lavoro di serializzazione che precedentemente rendeva l'integrazione delle chiavi di accesso ingombrante.
Ma il browser è solo una parte del sistema.
Il vero lavoro di implementazione risiede nella gestione delle sfide, nella verifica lato server, nella memorizzazione dei credential, nella configurazione del dominio, nel recupero account e in itinerari utente sicuri.
Per gli sviluppatori che costruiscono applicazioni moderne in PHP, JavaScript, Python o altri ambienti backend, le chiavi di accesso sono sempre più valide come alternativa pratica alle password tradizionali.
Il miglior punto di partenza non è sostituire un intero sistema di autenticazione in un'unica notte.
È implementare un flusso completo di registrazione e accesso correttamente verificato, quindi costruire una strategia di migrazione sicura intorno ad esso.