La Mediazione Immediata di WebAuthn: una spiegazione completa

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

La transizione alle passkey sta creando un "paradosso delle passkey": alcuni utenti le hanno già, mentre molti usano ancora le password tradizionali. Questo porta a schermate di login affollate con più pulsanti: "Accedi con password", "Accedi con Google" e "Accedi con Passkey". Questa frammentazione crea attrito. Un utente potrebbe cliccare su "Accedi con Passkey" su un nuovo dispositivo solo per trovarsi di fronte a un confuso codice QR, perché la sua passkey non è disponibile localmente. Il problema principale è l'incapacità del sito web di conoscere il contesto dell'utente prima di avviare un flusso di autenticazione.

Una soluzione è adottare un approccio identifier-first e determinare il metodo di login migliore per l'utente. Un'altra potenziale soluzione è un unico pulsante "Accedi" intelligente che orchestra il flusso più fluido per ogni utente. Dovrebbe richiedere direttamente una passkey se ne è disponibile una sul dispositivo, o eseguire un fallback graduale ad altri metodi in caso contrario.

È stata annunciata una nuova funzionalità di WebAuthn che potrebbe rendere tutto questo possibile: la Mediazione Immediata (mediation: 'immediate'). Impostando questa proprietà in una chiamata API WebAuthn, gli sviluppatori possono creare un'esperienza di accesso unificata e intelligente che risolve il paradosso delle passkey. In questo articolo, analizziamo nel dettaglio mediation: 'immediate' dal punto di vista degli sviluppatori, esplorando cos'è, come funziona e come implementarla.

Per comprendere la Mediazione Immediata, è utile conoscere prima le altre opzioni. La mediazione dell'utente in WebAuthn è il modo in cui il browser gestisce l'interazione tra il tuo sito web (la Relying Party) e l'autenticatore dell'utente (ad es. Face ID, YubiKey).

Questo è il flusso WebAuthn classico ed esplicito. Quando una Relying Party chiama navigator.credentials.get() senza specificare una preferenza di mediation, il browser presenta sempre una finestra di dialogo modale. Questa finestra si sovrappone al contenuto della pagina, richiedendo l'attenzione immediata dell'utente e mettendo in pausa ogni altra interazione con il sito web.

• Caso d'uso: Ideale per pulsanti dedicati "Accedi con Passkey" in cui l'utente ha chiaramente espresso la sua intenzione.
• Limitazione: Se l'utente non ha una passkey sul dispositivo corrente, gli viene mostrato un flusso cross-device (ad es. codice QR), che può creare confusione e portare a un vicolo cieco.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

Introdotta per aiutare gli utenti nella transizione alle passkey, questa modalità è più discreta. Con mediation: 'conditional', la richiesta WebAuthn è collegata a un campo di input (ad es. nome utente) con l'attributo autocomplete="webauthn". Quando l'utente clicca sul campo, l'interfaccia di compilazione automatica del browser suggerisce le passkey disponibili.

• Caso d'uso: Ideale per migliorare progressivamente i moduli di login tradizionali, consentendo agli utenti di scoprire e utilizzare le passkey senza un pulsante separato.
• Limitazione: Dà una priorità così alta alla privacy che se l'utente non ha una passkey o non interagisce con il prompt, la Promise della chiamata API non si risolve mai. Il sito web non riceve alcun segnale, rendendo impossibile orchestrare un'interfaccia di fallback.

mediation: 'immediate' è la soluzione al problema del "pulsante di accesso unico". Fornisce a un sito web un modo affidabile per verificare la disponibilità di una passkey prima di mostrare qualsiasi interfaccia utente.

Invece di imporre all'utente di autenticarsi con una passkey tramite una finestra modale, la mediazione immediate chiede al browser: "C'è una passkey immediatamente disponibile per questo utente su questo dispositivo, proprio ora?"

Fondamentalmente, questa query controlla solo le credenziali disponibili localmente (ad es. autenticatori integrati nel dispositivo come Windows Hello o passkey sincronizzate tramite un gestore di password). È progettata per evitare di attivare il flusso cross-device con codice QR, che è un punto di attrito comune.

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

