Funzionalità del client WebAuthn

Passkeys Cheat Sheet — dev-focused WebAuthn reference. Trusted by Ally, Stanford CS & more.

Get Cheat Sheet

WebAuthn è il moderno standard alla base delle passkey. Invece di affidarsi alle password tradizionali, sfrutta la crittografia a chiave pubblica, permettendo agli utenti di autenticarsi con le passkey, che possono includere dati biometrici (come le impronte digitali o il riconoscimento facciale) o chiavi di sicurezza fisiche. Questo cambiamento non solo rafforza la sicurezza, ma migliora anche l'esperienza utente eliminando la necessità di gestire le password.

Lo standard WebAuthn Level 3 introduce nuove funzionalità del client (che possono essere recuperate tramite l'API del browser getClientCapabilities()), progettate per offrire a sviluppatori e piattaforme maggiore controllo e flessibilità nell'implementazione delle passkey. Questi aggiornamenti semplificano il processo di integrazione delle passkey tra dispositivi, browser e piattaforme, garantendo un'esperienza più fluida e uniforme per l'utente.

In questo articolo risponderemo alle seguenti domande:

1. Cosa sono le funzionalità del client WebAuthn?
2. Quali funzionalità del client WebAuthn esistono?
3. Come migliorano le implementazioni delle passkey?
4. Perché queste funzionalità sono importanti per sviluppatori e product manager?

Alla fine, avrete le idee chiare su come queste caratteristiche possano aiutarvi a creare flussi di autenticazione sicuri, senza interruzioni e in linea con le aspettative degli utenti di oggi.

Le funzionalità del client WebAuthn (o client capabilities) sono un insieme di caratteristiche che permettono a browser e piattaforme di comunicare quali funzioni WebAuthn supportano. In parole povere, funzionano come una "lista di controllo" che fa sapere ai siti web quali metodi e impostazioni di autenticazione sono disponibili sul dispositivo dell'utente. Questo consente agli sviluppatori di personalizzare i flussi di accesso in base alle capacità del client, garantendo un'esperienza più sicura e senza intoppi.

Per esempio, se un browser segnala di supportare l'autenticazione biometrica (come il Touch ID), gli sviluppatori possono progettare il flusso di login offrendo all'utente l'opzione di accedere con l'impronta digitale. Al contrario, se il browser non supporta certe funzionalità, si possono fornire soluzioni alternative, come una password o un OTP via SMS. Nella pratica, percorsi non supportati o interrotti possono comunque tradursi in errori generici del browser, quindi i team dovrebbero mappare questi risultati a una classificazione esplicita degli errori WebAuthn.

Lo standard WebAuthn Level 3 introduce diverse nuove capacità del client che rendono le implementazioni delle passkey più versatili e intuitive. Il primo supporto alla chiamata API getClientCapabilities() è stato introdotto in Safari 17.4.

Per rilevare il supporto nel browser, può essere utile il seguente snippet:

// Check if PublicKeyCredential is supported in the current browser
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential is not supported in this browser.");
}
 
// Check if getClientCapabilities method exists on PublicKeyCredential
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Error getting client capabilities:", error);
    }
} else {
    console.log("getClientCapabilities is not supported in this browser");
}

getClientCapabilities() permette a siti web e app di interrogare il client (es. browser o dispositivo) per determinare quali funzioni WebAuthn sono supportate. Conoscendo le capacità del client, gli sviluppatori possono ottimizzare i flussi di autenticazione per sfruttare le caratteristiche disponibili, come l'autenticazione biometrica, e fornire metodi alternativi se alcune capacità mancano all'appello.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Ecco uno sguardo più da vicino alle funzionalità del client WebAuthn e al loro impatto sull'integrazione delle passkey:

conditionalCreate abilita la creazione automatica di passkey in base a specifiche condizioni. Un'applicazione potrebbe usare questa funzionalità per creare automaticamente una passkey durante la compilazione automatica della password se il password manager lo supporta. Questa funzione aiuta a incrementare l'adozione delle passkey e il loro successivo utilizzo, accompagnando automaticamente gli utenti nella transizione dalle password alle passkey.

