API WebAuthn Signal: Aggiornare ed eliminare le passkey lato client

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

Ultimo aggiornamento: 4 novembre 2025

Una rapida panoramica del supporto per l'API WebAuthn Signal sulle diverse piattaforme:

⚠️ Problema noto: Safari 26+ ha un bug per cui la promise non si risolve correttamente (WebKit Bug #298951). Fix in attesa di merge.

L'ecosistema delle passkey è in continua evoluzione. Per facilitare il cambiamento, lo standard WebAuthn sottostante evolve rapidamente. Le nuove funzionalità spesso iniziano con un explainer tecnico su GitHub per poi trasformarsi in una pull request nello standard dopo essere state discusse a sufficienza. Recentemente, questa pull request è stata aggiunta alla bozza dello standard come API WebAuthn Signal. In questo articolo vedremo:

• Perché è necessaria l'API WebAuthn Signal: Quali casi d'uso supporta l'API WebAuthn Signal?
• Come funziona l'API WebAuthn Signal: Come funziona esattamente? Quali sono le raccomandazioni per i relying party?

Al momento della stesura di questo articolo, l'API WebAuthn Signal è abilitata per impostazione predefinita a partire da Chrome 132 ed era precedentemente nota come Reporting API, prima di essere rinominata per evitare conflitti con un'altra API con lo stesso nome.

L'API WebAuthn Signal affronta casi d'uso specifici relativi alla gestione delle passkey lato client. In particolare, aiuta a mantenere le informazioni sincronizzate tra il relying party (RP) e gli authenticator che fanno parte dei sistemi operativi lato client. Esistono i seguenti casi d'uso importanti:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Quando viene creata una passkey, questa include diverse informazioni: user.id, user.name e user.displayName. La passkey stessa è identificata tramite un Credential ID univoco.

• user.id: è un identificatore univoco che rappresenta l'account a cui è collegata la passkey. Questo user.id è cruciale perché viene utilizzato per l'effettivo abbinamento della passkey all'account dell'utente.
• user.name e user.displayName: questi sono metadati utilizzati esclusivamente per scopi di visualizzazione nell'interfaccia utente.

L'illustrazione seguente mostra una struttura di database tipica e semplice che spiega quali informazioni verrebbero solitamente memorizzate in quale campo:

È importante capire che mentre user.name (spesso un indirizzo email) e user.displayName (un nome più amichevole e leggibile) aiutano l'utente a identificare il proprio account nella UI di selezione, la vera associazione tra una passkey e un account è mantenuta attraverso lo user.id e il Credential ID:

• Un account può avere più passkey, ma ogni passkey è identificata in modo univoco e abbinata all'account utilizzando lo user.id.
• Ogni passkey ha di per sé un Credential ID univoco generato dall'authenticator.

Un problema sorge quando lo user.name, che può essere un indirizzo email, cambia. Attualmente, non esiste un meccanismo per aggiornare questo cambiamento direttamente sull'authenticator lato client. Lo user.name può cambiare per vari motivi, ad esempio quando un utente aggiorna il proprio indirizzo email. Nonostante questo cambiamento nei metadati dell'account lato server, il vecchio user.name continuerà ad apparire nella UI di selezione delle credenziali, causando confusione agli utenti.

La soluzione alternativa per questo problema consiste nel creare una nuova passkey con lo user.name aggiornato e lo stesso user.id, per poi sovrascrivere la passkey esistente. Tuttavia, questo approccio è scomodo per diversi motivi:

1. Ridondanza: Un authenticator può memorizzare solo una passkey per user.id per uno specifico ID di relying party. Ciò significa che la vecchia passkey deve essere sostituita con una nuova per aggiornare i metadati, il che rappresenta un passaggio extra.
2. Esperienza Utente: Gli utenti non capiranno perché devono creare una nuova passkey. Questo è il motivo per cui questa soluzione non è ampiamente utilizzata.
3. Complessità: Gestire la creazione di passkey e la sostituzione solo per aggiornare i metadati è una complessità non necessaria.

Indirizzi email, numeri di telefono e altri identificatori possono cambiare regolarmente. Senza un metodo diretto per aggiornare user.name e user.displayName direttamente sull'authenticator, gli utenti potrebbero riscontrare un problema persistente in cui vedono e devono selezionare una passkey associata al loro vecchio indirizzo email. Questa situazione compromette l'esperienza fluida che le passkey mirano a fornire. L'API WebAuthn Signal mira a risolvere questo problema consentendo ai relying party di segnalare aggiornamenti ai metadati delle passkey senza richiedere la creazione di nuove. Prima di spiegare come implementare l'API Signal, esploreremo il secondo importante caso d'uso che essa affronta.

Become part of our Passkeys Community for updates & support.

Join

Un altro caso d'uso cruciale è l'eliminazione delle passkey sull'authenticator lato client. Nel tempo, gli utenti possono revocare le credenziali tramite l'elenco di gestione delle passkey o eliminare i propri account, e diventa necessario garantire che queste credenziali siano rimosse dall'authenticator lato client per impedire che appaiano in future UI di selezione delle credenziali (Conditional UI / passkey autofill).

La necessità di questa funzionalità sorge in diversi scenari:

1. Passkey eliminata tramite impostazioni account: Quando una credenziale non è più valida, ad esempio dopo che un utente l'ha esplicitamente eliminata tramite le impostazioni dell'account:

Dal punto di vista dell'utente, è difficile capire che un'eliminazione nelle impostazioni dell'account, in una finestra di dialogo come quella sopra, non porta alla rimozione della passkey su questo client.

2. Eliminazione dell'Account: Quando un utente elimina il proprio account, anche tutte le passkey associate dovrebbero essere rimosse.

3. Policy di Sicurezza: I relying party potrebbero avere policy di sicurezza che richiedono la revoca delle credenziali dopo periodi di inattività o a causa di problemi di sicurezza rilevati.

Senza un metodo diretto per eliminare le passkey lato client, queste credenziali obsolete o non valide continuano a intasare la UI di selezione, creando confusione. Gli utenti potrebbero vedere e tentare di utilizzare passkey non più valide, risultando in tentativi di autenticazione falliti e una pessima esperienza utente.

Guarda questo video su come eliminare le passkey lato server nella Console di Gestione Corbado Connect:

L'implementazione dell'API WebAuthn Signal comporta diversi passaggi e considerazioni per garantire che la funzionalità sia integrata correttamente e in modo sicuro. L'API Signal consente ai relying party (RP) di aggiornare o eliminare le passkey (credenziali) sull'authenticator lato client. Questa sezione delinea le considerazioni chiave e i passaggi per l'implementazione.

Quando si implementa l'API WebAuthn Signal, è fondamentale tenere a mente le seguenti considerazioni:

• Tutela della Privacy: L'API WebAuthn Signal è progettata per preservare la privacy dell'utente, essendo uno dei fondamenti di WebAuthn. Ciò significa che non viene fornito alcun feedback all'RP sul fatto che la modifica richiesta sia stata elaborata. L'API opera silenziosamente per prevenire qualsiasi potenziale fuga di informazioni sullo stato delle credenziali.

• Disponibilità dell'Authenticator: L'efficacia dell'API WebAuthn Signal dipende dalla disponibilità dell'authenticator. Ciò include sia la disponibilità fisica che il supporto software (es. compatibilità browser e sistema operativo). Il browser può eseguire azioni solo se l'authenticator è accessibile e supporta le operazioni necessarie senza bisogno di autenticazione biometrica.

• Restrizioni di Dominio: L'API garantisce che solo il relying party associato a uno specifico dominio possa richiedere modifiche alle credenziali relative a quel dominio. Questa è una misura di sicurezza per prevenire modifiche non autorizzate da parte di terzi.

• Credential ID come Chiave: Quando si fa riferimento alle passkey, il Credential ID è la chiave primaria utilizzata dall'API WebAuthn Signal. Questo ID identifica univocamente la passkey sull'authenticator lato client. L'API consente agli RP di modificare i metadati associati alle passkey o segnalare che determinate passkey non dovrebbero più essere accessibili, ma solo attraverso il Credential ID. Nel caso in cui un authenticator non conosca uno specifico Credential ID, lo ignorerà silenziosamente.

Queste considerazioni sono essenziali per comprendere gli aspetti più importanti del corretto funzionamento dell'API WebAuthn Signal.

L'API WebAuthn Signal fornisce un meccanismo semplificato per i relying party (RP) per aggiornare i metadati associati alle passkey sugli authenticator lato client. Questo è particolarmente importante per garantire che gli utenti vedano informazioni accurate e aggiornate nella UI di selezione delle credenziali senza dover creare nuove passkey inutilmente. Ecco come l'API permette che ciò avvenga:

Aggiornamento dei Metadati con signalCurrentUserDetails(options)

Il metodo signalCurrentUserDetails(options) nell'API Signal è specificamente progettato per aggiornare i metadati delle passkey. Questo metodo consente agli RP di fornire i valori correnti per user.name e user.displayName.

Ecco come funziona il processo (vedi anche lo standard WebAuthn Level 3).

1. Struttura del Metodo: Il metodo signalCurrentUserDetails(options) include l'rp.id, lo user.id e i valori aggiornati per user.name e user.displayName.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // handle utente, base64url.
    name: "Nuovo nome utente",
    displayName: "Nuovo nome visualizzato",
});