La potenza di questa funzionalità risiede nel suo risultato chiaro e binario. La Promise restituita da navigator.credentials.get() avrà successo o fallirà, dando allo sviluppatore un segnale inequivocabile.

• Percorso 1 (Successo): Esiste una credenziale. Se il browser trova una passkey disponibile localmente, scavalca l'interfaccia utente del sito web e presenta immediatamente la propria finestra di dialogo nativa, come un selettore di account. Se l'utente si autentica con successo, la Promise si risolve con l'oggetto PublicKeyCredential.
• Percorso 2 (Fallimento): Non esiste alcuna credenziale. Se il browser non trova credenziali disponibili localmente, non mostra alcuna interfaccia utente. Invece, la Promise di navigator.credentials.get() viene immediatamente respinta con una DOMException chiamata NotAllowedError.

L'errore NotAllowedError non è un bug, ma una vera e propria funzionalità. È un segnale affidabile e istantaneo che indica al sito web di procedere con un metodo di autenticazione di fallback. Questo permette agli sviluppatori di usare un semplice blocco try...catch: il blocco try tenta il flusso passkey fluido, mentre il blocco catch intercetta NotAllowedError per renderizzare un modulo di login tradizionale. Risolve elegantemente il problema del pulsante di accesso unico creando un singolo punto di ingresso che si adatta in modo intelligente al contesto dell'utente.

Scegliere la modalità di mediazione giusta è una decisione critica per l'esperienza utente. Questa tabella fornisce un confronto diretto.

Ecco una guida pratica, passo dopo passo, per implementare mediation: 'immediate'.

Poiché mediation: 'immediate' è una nuova funzionalità, un robusto rilevamento delle sue capacità è fondamentale.

// Il rilevamento della funzionalità è essenziale per il miglioramento progressivo.
let immediateMediationAvailable = false;
 
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
    try {
        const capabilities = await PublicKeyCredential.getClientCapabilities();
        // La capacità 'immediateGet' segnala il supporto del browser.
        immediateMediationAvailable = capabilities.immediateGet === true;
    } catch (e) {
        console.error("Error getting client capabilities:", e);
    }
}

Questa chiamata deve essere attivata da un gesto dell'utente, come il click su un pulsante.

// Questa funzione dovrebbe essere il gestore di eventi per il tuo pulsante "Accedi" principale.
async function handleSignInClick() {
    if (!immediateMediationAvailable) {
        // Esegui il fallback mostrando un modulo di login legacy se la funzione non è supportata.
        showLegacyLoginForm();
        return;
    }
 
    try {
        // Richiedi una challenge nuova e casuale dal tuo server per ogni tentativo.
        const challenge = await fetchChallengeFromServer();
 
        const publicKeyCredentialRequestOptions = {
            challenge: challenge, // La challenge fornita dal server come Uint8Array
            rpId: "example.com",
            // La lista allowCredentials DEVE essere vuota per la mediazione immediata
            // per proteggere la privacy dell'utente.
            allowCredentials: [],
        };
 
        const credential = await navigator.credentials.get({
            publicKey: publicKeyCredentialRequestOptions,
            // Questa è la chiave che abilita il flusso di mediazione immediata.
            mediation: "immediate",
        });
 
        // Se la Promise si risolve, invia la credenziale al tuo server per la verifica.
        await verifyCredentialOnServer(credential);
    } catch (error) {
        // Il blocco catch è una parte critica del flusso di controllo.
        handleAuthError(error);
    }
}

Il blocco catch è dove si realizza l'"intelligenza" del pulsante di accesso unico.

// La gestione di NotAllowedError è la chiave del meccanismo di fallback.
function handleAuthError(error) {
    // Controlla la proprietà 'name' della DOMException.
    if (error.name === "NotAllowedError") {
        // Questo è il segnale atteso per mostrare il modulo di login tradizionale.
        console.log("Nessuna passkey locale trovata. Mostro il modulo di login legacy.");
        showLegacyLoginForm();
    } else {
        // Questo gestisce altri potenziali errori, come l'utente che chiude il prompt.
        console.error("Errore di autenticazione:", error);
    }
}