Simile a conditionalCreate, conditionalGet innesca automaticamente i login con passkey. Questo è utile negli scenari in cui si vuole offrire la migliore UX possibile, rendendo l'accesso non solo senza password, ma anche senza username (l'utente clicca semplicemente sulla passkey selezionata in una finestra modale / dropdown e si autentica). Usando questa capacità, gli sviluppatori assicurano che l'autenticazione con passkey avvenga solo quando appropriato, riducendo i prompt non necessari e migliorando l'esperienza complessiva.

hybridTransport assicura che le passkey possano essere utilizzate su dispositivi diversi, abilitando un'autenticazione cross-device fluida (tramite codici QR e Bluetooth). Per esempio, un utente potrebbe usare una passkey memorizzata sul proprio smartphone per accedere a un servizio sul computer desktop. Questa capacità permette agli utenti di autenticarsi in modo sicuro senza dover trasferire le passkey manualmente o fare affidamento sui classici metodi di login per ogni dispositivo, favorendo un'esperienza di autenticazione unificata.

I Platform Authenticator, come Windows Hello, Face ID o Touch ID, sono integrati direttamente nei dispositivi e offrono un'esperienza passkey più veloce, fluida e sicura, consentendo agli utenti di autenticarsi con dati biometrici o altri metodi nativi del dispositivo (es. un PIN).

Become part of our Passkeys Community for updates & support.

Join

userVerifyingPlatformAuthenticator assicura che l'autenticazione con passkey coinvolga la User Verification, come la scansione attiva dell'impronta digitale o il riconoscimento facciale, offrendo così un livello aggiuntivo di sicurezza.

La funzionalità relatedOrigins consente un'autenticazione trasparente tra domini diversi di proprietà della stessa organizzazione (es. amazon.com e amazon.de). Per esempio, se un'azienda gestisce più domini o ha sottodomini diversi, gli utenti possono accedere una sola volta e utilizzare tutte le proprietà senza doversi riautenticare su ciascuna. Questa funzione semplifica notevolmente l'esperienza utente, riducendo gli attriti, ed è particolarmente utile per le aziende che operano in ambienti internazionali o con piattaforme multi-servizio.

Il metodo signalAllAcceptedCredentials(options) fornisce l'elenco completo degli ID delle credenziali WebAuthn per un determinato utente. Le WebAuthn Relying Party dovrebbero usare questo metodo al posto di signalUnknownCredential() quando l'utente è autenticato, poiché in questo caso non c'è rischio di fughe di dati (privacy leak). Questo metodo offre una panoramica completa delle credenziali a chiave pubblica di un utente, includendo eventuali modifiche recenti che potrebbero non essere state aggiornate sugli Authenticator attualmente connessi.

Facciamo un esempio. Un utente (userId: A) possiede 2 passkey i cui Credential ID, codificati in Base64URL, sono X e Y. Poi, l'utente elimina la passkey X dalle impostazioni dell'account del servizio web (example.com), cancellando così la chiave pubblica. Ora, eseguiamo questo frammento di codice:

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle, Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

Se l'Authenticator è disponibile al momento dell'esecuzione del codice, eliminerà o nasconderà la passkey X dalle future cerimonie di autenticazione. Tuttavia, dato che l'Authenticator potrebbe non essere collegato in quel momento, si consiglia alle Relying Party di eseguire periodicamente questo codice, per esempio a ogni login.

Le passkey non presenti in allAcceptedCredentialIds verranno rimosse o nascoste, potenzialmente in modo irreversibile. Perciò è fondamentale che le Relying Party facciano attenzione a non rimuovere mai dall'elenco i Credential ID validi. Se un Credential ID valido viene rimosso accidentalmente, la Relying Party dovrebbe includerlo immediatamente in un'altra chiamata a signalAllAcceptedCredentials(options) il prima possibile per "scoprire" nuovamente la passkey. Se la passkey non è semplicemente nascosta ma rimossa, ci sarà ben poco da fare per risolvere il problema.