2. Aggiornamento dei Metadati Locali: Cerca le credenziali disponibili localmente (sull'authenticator) che corrispondono a rpId e userId. Per tutte le credenziali corrispondenti, l'authenticator aggiornerà il name e il displayName della credenziale.

3. Tutela della Privacy: Il processo è progettato per preservare la privacy. L'API Signal non fornisce feedback all'RP sul fatto che gli aggiornamenti siano stati elaborati con successo, impedendo qualsiasi fuga di informazioni sullo stato delle credenziali.

4. Coerenza tra Dispositivi: Eseguendo regolarmente i metodi signalCurrentUserDetails(options), gli RP possono garantire che i metadati per le passkey rimangano coerenti su diversi dispositivi e piattaforme in cui l'utente può autenticarsi. Questo approccio riduce le possibilità che vengano visualizzate informazioni obsolete o errate nella UI di selezione delle credenziali.

Nello screenshot qui sopra, puoi vedere come Google Chrome segnala tale aggiornamento all'utente. L'API WebAuthn Signal è parte di Chrome e può essere testata con Google Password Manager su desktop.

L'API WebAuthn Signal fornisce meccanismi per i relying party (RP) per segnalare l'eliminazione delle passkey dagli authenticator lato client. Questo è essenziale per garantire che le credenziali obsolete o non valide non appaiano nella UI di selezione delle credenziali, mantenendo così un'esperienza utente snella e sicura. Esistono due metodi per eliminare le passkey localmente: signalUnknownCredential(options) e signalAllAcceptedCredentials(options). Il primo può essere utilizzato in situazioni in cui l'utente non è autenticato, mentre il secondo può essere utilizzato quando l'utente è autenticato. Pertanto, quest'ultimo dovrebbe essere preferito per motivi di privacy.

Ecco come funzionano i due metodi:

1. Struttura del Metodo: Il metodo signalUnknownCredential(options) include l'rpId (ID del relying party) e il credentialId (l'identificatore univoco della credenziale da eliminare).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // id credenziale che l'utente ha appena provato, base64url
});