Per un'esperienza ancora più fluida, puoi chiedere al browser di cercare sia le passkey che le password salvate nella stessa richiesta aggiungendo password: true.

// Combinare passkey e password per un'esperienza di accesso veramente unificata.
const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    password: true, // Chiedi al browser di includere le password salvate.
    mediation: "immediate",
});
 
// L'oggetto 'credential' restituito sarà un PublicKeyCredential
// o un PasswordCredential. La tua logica lato server deve gestire entrambi.

1. Richieste WebAuthn concorrenti: Una richiesta conditional in sospeso (spesso avviata al caricamento della pagina) può bloccare una nuova richiesta immediate. Considera l'uso di un AbortController per annullare eventuali richieste in sospeso prima di avviarne una nuova.
2. La restrizione di allowCredentials: L'array allowCredentials deve essere vuoto. Fornire ID di credenziali causerà il fallimento della chiamata. Questa è una misura di salvaguardia della privacy cruciale per impedire ai siti di verificare la presenza di utenti specifici e noti.
3. Il requisito del gesto dell'utente: La chiamata deve essere avviata da un gesto dell'utente (ad es. un evento 'click'). Chiamarla programmaticamente al caricamento della pagina sarà bloccata dai browser come misura di protezione della privacy.

mediation: 'immediate' è stata progettata con una chiara comprensione dei suoi compromessi in termini di sicurezza e privacy.

Il compromesso principale è una "fuga di un bit". Misurando il tempo di risoluzione della Promise, una Relying Party può dedurre un'informazione binaria: se la Promise è stata respinta istantaneamente (nessuna credenziale locale) o è stata ritardata (è stato mostrato un prompt dell'interfaccia utente perché è stata trovata una credenziale locale). Lo scopo di questa fuga di informazioni è consentire una migliore esperienza utente.

I progettisti hanno previsto il potenziale di abuso (ad es. tracciamento degli utenti) e hanno integrato diverse misure di salvaguardia non negoziabili:

1. Gesto dell'utente obbligatorio: La chiamata API deve essere attivata da un'azione dell'utente come un click. Ciò impedisce a un sito di sondare silenziosamente gli account al caricamento della pagina e rende impraticabile il fingerprinting su larga scala.
2. Disabilitato in modalità privata/incognito: La funzione non è consentita nelle modalità di navigazione privata per impedire di collegare l'attività di un utente tra sessioni normali e private.
3. Lista allowCredentials vietata: L'array allowCredentials deve essere vuoto. Ciò impedisce a un sito di utilizzare questa funzione per verificare se un utente specifico e noto sta visitando il sito.
4. Solo contesto di prima parte: La funzione non è consentita in contesti di terze parti (ad es. un iframe di un'altra origine) per prevenire il tracciamento cross-site.

Queste mitigazioni assicurano che le garanzie di sicurezza fondamentali di WebAuthn rimangano intatte. La cerimonia di autenticazione stessa non cambia e rimane resistente al phishing.

mediation: 'immediate' è una funzionalità avanzata della specifica WebAuthn Level 3, e il suo rilascio è in corso. A metà del 2025, una strategia di miglioramento progressivo è essenziale.

Mentre mediation: 'immediate' fornisce un ottimo strumento di basso livello per un pulsante di login più intelligente, è importante distinguerlo da una soluzione più ampia di "Passkey Intelligence", come quella offerta da Corbado. Entrambe mirano a risolvere il paradosso delle passkey e ad aumentarne l'adozione, ma lo fanno in modi diversi.

La Passkey Intelligence fa un passo in più raccogliendo e valutando i dati nel tempo. Ciò consente interventi sull'utente più sofisticati e tempestivi. Ad esempio, un backend di Passkey Intelligence può rilevare:

• Un utente che si autentica con successo con una password su un nuovo dispositivo compatibile con le passkey e invitarlo ad aggiungere una passkey per la volta successiva.
• Un utente che completa un login "ibrido" cross-device e suggerirgli immediatamente di registrare il nuovo dispositivo.
• Un utente che non riesce ad accedere su un nuovo dispositivo e offrire la creazione di una passkey come opzione di recupero o configurazione (ripristino automatico).

Questo approccio basato sui dati è indipendente dal supporto del browser per mediation: 'immediate', il che significa che può fornire un flusso di login più intelligente a tutti i tuoi utenti, fin da subito.

Il meglio di entrambi i mondi

In definitiva, questi due approcci non si escludono a vicenda; sono complementari. La soluzione ideale li combina:

1. Usa un servizio di Passkey Intelligence come cervello del tuo processo di login.
2. Il servizio può quindi utilizzare mediation: 'immediate' come uno dei suoi segnali sui browser supportati per eseguire un rapido controllo iniziale.
3. In base al risultato — o alla mancanza di supporto per la funzionalità — il servizio di intelligence può quindi utilizzare i suoi dati storici più ricchi per orchestrare il fallback perfetto, che si tratti di mostrare un campo password o di offrire una richiesta di creazione di passkey just-in-time.

Combinando la velocità nativa di mediation: 'immediate' con le informazioni approfondite di un backend di Passkey Intelligence, puoi fornire l'esperienza di login più fluida, adattiva ed efficace possibile, guidando delicatamente ogni utente verso un futuro senza password.

La Mediazione Immediata è un grande miglioramento per l'esperienza di login. Fornisce l'intelligenza necessaria per eliminare i punti comuni di attrito e confusione per gli utenti durante la transizione alle passkey.

• Riduce la confusione dell'utente: Abilitando un unico pulsante "Accedi", la mediazione immediate elimina il carico cognitivo per l'utente. Non deve più ricordare quale metodo di autenticazione ha impostato o scegliere da un elenco affollato di opzioni. Il processo di login diventa più semplice e intuitivo.
• Previene gli abbandoni del login con passkey: Un motivo comune per cui gli utenti abbandonano un login con passkey è l'apparizione inaspettata di un codice QR per un flusso cross-device. Poiché mediation: 'immediate' cerca solo credenziali locali, evita completamente questa situazione confusionaria. Invece di far abbandonare il flusso all'utente, l'applicazione riceve un segnale chiaro (NotAllowedError) per eseguire un fallback graduale a un altro metodo, risultando in un percorso più fluido.
• Crea un flusso fluido e intelligente: Il vantaggio principale è un'esperienza di login intelligente. L'applicazione può chiedere al browser se un login con passkey fluido è possibile prima di impegnarsi in un'interfaccia utente. Questo approccio "Chiedi, non imporre" assicura che gli utenti vedano solo i prompt pertinenti per loro. Rende il login intelligente e adattivo, rafforzando la comodità delle passkey e incoraggiandone l'uso continuato.

La Mediazione Immediata è una nuova funzionalità di WebAuthn che risolve l'esperienza di login frammentata del periodo di transizione alle passkey. Permette la creazione di un unico pulsante "Accedi" intelligente che si adatta al contesto dell'utente, eliminando confusione e attrito. Sebbene introduca un compromesso calcolato sulla privacy, include robuste misure di salvaguardia per mitigare i rischi senza compromettere la sicurezza fondamentale di WebAuthn.

Per gli sviluppatori, la strada da percorrere è il miglioramento progressivo. Costruite un'esperienza di base solida e aggiungete la mediazione immediate per i browser supportati. Adottare questa funzionalità è una mossa strategica per accelerare l'adozione delle passkey, migliorare la sicurezza, ridurre i costi operativi e aumentare la conversione.

L'implementazione di questi flussi di autenticazione avanzati può essere complessa. La piattaforma Enterprise Passkey di Corbado astrae questa complessità. La nostra infrastruttura gestisce l'orchestrazione ottimale del flusso, inclusa la mediazione condizionale e immediate, consentendo al tuo team di implementare con fiducia un'esperienza di autenticazione all'avanguardia e senza attriti.