Experiment with passkey flows in the Passkeys Debugger.

Try for Free

Il metodo signalCurrentUserDetails(options) segnala il nome attuale dell'utente e il Display Name di WebAuthn. Quando viene chiamato signalCurrentUserDetails(options), il client segue una serie di passi predefiniti per eseguire l'azione.

Vediamo un esempio. Un utente con WebAuthn User ID A aggiorna il proprio nome nelle impostazioni dell'account di un sito web (example.com). A questo punto, la Relying Party può eseguire il seguente codice:

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // user ID, Base64URL.
    name: "Nuovo nome utente",
    displayName: "Nuovo display name",
});

L'Authenticator aggiornerà quindi i metadati della passkey salvata localmente. Il grande vantaggio è che nelle future richieste di Conditional UI / autocompilazione passkey, il menu a tendina o la selezione della Conditional UI mostrerà il nome aggiornato e il Display Name corretto.

Il metodo signalUnknownCredential(options) segnala che un WebAuthn Credential ID non è riconosciuto dalla Relying Party WebAuthn, ad esempio se la passkey è stata eliminata dall'utente. A differenza di signalAllAcceptedCredentials(options), questo metodo non richiede di fornire l'elenco completo dei Credential ID accettati o l'User Handle WebAuthn, prevenendo così potenziali fughe di informazioni se chiamato da fonti non autenticate.

Facciamo un esempio. Un utente cancella una passkey con Credential ID X nelle impostazioni dell'account di un sito (example.com), eliminando la chiave pubblica. Tuttavia, la chiave privata è ancora disponibile sul dispositivo dell'utente. Questo significa che nelle future richieste di login con Conditional UI / autocompilazione passkey (con un elenco allowCredentials vuoto), la passkey potrà ancora essere selezionata. Il tentativo di login fallirà, poiché la chiave pubblica è già stata cancellata, quindi la Relying Party dovrebbe eseguire:

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // credential ID the user just tried, Base64URL
});

L'Authenticator cancellerà o nasconderà la passkey con Credential ID X per le future operazioni di autenticazione.

Poiché lo standard WebAuthn Level 3 è ancora in fase di bozza, l'adozione di queste nuove capacità del client non è ancora del tutto diffusa. I vari browser stanno implementando gradualmente queste funzioni, ma il supporto varia. Di seguito, trovate una panoramica aggiornata della disponibilità nei principali browser menzionati:

È probabile che il ritmo di adozione acceleri man mano che lo standard Level 3 maturerà e più browser rilasceranno queste funzioni. Se volete scoprire quanti utenti possono già sfruttare getClientCapabilities(), potete consultare i dati reali su State of Passkeys. Tenete d'occhio le note di rilascio dei browser e la documentazione ufficiale per pianificare al meglio una compatibilità più ampia in futuro.

See how many people actually use passkeys.

View Adoption Data

Come sviluppatori, probabilmente vi starete chiedendo cosa comporti il rilevamento di queste nuove funzionalità del client WebAuthn e come sfruttarle nelle vostre app. Di seguito trovate alcuni consigli utili.

Tuttavia, ricordate che non tutti i browser supportano ancora la chiamata API getClientCapabilities() (a novembre 2024). C'è un polyfill disponibile qui, che può essere usato finché tutti i browser non si saranno adeguati.

Usate getClientCapabilities() nelle prime fasi del vostro codice per rilevare le funzioni supportate dal client all'inizio del caricamento della pagina o del flusso di autenticazione. Questo vi permetterà di personalizzare dinamicamente l'esperienza e di fornire le funzionalità passkey che funzionano meglio sul dispositivo/browser, ad esempio proponendo l'autenticazione tramite piattaforma quando supportata, oppure offrendo metodi alternativi (es. OTP via SMS o chiavi di sicurezza hardware) in caso contrario.