2. Chiamata del Metodo: Gli RP chiamano questo metodo ogni volta che rilevano che una credenziale dovrebbe essere eliminata. Questo potrebbe avvenire immediatamente dopo un tentativo di autenticazione con una credenziale non valida, durante l'eliminazione dell'account o quando un utente revoca una credenziale tramite le impostazioni dell'account.

3. Gestione del Metodo: Quando viene chiamato il metodo signalUnknownCredential(options), l'authenticator lato client cerca di trovare le credenziali che corrispondono alla credenziale specificata da rpId e credentialID per l'omissione. A seconda delle capacità dell'authenticator, la credenziale viene rimossa o viene impiegata una procedura specifica dell'authenticator per nascondere la credenziale nelle future cerimonie di autenticazione.

1. Struttura del Metodo: Il metodo signalAllAcceptedCredentials(options) include l'rpId (ID del relying party), lo userId e un elenco di Credential ID validi allAcceptedCredentialIds (elenco di identificatori univoci delle credenziali che dovrebbero essere mantenute).

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // handle utente, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. Chiamata del Metodo: Gli RP chiamano questo metodo ogni volta che rilevano che una credenziale dovrebbe essere eliminata e segnalano un elenco di credenziali valide. Questo metodo dovrebbe essere preferito rispetto a signalUnknownCredential(options) per eliminare le credenziali.

