Data di pubblicazione: 09 maggio 2025, Ultimo aggiornamento: 22 dicembre 2025
Le passkey offrono un'autenticazione efficace e resistente al phishing. Tuttavia, convincere gli utenti ad adottarle può creare attrito. Con la creazione automatica delle passkey, puoi creare passkey per i tuoi utenti al momento giusto, a condizione che abbiano già una password salvata per il tuo sito. La creazione condizionale, che consente la creazione automatica delle passkey, fa parte della specifica WebAuthn.
Come funziona
Per aiutare gli utenti ad adottare le passkey in modo più pratico, utilizza una funzionalità dell'API WebAuthn chiamata creazione condizionale. La creazione condizionale consente al tuo sito di richiedere una passkey per l'utente senza che quest'ultimo debba eseguire alcuna azione.
Questo flusso funziona quando vengono soddisfatte le seguenti condizioni:
- L'utente ha una password salvata nel gestore delle password predefinito.
- La password è stata utilizzata di recente. Idealmente, chiama la creazione condizionale immediatamente dopo un accesso riuscito basato su password.
Se entrambe le condizioni sono soddisfatte, puoi richiedere al gestore delle password di creare una passkey per l'utente chiamando la creazione condizionale. Dopo aver creato correttamente la passkey, l'utente riceve una notifica a seconda del gestore delle password.
Compatibilità
La creazione condizionale è supportata da Safari su macOS e da tutti i browser su iOS, nonché da Chrome su computer e Chrome su Android.
Questo supporto significa che funziona sui rispettivi provider di passkey predefiniti: Portachiavi iCloud (Password) su Safari su macOS e iOS e Gestore delle password di Google su Chrome su computer e Android.
Poiché iOS 18 o versioni successive e Android 14 o versioni successive supportano i provider di passkey di terze parti, indipendentemente dal browser utilizzato dall'utente, il supporto della creazione condizionale dipende dal provider di passkey. Se il provider di passkey selezionato non supporta la creazione condizionale, non verrà creata una nuova passkey.
Implementare la creazione condizionale
La creazione automatica delle passkey si basa su una funzionalità dell'API WebAuthn chiamata creazione condizionale. Si tratta di normali richieste create() di WebAuthn con il
mediation parametro impostato su "conditional", che funziona in modo simile al completamento automatico delle passkey per le richieste get().
Utilizza la creazione condizionale dopo che l'utente ha eseguito l'accesso con una password. La riuscita della creazione dipende dal gestore delle password e dal soddisfacimento di determinate condizioni. Queste condizioni possono variare a seconda del gestore delle password e possono cambiare nel tempo. Ad esempio, in Chrome con Gestore delle password di Google (GPM), l'utente deve aver eseguito l'accesso di recente utilizzando una password salvata per il sito.
Se il browser crea correttamente la passkey, restituisce una credenziale della chiave pubblica. Invia questa credenziale al backend per completare la registrazione e abilitare l'autenticazione futura.
Presentazione della funzionalità
Puoi determinare se la creazione condizionale è disponibile nel browser richiamando PublicKeyCredential.getClientCapabilities(). Verifica se un oggetto restituito contiene true per la proprietà conditionalCreate.
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
const capabilities = await PublicKeyCredential.getClientCapabilities();
if (capabilities.conditionalCreate) {
// Conditional create is available
}
}
Se getClientCapabilities non è disponibile, non è disponibile nemmeno la creazione condizionale.
Creare una passkey in modo condizionale
Per eseguire la creazione automatica di una passkey, richiama
navigator.credentials.create() ma con mediation: "conditional", come indicato di seguito.
const cred = await navigator.credentials.create({
publicKey: options,
// Request conditional creation
mediation: 'conditional'
});
Dovresti utilizzare la creazione automatica delle passkey immediatamente dopo che l'utente ha eseguito l'accesso per avere le maggiori probabilità di soddisfare i criteri del gestore delle password per la creazione automatica.
Puoi inviare la credenziale della chiave pubblica risultante al server per verificare e registrare la passkey. Sul server, assicurati che l'utente abbia eseguito l'accesso.
Avvertenze
La creazione condizionale di per sé non è difficile da implementare, ma ci sono diverse avvertenze quando si integra effettivamente questa funzionalità in un sistema esistente.
Ignorare la presenza e la verifica dell'utente sul server
La risposta di registrazione restituisce sia "Presenza dell'utente" che "Utente verificato" come
false, quindi il server deve ignorare questi flag durante la verifica delle credenziali.
Interrompere la chiamata WebAuthn in corso prima di eseguire la creazione automatica di una passkey
Quando l'RP si aspetta che l'utente acceda con una passkey o una password, la scelta migliore è eseguire un'operazione di recupero condizionale. Ciò potrebbe causare l'annullamento della chiamata di recupero condizionale prima di eseguire una creazione condizionale.
Per farlo, devi utilizzare AbortController e chiamare .abort().
// To abort a WebAuthn call, instantiate an AbortController.
const controller = new AbortController();
const cred = await navigator.credentials.get({
publicKey: options,
signal: controller.signal,
// Request conditional get
mediation: 'conditional'
});
// Abort the call
controller.abort();
Ignorare le eccezioni in modo normale
Quando viene eseguita la creazione condizionale di una passkey, ci sono alcuni casi in cui devi ignorare le eccezioni:
InvalidStateError: nel provider di passkey esiste già una passkey. Ricorda di specificareexcludeCredentials.NotAllowedError: la creazione di una passkey non soddisfa la condizione.AbortError: la chiamata WebAuthn viene interrotta.
La visualizzazione degli errori in questi casi potrebbe confondere l'utente, poiché il browser li gestisce in modo silenzioso: mostra una notifica solo in caso di successo e gli errori non attivano messaggi visibili.
Segnalare quando la registrazione di una passkey non riesce
Quando una passkey viene creata ma non è stata registrata sul server, l'utente riceverà un tentativo di accesso non riuscito. Ciò può accadere quando l'elenco delle passkey non è coerente tra il provider di passkey e il server.
Per evitare queste circostanze, utilizza l'API Signal per mantenerle coerenti.
L'upgrade dagli accessi senza password non è supportato
A questo punto, la creazione condizionale di una passkey è limitata all'inserimento di una password valida da parte dell'utente. Ciò significa che gli approcci di accesso senza password, come i link magici, la verifica del numero di telefono o la federazione di identità, non soddisfano la condizione.
Riepilogo
La creazione automatica delle passkey può accelerare l'adozione delle passkey sul tuo sito web, aiutando gli utenti del tuo sito web a passare dalle password a un metodo di autenticazione più sicuro.
Per saperne di più sulle passkey, inizia da Accesso senza password con le passkey.