Se state aggiungendo le passkey a un sito web o a un'app che attualmente utilizza password, la funzione conditionalCreate può dare un vero e proprio slancio alla vostra adozione delle passkey. In background, durante un'autocompilazione della password con un gestore di credenziali compatibile (solo Apple Passwords a ottobre 2024), verrà automaticamente generata una passkey, che sarà la scelta preferita per i login futuri.

Per avere non solo un'elevata adozione di passkey, ma anche un alto utilizzo per l'accesso con passkey, verificate se il dispositivo o il browser supporta la Conditional UI / Passkey Autofill controllando la presenza di conditionalGet. In questo modo incoraggerete gli utenti a usare la passkey appena creata per accedere, poiché viene suggerita proattivamente dal sistema operativo / browser e richiede ancora meno sforzo rispetto all'inserimento manuale di una password.

Sfruttate hybridTransport per abilitare l'autenticazione cross-device (tramite codice QR e Bluetooth), consentendo agli utenti di accedere in modo trasparente dal loro smartphone anche se stanno utilizzando il vostro servizio su un desktop.

Le funzionalità del client WebAuthn rappresentano un significativo passo avanti nel colmare le attuali lacune delle passkey. In questo articolo abbiamo affrontato le domande chiave sulle client capabilities di WebAuthn:

1. Cosa sono le funzionalità del client WebAuthn? Abbiamo spiegato come queste caratteristiche permettono a browser e piattaforme di segnalare il proprio supporto per specifiche funzionalità, offrendo agli sviluppatori un maggiore controllo sui flussi di autenticazione.
2. Quali funzionalità del client WebAuthn esistono? Abbiamo offerto una panoramica delle nuove funzioni introdotte dallo standard Level 3, tra cui getClientCapabilities, conditionalCreate, hybridTransport e altre.
3. Come migliorano le implementazioni delle passkey? Abbiamo discusso di come queste capacità semplifichino l'integrazione, migliorino l'uso cross-device e aumentino la sicurezza.
4. Perché sono importanti per gli sviluppatori? Queste funzioni aiutano a creare esperienze di autenticazione sicure e fluide in linea con le moderne aspettative degli utenti, rendendo l'implementazione più semplice ed efficace.

Vi incoraggiamo a esplorare le nuove funzionalità del WebAuthn Level 3 e a rimanere aggiornati sulla loro adozione tra i vari browser. Se volete implementare le passkey e sfruttare appieno queste capacità avanzate, contattateci per avere supporto e una guida esperta.

Chiamate getClientCapabilities() all'inizio del caricamento della pagina o del flusso di autenticazione per rilevare dinamicamente le funzionalità supportate. Questo vi permette di offrire l'autenticazione su piattaforma quando supportata, o di ripiegare su alternative come SMS OTP o chiavi di sicurezza hardware quando non lo è.

signalAllAcceptedCredentials richiede l'elenco completo degli ID delle credenziali validi e il WebAuthn User Handle, quindi dovrebbe essere chiamato solo quando l'utente è autenticato per evitare fughe di informazioni. signalUnknownCredential segnala un singolo ID credenziale non riconosciuto senza richiedere l'intero elenco, rendendolo sicuro da richiamare in scenari non autenticati come, ad esempio, dopo un tentativo di accesso fallito.

La funzionalità relatedOrigins consente un'autenticazione trasparente tra domini diversi posseduti dalla stessa organizzazione, ad esempio amazon.com e amazon.de. Gli utenti possono accedere una sola volta e utilizzare tutte le proprietà senza doversi riautenticare su ciascun dominio, riducendo l'attrito in ambienti internazionali o multi-servizio.

A partire da novembre 2024, non tutti i browser supportano getClientCapabilities(), quindi potete usare il polyfill disponibile su github.com/MasterKale/webauthn-polyfills come soluzione temporanea. Si prevede che l'adozione accelererà man mano che lo standard WebAuthn Level 3 diventerà più maturo; al momento, Chrome 133, Edge 133, Firefox 135 e Safari 17.4 includono già il supporto.