3. Gestione del Metodo: Quando viene chiamato il metodo signalAllAcceptedCredentials(options), l'authenticator lato client abbina rpId e userId. L'authenticator cerca tutte le credenziali locali che corrispondono a rpId e userId. Il risultato viene confrontato con allAcceptedCredentialIds. Se ci sono credenziali locali che non sono presenti in allAcceptedCredentialIds, queste vengono rimosse localmente (o nascoste a seconda dell'authenticator).

4. Ripristino Credenziali: Se le credenziali sono state solo nascoste (a seconda dell'authenticator) e ora fanno parte di allAcceptedCredentialIds, queste saranno nuovamente presenti nelle future cerimonie di autenticazione.

5. Consigli Utili:

   • Quando si utilizza signalAllAcceptedCredentials(options) è importante notare che gli authenticator potrebbero non essere sempre connessi al momento dell'esecuzione di questo metodo. Di conseguenza, i relying party potrebbero considerare di eseguire signalAllAcceptedCredentials(options) periodicamente, ad esempio durante ogni accesso, per garantire che tutte le credenziali siano aggiornate.
   • I relying party devono essere cauti quando specificano l'elenco degli ID delle credenziali (allAcceptedCredentialIds). Le credenziali non incluse in questo elenco potrebbero essere nascoste o rimosse dall'authenticator, potenzialmente in modo irreversibile. Per evitare che credenziali valide vengano erroneamente omesse, è fondamentale assicurarsi che l'elenco sia completo. Se un ID di credenziale valido viene accidentalmente tralasciato, dovrebbe essere riaggiunto a signalAllAcceptedCredentials(options) il prima possibile per renderlo nuovamente visibile, supponendo che l'authenticator lo supporti.
   • Ove possibile, gli authenticator dovrebbero preferire nascondere temporaneamente le credenziali invece di rimuoverle permanentemente. Questo approccio può facilitare il recupero se un ID di credenziale valido è stato accidentalmente omesso dal relying party, consentendone il ripristino senza perdita permanente.

Nello screenshot qui sopra, puoi vedere come Google Chrome segnala le eliminazioni. L'API WebAuthn Signal può essere testata con Google Password Manager su desktop.

Per implementare efficacemente l'API WebAuthn Signal e garantire una sincronizzazione fluida dei metadati delle passkey tra gli authenticator lato client, considera le seguenti raccomandazioni:

• Tieni d'occhio gli aggiornamenti dell'API WebAuthn Signal e l'implementazione effettiva: Rimani informato sugli ultimi sviluppi e aggiornamenti relativi all'API Signal. L'API WebAuthn Signal è abilitata con Google Chrome 132, seguito da altri browser (ad esempio anche Safari ha annunciato il supporto). Controlla regolarmente i progressi e gli aggiornamenti sull'API WebAuthn Signal per assicurarti che la tua implementazione sia allineata con gli standard e le pratiche più recenti. Aggiorneremo questo post man mano che il panorama si evolverà.
• Inizia con l'approccio signalAllAcceptedCredentials(options) dopo ogni login riuscito: Questo approccio garantisce che tutti i metadati e gli ID delle credenziali vengano aggiornati in un unico metodo, semplificando il processo e mantenendo la coerenza tra dispositivi e piattaforme e allo stesso tempo disattivando le credenziali eliminate o obsolete.
• Messaggistica in tempo reale con signalUnknownCredential(options) per deployment su larga scala: Considera l'utilizzo della messaggistica in tempo reale con il metodo signalUnknownCredential(options) in deployment su larga scala o quando c'è necessità di aggiornamenti immediati. Questo metodo può migliorare l'efficienza e la precisione della gestione delle credenziali, garantendo che quelle non valide o obsolete vengano prontamente rimosse dalla UI di selezione.

Seguendo queste raccomandazioni, puoi implementare l'API WebAuthn Signal in modo efficace una volta supportata, garantendo che i metadati delle passkey rimangano aggiornati e coerenti su tutti gli authenticator lato client, fornendo così un'esperienza utente fluida e sicura per le passkey.

Lo standard WebAuthn è in continua evoluzione, arricchendosi di funzionalità su base mensile. L'introduzione dell'API WebAuthn Signal è un significativo passo avanti nella gestione dei metadati e delle eliminazioni delle passkey sugli authenticator lato client. Questa API affronta i casi d'uso cruciali di mantenere le informazioni sincronizzate tra relying party (RP) e authenticator, e garantire che le passkey non valide o obsolete vengano rimosse, migliorando così l'esperienza utente.

• Perché è necessaria l'API Signal? L'API Signal è essenziale per aggiornare i metadati delle passkey ed eliminare le passkey sugli authenticator lato client. Risolve i problemi relativi a informazioni obsolete di user.name e user.displayName, che possono causare confusione quando le credenziali vengono presentate nella UI di selezione. Inoltre, aiuta a mantenere un'interfaccia di selezione delle credenziali pulita e sicura rimuovendo le passkey revocate o eliminate.
• Come funziona l'API Signal? L'API Signal funziona consentendo agli RP di chiamare metodi sullo stato attuale delle credenziali, inclusi aggiornamenti ai metadati e segnalazione dell'eliminazione delle passkey. Queste segnalazioni vengono elaborate dall'authenticator lato client, garantendo che le informazioni presentate agli utenti siano accurate e aggiornate. L'API è progettata per preservare la privacy e opera senza fornire feedback all'RP sul successo degli aggiornamenti.

Man mano che lo standard WebAuthn evolve, beneficia dei diversi interessi dei suoi partecipanti, che spingono avanti diverse parti dello standard. Tenere d'occhio questi sviluppi è cruciale per rimanere aggiornati con gli ultimi miglioramenti e garantire che le implementazioni rimangano allineate con le ultime best practice e standard. La community WebAuthn continua a guidare l'innovazione, rendendo l'autenticazione più sicura e facile da usare.