Get your free and exclusive +90-page Banking Passkey Report
Back to Overview

Passkey per app native: Implementazione nativa vs. WebView

Questo articolo spiega come implementare le passkey nelle app native (iOS + Android). Scoprirai quale tipo di WebView è consigliato per l'autenticazione con passkey.

Vincent Delitz

Vincent

Created: June 20, 2025

Updated: December 11, 2025

native app passkeys

See the original blog version in English here.

WhitepaperEnterprise Icon

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

Get free Whitepaper

Implementazione delle passkey in app native: Guida di riferimento rapida#

ApproccioAdozioneCreare passkeyUsare passkeyGestire passkeyComplessità tecnicaSupporto OAuth
Implementazione nativa🟢🟢🟢Adozione elevata, UX migliore, biometria fluidaAutenticazione istantanea e silenziosaControllo nativo completoMedio-AltaRichiede un flusso separato
System WebView🟢🟢Buona adozione, esperienza simile al browserUX standard del browser, portachiavi condivisoGestione basata su browserBassaEccellente
Embedded WebView🟢Adozione più bassa, richiede più configurazioneSupporto nativo iOS e Android (WebKit 1.12.1+), nessuna Conditional UIControllo limitatoMedio-AltaN/A

Nota: System WebView e Embedded WebView sono spesso combinati, dove il System WebView gestisce il login (con condivisione automatica delle credenziali), e poi l'Embedded WebView renderizza la gestione delle passkey nelle impostazioni.

Fattori chiave per la decisione:

  • Login basato su OAuth? → System WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
  • Vuoi riutilizzare l'autenticazione web in un'app nativa? → Embedded WebView (WKWebView, WebView di Android con WebKit 1.12.1+)
  • Stai costruendo un'app native-first? → Implementazione nativa (Apple AuthenticationServices, Google Credential Manager)

1. Scelte per l'implementazione delle passkey in app native#

Le moderne piattaforme mobili offrono tre approcci distinti per integrare le passkey nella tua app nativa, ognuno con diversi compromessi in termini di esperienza utente, complessità tecnica e compatibilità con OAuth:

  1. Implementazione nativa: Costruisci flussi di passkey direttamente nella tua app usando le API della piattaforma (iOS AuthenticationServices, Android Credential Manager). Offre la migliore esperienza utente con un'autenticazione biometrica fluida, ma richiede uno sforzo di implementazione tecnica medio-alto.

  2. System WebView: Usa il componente browser della piattaforma (iOS ASWebAuthenticationSession / SFSafariViewController, Android Chrome Custom Tabs) per gestire l'autenticazione. Eccellente per i flussi di login basati su OAuth e condivide le credenziali con il browser di sistema.

  3. Embedded WebView: Incorpora una web view personalizzabile (iOS WKWebView, Android WebView) all'interno della tua app per riutilizzare l'autenticazione web con una struttura di app nativa. Offre un aspetto simile al nativo senza barre degli URL e pieno controllo sull'interfaccia della web view. Richiede una configurazione aggiuntiva, incluse autorizzazioni ed entitlements (iOS), e la configurazione della WebView con AndroidX WebKit 1.12.1+ (Android) per abilitare la funzionalità passkey.

La scelta giusta dipende dall'architettura di autenticazione della tua app, dall'uso di provider OAuth, dal controllo che desideri avere sull'interfaccia utente e dal fatto che tu stia costruendo un'app native-first o riutilizzando componenti web.

1.1 Implementazione nativa: La migliore esperienza utente#

Un'implementazione nativa delle passkey offre l'esperienza utente ottimale, con flussi di autenticazione integrati direttamente nell'interfaccia della tua app tramite API specifiche della piattaforma. Gli utenti beneficiano di dialoghi nativi della piattaforma, verifica biometrica fluida e tempi di login più rapidi possibili.

Quando scegliere l'implementazione nativa:

  • Se stai creando una nuova app nativa o stai rifattorizzando l'autenticazione con schermate native
  • Se vuoi la migliore esperienza utente possibile con un'autenticazione istantanea e silenziosa
  • Prompt automatici delle passkey all'avvio dell'app: Le implementazioni native possono usare preferImmediatelyAvailableCredentials per visualizzare automaticamente l'overlay delle passkey quando sono disponibili, offrendo l'esperienza di login più rapida senza richiedere l'inserimento di un identificatore
  • Se hai bisogno di pieno controllo sull'interfaccia e sul flusso di autenticazione
  • Se sei disposto a investire nell'implementazione specifica della piattaforma (iOS Swift, Android Kotlin)

Vantaggio chiave: preferImmediatelyAvailableCredentials()

Le implementazioni native possono sfruttare preferImmediatelyAvailableCredentials() per creare un overlay automatico delle passkey che appare immediatamente all'avvio dell'app quando sono disponibili. Questo flusso senza nome utente offre l'esperienza di login più rapida possibile: gli utenti vedono le loro passkey all'istante senza dover prima inserire un identificatore. Questa funzionalità è esclusiva delle implementazioni native e non è disponibile nelle varianti WebView.

Mentre le implementazioni WebView possono usare la Conditional UI (suggerimenti di passkey nei campi di input), l'overlay automatico nativo offre una UX superiore con tassi di utilizzo delle passkey più alti, poiché l'autenticazione inizia immediatamente all'avvio dell'app.

Panoramica dei requisiti tecnici:

L'integrazione nativa delle passkey richiede un trust crittografico tra la tua app e il dominio web. Senza di esso, il sistema operativo rifiuterà tutte le operazioni WebAuthn. Requisiti chiave:

  1. File di associazione app-dominio ospitati su /.well-known/
  2. Relying Party ID corretto che corrisponda al tuo dominio web
  3. Funzionalità specifiche della piattaforma (dettagliate nella Sezione 4)

Il vantaggio principale: le passkey create sul tuo sito web funzionano perfettamente nella tua app e viceversa.

1.1.1 Passkey native su iOS (Swift)#

L'implementazione nativa delle passkey su iOS coinvolge il framework AuthenticationServices di Apple, che fornisce un'API per le operazioni WebAuthn:

Componenti chiave:

  • ASAuthorizationController: Gestisce il flusso di autenticazione
  • ASAuthorizationPlatformPublicKeyCredentialProvider: Crea le richieste di passkey
  • Tre modalità di interfaccia distinte per gestire i login con passkey:
    • Login tramite campo di testo: Campo username tradizionale con login tramite passkey che inizia al clic sul pulsante
    • Overlay modale delle passkey: Dialogo del sistema operativo che elenca le passkey disponibili
    • Conditional UI: Suggerimenti di passkey nella barra QuickType sopra la tastiera

Consigli per lo sviluppo

  • Caching AASA: Apple mette in cache il file AASA in modo aggressivo (fino a 24 ore), il che può frustrare i test. Soluzione: Abilita la Developer Mode sul tuo dispositivo di test e aggiungi ?mode=developer all'URL del tuo AASA per forzare un recupero aggiornato
  • Test di performance: Esegui test con account iCloud contenenti centinaia di credenziali per osservare la latenza nel mondo reale. L'overlay di sistema potrebbe mostrare un leggero ritardo con molte passkey memorizzate

1.1.2 Passkey native su Android (Kotlin)#

L'implementazione nativa delle passkey su Android utilizza l'API Credential Manager (o la più vecchia API FIDO2 per la retrocompatibilità):

Componenti chiave:

  • CredentialManager: API centrale per tutte le operazioni sulle credenziali
  • CreatePublicKeyCredentialRequest: Per la registrazione di passkey
  • GetCredentialRequest: Per l'autenticazione con passkey
  • Due modalità di interfaccia principali:
    • Login tramite campo di testo: Campo username tradizionale con login tramite passkey che inizia al clic sul pulsante
    • Overlay modale delle passkey: Dialogo del sistema operativo che elenca le passkey disponibili

Nota: Android attualmente non dispone dei suggerimenti da tastiera della Conditional UI di iOS nelle app native (sebbene la Conditional UI funzioni nelle app web)

1.1.3 Sfide e soluzioni di implementazione#

L'implementazione nativa delle passkey presenta sfide importanti e lezioni apprese: l'integrazione a livello di sistema operativo può far emergere problemi su diversi dispositivi e versioni del sistema operativo.

  1. Ad esempio, il nostro team ha riscontrato problemi come il caching aggressivo di Apple del file apple-app-site-association (utilizzato per il collegamento delle credenziali tra app e web) e sottili differenze nell'interfaccia utente di alcuni prompt biometrici di produttori Android.
  2. Inoltre, bisogna considerare che in alcuni scenari aziendali, i dispositivi gestiti potrebbero avere la sincronizzazione delle passkey disabilitata per policy. In ambienti aziendali dove la sincronizzazione del Portachiavi iCloud o del Google Password Manager è disattivata, le passkey diventano legate al dispositivo e non si spostano, uno scenario importante da pianificare (ad es. assicurarsi che gli utenti possano ancora accedere se cambiano telefono).
  3. Inoltre, le app di gestione delle credenziali di terze parti possono influenzare il flusso. Ad esempio, se un utente ha un gestore di password come 1Password impostato come provider di credenziali attivo, questo intercetterà spesso la creazione e l'archiviazione delle passkey, avendo la priorità sul gestore di credenziali nativo della piattaforma.

1.1.4 Semplificare con SDK nativi#

Sebbene sia possibile implementare le passkey utilizzando le API grezze della piattaforma, gli SDK appositamente creati accelerano significativamente lo sviluppo gestendo la complessità di WebAuthn, i casi limite e fornendo telemetria integrata. Gli SDK offrono anche interfacce simulabili per i test unitari (fondamentale poiché non è possibile testare la biometria nei simulatori).

Raccomandazione: Per le implementazioni native, consigliamo di utilizzare gli SDK di Corbado (SDK Passkey per iOS Swift, SDK Passkey per Android Kotlin) che gestiscono i numerosi casi limite scoperti attraverso le implementazioni in produzione, forniscono telemetria aggiuntiva e strumenti di test.

Igor Gjorgjioski Testimonial

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

Corbado proved to be a trusted partner. Their hands-on, 24/7 support and on-site assistance enabled a seamless integration into VicRoads' complex systems, offering passkeys to 5 million users.

Passkey che milioni di persone adottano, velocemente. Inizia con la piattaforma di adozione di Corbado.

Inizia la prova gratuita

1.2 Implementazione System WebView: Autenticazione compatibile con OAuth#

Le System WebView utilizzano il componente browser nativo della piattaforma per gestire l'autenticazione all'interno della tua app. A differenza delle implementazioni completamente native, le System WebView mostrano contenuti web utilizzando il browser di sistema effettivo (Safari su iOS, Chrome su Android), mantenendo cookie condivisi, credenziali salvate e i familiari indicatori di sicurezza del browser.

Quando scegliere System WebView:

  • La tua app utilizza un login basato su OAuth: System WebView è l'approccio consigliato per i flussi OAuth2/OIDC, fornendo un'autenticazione sicura
  • Autenticazione web esistente che si desidera riutilizzare nelle app mobili
  • Necessità di supportare più metodi di autenticazione (password, social login, passkey) senza ricostruire nativamente
  • Volontà di mantenere un'unica base di codice per l'autenticazione su web e mobile

Vantaggi chiave:

  • Compatibilità OAuth: Creato appositamente per i flussi di autenticazione OAuth/OIDC
  • Indicatori di sicurezza: Gli utenti vedono l'URL effettivo e i certificati SSL, aumentando la fiducia
  • Basso sforzo di implementazione: Minimo codice nativo richiesto
  • UX coerente: Interfaccia browser familiare di cui gli utenti già si fidano

Componenti della piattaforma:

  • iOS: ASWebAuthenticationSession (consigliato per flussi di autenticazione) o SFSafariViewController (navigazione generale)
  • Android: Chrome Custom Tabs (CCT)

Grandi aziende come Google e GitHub hanno adottato questo approccio per aggiungere il login con passkey alle loro app mobili tramite overlay WebView su pagine di autenticazione web esistenti. Questo funziona bene quando una ricostruzione completa dell'autenticazione nativa non è immediatamente fattibile.

1.2.1 Opzioni System WebView per iOS#

iOS fornisce due componenti principali di System WebView for l'autenticazione:

ASWebAuthenticationSession (Consigliato per l'autenticazione):

  • Progettato specificamente per flussi OAuth/OIDC e di login sicuri
  • Chiede automaticamente all'utente il permesso di autenticarsi tramite l'app
  • Condivide cookie e credenziali con Safari
  • Supporta le passkey tramite il Portachiavi iCloud

SFSafariViewController (Navigazione generale):

  • Esperienza Safari completa all'interno dell'app
  • Mostra la barra degli URL e gli indicatori di sicurezza
  • Non condivide i cookie di Safari su iOS 11+; usare ASWebAuthenticationSession quando è richiesta la condivisione della sessione di Safari
  • Meno personalizzabile ma più affidabile per gli utenti
CaratteristicaASWebAuthenticationSessionSFSafariViewController
Caso d'uso principaleFlussi di autenticazioneNavigazione web generale
OAuth/OIDCEccellenteBuono
Supporto Passkey
PersonalizzazioneLimitataMinima

Se la tua app usa un login basato su OAuth, ASWebAuthenticationSession è la scelta consigliata poiché è progettata specificamente per scenari di autenticazione e offre il miglior equilibrio tra sicurezza ed esperienza utente.

1.2.2 System WebView per Android: Chrome Custom Tabs#

I Chrome Custom Tabs (CCT) offrono un'esperienza di autenticazione basata su Chrome all'interno della tua app:

Caratteristiche principali:

  • Condivide cookie e credenziali con il browser Chrome
  • Mostra l'URL e gli indicatori di sicurezza
  • Permette di personalizzare il colore della barra degli strumenti e il branding
  • Pre-riscaldamento per tempi di caricamento più rapidi

Integrazione OAuth: I Chrome Custom Tabs sono l'equivalente Android dell'ASWebAuthenticationSession di iOS, fornendo un eccellente supporto OAuth e mantenendo l'accesso alle passkey memorizzate.

Demo Icon

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

1.3 Implementazione Embedded WebView: Controllo della sessione con configurazione aggiuntiva#

Le Embedded WebView offrono pieno controllo sul rendering dei contenuti web all'interno della tua app, permettendo la manipolazione diretta di cookie, sessioni e navigazione senza la barra dell'URL. Tuttavia, questo controllo comporta requisiti tecnici aggiuntivi per abilitare la funzionalità passkey.

Quando scegliere Embedded WebView:

  • Esperienza simile al nativo: La tua app incorpora già l'autenticazione in una web view personalizzata per mantenere un aspetto nativo e vuoi mantenere questa esperienza utente coerente
  • Necessità di controllo su sessione/cookie: La tua app richiede la manipolazione diretta dei token di autenticazione e dello stato della sessione dopo il completamento dell'autenticazione OAuth
  • Flusso di autenticazione esistente in cui l'autenticazione System WebView restituisce un codice di autenticazione ma nessuna sessione in contesti incorporati
  • Necessità di mantenere lo stato autenticato su più schermate web incorporate
  • Solo autenticazione di prima parte: La tua app gestisce direttamente l'autenticazione, per implementazioni di passkey di terze parti vedi qui
  • AndroidX WebKit 1.12.1+ con rilevamento delle funzionalità in fase di esecuzione
  • Accettare la limitazione della Conditional UI per il login (non supportata in Embedded WebView), non rilevante per le impostazioni di gestione

Contesto importante:

Molte app utilizzano un approccio ibrido: System WebView gestisce l'autenticazione OAuth iniziale (dove le passkey funzionano senza problemi), per poi passare a Embedded WebView dopo l'autenticazione per gestire le passkey nelle impostazioni. Le sfide sorgono quando si tenta di utilizzare le passkey direttamente all'interno delle Embedded WebView.

Requisiti tecnici:

Le Embedded WebView richiedono una configurazione aggiuntiva rispetto alle System WebView:

  1. iOS: Entitlements per i domini associati, configurazione del file AASA
  2. Android: AndroidX WebKit 1.12.1+ con configurazione WebAuthn della WebView (richiesto il rilevamento delle funzionalità)
  3. Entrambi: File di associazione well-known configurati correttamente e Digital Asset Links

Componenti della piattaforma:

  • iOS: WKWebView
  • Android: android.webkit.WebView

Compromessi:

  • Complessità media: Richiede la configurazione della WebView (Android WebKit 1.12.1+) e l'impostazione degli entitlements (iOS)
  • Adozione delle passkey più bassa: Gli utenti potrebbero incontrare più attrito rispetto al nativo
  • Conditional UI non supportata: L'autocompletamento delle passkey nei campi di input non funziona in Embedded WebView su Android
  • Supporto limitato della piattaforma: Alcune funzionalità potrebbero non funzionare in modo coerente (es. creazione automatica di passkey)

2. Panoramica delle opzioni WebView#

Quando si implementano le passkey tramite WebView, è fondamentale comprendere la distinzione tra System WebView e Embedded WebView. I tre approcci sopra descritti (Implementazione nativa, System WebView e Embedded WebView) servono ciascuno a casi d'uso diversi.

Su iOS, hai diverse opzioni per visualizzare contenuti web in-app:

  • WKWebView è una WebView personalizzabile che fa parte del framework WebKit (introdotto in iOS 8). Ti dà molto controllo sull'aspetto e sul comportamento del contenuto web.
  • SFSafariViewController è un view controller fornito da Apple che funge da browser Safari leggero all'interno della tua app. Utilizza il motore di Safari. Su iOS 11+, ha un archivio di cookie separato e non condivide i cookie di Safari. Usa ASWebAuthenticationSession quando è richiesta la condivisione della sessione di Safari.
  • SFAuthenticationSession / ASWebAuthenticationSession sono sessioni di autenticazione web specializzate (disponibili da iOS 11/12) destinate specificamente a flussi di login OAuth/OpenID o altri flussi sicuri. Anche queste sfruttano Safari, ma sono focalizzate sui flussi di autenticazione e gestiscono automaticamente cose come i cookie condivisi e il Single Sign-On (SSO).

Su Android, le scelte principali sono:

  • Android WebView è il widget WebView standard (android.webkit.WebView), che è essenzialmente un mini browser che può essere incorporato nelle tue attività. È altamente personalizzabile ma viene eseguito nel processo della tua app.
  • Chrome Custom Tabs (CCT) è una funzione che apre una scheda basata su Chrome nel contesto della tua app. I Custom Tabs appaiono come parte della tua app ma sono alimentati dal browser Chrome (se installato) con funzioni come il pre-caricamento, i cookie condivisi e la familiare barra degli URL per la fiducia dell'utente.

Nelle sezioni seguenti, approfondiremo questi tipi di WebView per iOS e Android e discuteremo quale potrebbe essere più adatto per i flussi di autenticazione con passkey.

Substack Icon

Subscribe to our Passkeys Substack for the latest news.

Subscribe

3. WebView in iOS#

La piattaforma di Apple offre le tre opzioni di WebView elencate sopra. La tua scelta influenzerà la fluidità con cui le passkey possono essere utilizzate all'interno dell'app:

Per testare il diverso comportamento delle WebView in iOS, raccomandiamo l'app WebView - WKWebView and UIWebView rendering.

3.1 WKWebView#

WKWebView è un componente WebView versatile per iOS. Gli sviluppatori possono incorporare una WKWebView per renderizzare contenuti web con un alto grado di controllo sull'interfaccia e sul comportamento. WKWebView utilizza lo stesso motore di rendering di Safari, quindi è molto performante e supporta le moderne funzionalità web. In teoria, WKWebView può gestire WebAuthn (e quindi le passkey) se configurato correttamente, ma nota che alcune funzionalità avanzate del browser potrebbero essere limitate per sicurezza. Una cosa da tenere d'occhio è che WKWebView per impostazione predefinita non condivide cookie o dati del portachiavi con Safari Mobile. Gli utenti potrebbero dover effettuare nuovamente il login perché la loro sessione WebView è isolata dalla sessione di Safari. Inoltre, poiché il contenuto di WKWebView può essere completamente personalizzato dall'app, l'utente non vede una barra degli indirizzi o l'interfaccia di Safari – il che è ottimo per il branding, ma significa che l'utente ha meno indizi per verificare la legittimità della pagina (una preoccupazione per l'anti-phishing). Alcune app hanno persino abusato di WKWebView per iniettare script o alterare contenuti (ad es. è stato notato che TikTok inietta JS di tracciamento tramite il suo browser in-app), quindi bisogna fare attenzione a usare WKWebView in modo sicuro e affidabile per l'utente.

3.2 SFSafariViewController#

SFSafariViewController offre un'esperienza Safari in-app. Quando apri un URL con SFSafariViewController, è quasi come aprirlo nel browser Safari reale, tranne che l'utente rimane all'interno dell'interfaccia della tua app. Il vantaggio per le passkey è significativo: poiché è essenzialmente Safari, il Portachiavi iCloud dell'utente e le passkey salvate sono accessibili. Nota che i cookie non sono condivisi su iOS 11+. Ciò significa che se l'utente ha già una passkey per il tuo sito, Safari può trovarla e persino visualizzare l'autocompletamento della Conditional UI per un facile login. SFSafariViewController è meno personalizzabile (non puoi cambiarne molto la barra degli strumenti), ma gestisce automaticamente molte funzioni di sicurezza e privacy. La barra degli URL è mostrata, completa dell'icona del lucchetto per l'HTTPS, il che dà agli utenti la sicurezza di essere sul dominio corretto. In generale, SFSafariViewController è considerato più sicuro di una WKWebView grezza e più semplice da implementare (Apple lo fornisce come un componente pronto all'uso). Il compromesso principale è che sacrifichi un po' di controllo sull'aspetto e la sensazione. Per un flusso di autenticazione, questo è solitamente accettabile. La priorità qui è la sicurezza e la facilità di login, in cui SFSafariViewController eccelle utilizzando il contesto di Safari.

WKWebViewSFSafariViewController
Esperienza utente- Sensazione nativa: Gli utenti potrebbero sentire che il contenuto web è una parte nativa dell'app perché gli sviluppatori possono personalizzare l'aspetto per abbinarlo al design dell'app.
- Autocompletamento: È possibile l'autocompletamento con dati da Safari
- Fluida: Esperienza utente fluida utilizzando le impostazioni di Safari dell'utente, garantendo una navigazione web coerente tra app nativa e browser.
Esperienza sviluppatore- Altamente personalizzabile: Ampia personalizzazione e configurazione disponibili
- Flessibile: Molte API per interagire con i contenuti web
- Mediamente personalizzabile: Opzioni di personalizzazione limitate, specialmente rispetto a WKWebView,
- Semplice: Più semplice da implementare rispetto a WKWebView
Prestazioni- Piuttosto lenta: A seconda dell'implementazione e del contenuto web, le velocità di caricamento possono essere ottimizzate, ma potrebbero essere ancora più lente rispetto a SFSafariViewController a causa dell'elaborazione aggiuntiva di funzionalità e interazioni personalizzate.- Piuttosto veloce: Offre tipicamente prestazioni migliori poiché sfrutta il motore di Safari, ottimizzato per velocità ed efficienza, fornendo tempi di caricamento rapidi per le pagine web.
Fiducia e riconoscimento- Visualizzazione dell'URL non richiesta: WKWebView spesso non mostra l'URL, rendendo più difficile per gli utenti verificare la pagina web. Potenziale per app malevole di imitare questo comportamento e fare phishing di credenziali.- Esperienza simile al browser: Renderizza le pagine web usando Safari, fornendo un'esperienza "simile al browser". Gli utenti possono vedere l'URL e accedere alle funzioni di autocompletamento di Safari, infondendo potenzialmente più fiducia grazie all'interfaccia familiare.
Isolamento- Separati: Cookie e sessioni sono separati da Safari; gli utenti non saranno automaticamente loggati in una WKWebView.- Separati: Anche cookie e sessioni sono separati da Safari; gli utenti non saranno automaticamente loggati neanche in SFSafariViewController.
Vulnerabilità- Sicuro: Intrinsecamente sicuro grazie al sandboxing delle app di Apple, ma il comportamento e la sicurezza dipendono dall'implementazione dell'app. Potenziali vulnerabilità se non implementato correttamente.- Più sicuro: Beneficia delle funzionalità di sicurezza integrate di Safari, inclusi avvisi anti-phishing e contro siti web malevoli. Generalmente considerato più sicuro per la visualizzazione di contenuti web rispetto a WKWebView grazie a queste funzionalità e alla familiarità dell'utente con Safari.
Altro- Funzionalità non disponibili: Alcune funzionalità del browser (es., WebAuthn) potrebbero non essere completamente accessibili a causa di problemi di sicurezza e del fatto che WKWebView viene eseguito nel contesto dell'applicazione.
- Iniezione di JavaScript: Alcune app, come TikTok, iniettano JavaScript di tracciamento nella loro WKWebView in-app, o limitano il controllo dell'utente (es. Facebook)
- Problemi di privacy: Più feedback dalla community riguardo alla privacy
- Nessuna iniezione di JavaScript: Non consente l'esecuzione di JavaScript dall'app, migliorando sicurezza e privacy. Inoltre, non supporta avvisi o conferme JavaScript, influenzando potenzialmente l'esperienza utente su determinate pagine web.
- Modalità Lettura: Offre una modalità lettura per una versione pulita e facile da leggere degli articoli.

3.3 SFAuthenticationSession / ASWebAuthenticationSession#

SFAuthenticationSession / ASWebAuthenticationSession – Queste classi (la seconda è il nome più recente e compatibile con Swift) sono costruite specificamente per flussi di login come OAuth o OpenID Connect. Quando hai bisogno di autenticare un utente tramite una pagina web (magari verso un IdP esterno), queste sessioni sono la scelta consigliata su iOS. Sono molto simili a SFSafariViewController in quanto utilizzano il browser Safari e condividono cookie/dati con Safari. La differenza chiave è che SFAuthenticationSession chiederà sempre all'utente se l'app vuole autenticarsi usando una pagina web (per la consapevolezza dell'utente) e utilizzerà automaticamente la sessione Safari esistente dell'utente, se disponibile.

Il vantaggio è un'esperienza SSO fluida – se l'utente è già loggato al provider in Safari, questa sessione può usare quel cookie per evitare un altro login. Per le passkey, questo è importante perché significa che qualsiasi credenziale passkey memorizzata in Safari/iCloud Keychain può essere usata anche qui. La guida ufficiale di Apple è di usare ASWebAuthenticationSession per qualsiasi cosa che assomigli a un flusso di login. I pro sono una maggiore privacy (la tua app non vede mai le credenziali o i cookie, se ne occupa Safari) e il supporto SSO integrato. Il contro è che è limitato ai flussi di autenticazione (non lo useresti per renderizzare semplicemente contenuti web arbitrari nella tua app). In sintesi, se scegli un approccio WebView su iOS, ASWebAuthenticationSession è tipicamente la scelta migliore per implementare le passkey perché è sicuro, condivide lo stato con Safari ed è costruito appositamente per l'autenticazione.

StateOfPasskeys Icon

Want to find out how many people use passkeys?

View Adoption Data

4. WebView in Android#

Su Android, la decisione sulla WebView è tra la classica WebView e i Chrome Custom Tabs:

Per testare il diverso comportamento delle WebView in Android, raccomandiamo l'app WebView vs Chrome Custom Tabs.

4.1 Android WebView#

Android WebView (android.webkit.WebView) è un componente che ti permette di incorporare pagine web nel layout della tua attività. È simile a WKWebView in quanto ti dà il pieno controllo: puoi intercettare la navigazione, iniettare JavaScript, personalizzare l'interfaccia, ecc. Viene anche eseguito all'interno del processo della tua app. Usare una WebView per le passkey significa che la tua app carica la tua pagina di login web, e quella pagina può avviare una cerimonia di passkey WebAuthn. Le moderne Android WebView supportano WebAuthn (a condizione che l'implementazione della WebView del dispositivo sia aggiornata tramite Android System WebView o il componente Chrome). Una considerazione importante: per impostazione predefinita, una Android WebView non condivide cookie o credenziali memorizzate con il browser Chrome dell'utente. Quindi qualsiasi passkey creata o usata nella WebView potrebbe non essere nota a Chrome, e viceversa. Questo isolamento può essere buono per la sicurezza (la tua app non può leggere i cookie del browser), ma potrebbe costringere gli utenti a effettuare nuovamente il login se si sono già autenticati in Chrome. Un altro problema è la fiducia. Una WebView semplice non mostra l'URL o l'icona del lucchetto SSL, quindi gli utenti devono fidarsi completamente della tua app che non li stia ingannando con il phishing. Google ha persino proibito l'uso di WebView per gli accessi OAuth di Google a causa dei potenziali rischi di phishing. Dal punto di vista delle prestazioni, le WebView vanno bene, ma possono essere più lente o più intensive in termini di memoria rispetto all'utilizzo del browser predefinito dell'utente, specialmente se si caricano pagine pesanti.

4.2 Chrome Custom Tabs (CCT)#

Chrome Custom Tabs (CCT) sono un approccio ibrido. Permettono alla tua app di aprire una pagina renderizzata da Chrome che sembra parte della tua app. Puoi personalizzare il colore della barra degli strumenti, aggiungere un logo dell'app, ecc., ma il contenuto è renderizzato da Chrome in un processo separato. Per le passkey, i CCT hanno diversi vantaggi: condividono i cookie e le credenziali dell'utente con Chrome, il che significa che se l'utente ha una passkey salvata tramite Chrome (Google Password Manager), il Custom Tab può accedervi. L'utente vedrà anche l'URL effettivo e gli indicatori di sicurezza, il che costruisce fiducia. Le prestazioni sono spesso migliori – Chrome può essere "riscaldato" in background per un caricamento più rapido. E, cosa importante, la sicurezza è forte: poiché è essenzialmente l'app di Chrome, funzionalità come Google Safe Browsing proteggono la sessione, e la tua app non può iniettare script arbitrari nella pagina (prevenendo alcuni attacchi).

Lo svantaggio è che richiede che l'utente abbia Chrome (o un browser supportato) installato e aggiornato. La maggior parte degli utenti Android ce l'ha, ma su alcuni dispositivi in certe regioni, questo potrebbe essere un problema. Nel complesso, se scegli un approccio web incorporato su Android, i Chrome Custom Tabs sono raccomandati per i flussi di passkey, poiché offrono un buon equilibrio tra integrazione e sicurezza. In effetti, sono analoghi in molti modi a SFSafariViewController/ASWebAuthSession di iOS – sfruttando il browser predefinito per l'autenticazione.

(A parte: WKWebView vs SFSafariViewController di Apple e WebView vs CCT di Android hanno molti paralleli. Sia Safari VC che Chrome Tabs condividono lo stato del browser e offrono una sicurezza migliore, mentre WKWebView/Android WebView danno più controllo ma isolano il contenuto web. Per le passkey, la condivisione dello stato (cookie, archivi di credenziali) è solitamente desiderabile in modo che la passkey possa essere accessibile e creata senza problemi.)

CaratteristicaWebViewChrome Custom Tab
Esperienza utente- Flessibilità: Offre un ricco set di API per interagire con i contenuti web e gestire le interazioni dell'utente, inclusa la gestione di dialoghi JavaScript e richieste di autorizzazione.
- Coerenza: Gestire un'esperienza utente coerente, specialmente con contenuti web variegati, può essere una sfida.
- Funzionalità del browser: Condivide funzionalità come Risparmio dati e Autocompletamento sincronizzato tra i dispositivi.
- Pulsante Indietro: Consente agli utenti di tornare facilmente all'app con un pulsante Indietro integrato.
- Dipendenza: Dipende dall'app Chrome, che potrebbe non essere disponibile o aggiornata su tutti i dispositivi degli utenti.
- Reindirizzamento al browser: Alcune funzionalità potrebbero reindirizzare gli utenti all'app Chrome, potenzialmente interrompendo l'esperienza utente.
- Custom Tabs parziali: Solo una parte dello schermo può essere utilizzata per il Chrome Custom Tab mentre il resto mostra l'app nativa.
- Side-sheet: In modalità orizzontale e su dispositivi a schermo grande, il Chrome Custom Tab viene visualizzato solo su un lato dello schermo, mentre il resto dello schermo mostra l'app nativa.
Esperienza sviluppatore- Altamente personalizzabile: Offre ampie opzioni/esigenze di personalizzazione.
- Interattività: Fornisce numerose API per interagire con i contenuti web e gestire le interazioni dell'utente.
- Personalizzabile: Consente la personalizzazione del colore della barra degli strumenti, del pulsante di azione, della barra degli strumenti inferiore, delle voci di menu personalizzate e delle animazioni di entrata/uscita.
- Callback: Invia un callback all'applicazione in caso di navigazione esterna.
- Funzionalità di sicurezza: Fornisce funzionalità pronte all'uso, eliminando la necessità di gestire richieste, concessioni di autorizzazioni o archivi di cookie.
Prestazioni- Prestazioni mediocri: Potrebbe non offrire lo stesso livello di prestazioni dei Chrome Custom Tabs (CCT).- Pre-riscaldamento: Include il pre-riscaldamento del browser in background e il caricamento speculativo degli URL per migliorare il tempo di caricamento della pagina.
- Priorità: Impedisce che le app che avviano un Custom Tab vengano terminate durante il loro utilizzo elevando la loro importanza al livello "foreground".
Fiducia e riconoscimento- URL e SSL non visibili: L'URL e le informazioni SSL non sono intrinsecamente visibili in una WebView. A meno che lo sviluppatore dell'app non implementi queste funzionalità, gli utenti non sapranno se si trovano sul sito web corretto o su uno di phishing.- URL e SSL visibili: Utilizza il browser Chrome effettivo per renderizzare le pagine. Gli utenti possono vedere l'URL e il certificato SSL (che indica se la connessione è sicura). Questo può dare agli utenti la certezza di non trovarsi su un sito di phishing.
Isolamento- Esegue nel processo dell'app: Se un'app ha una vulnerabilità che consente l'esecuzione di codice malevolo, c'è il rischio che la WebView possa essere compromessa. Tuttavia, anche la WebView riceve aggiornamenti, ma il suo comportamento e la sua sicurezza possono dipendere maggiormente dall'app che la utilizza.
- Nessuna condivisione di cookie/sessioni: Non condivide cookie o sessioni con il browser principale del dispositivo, offrendo isolamento ma richiedendo potenzialmente agli utenti di effettuare nuovamente il login.
- Esegue nel processo di Chrome: Essendo parte di Chrome, i Custom Tabs vengono eseguiti nello stesso processo e hanno gli stessi aggiornamenti di sicurezza e le stesse funzionalità di Chrome.
- Jar di cookie e modello di autorizzazioni condivisi: Assicura che gli utenti non debbano effettuare nuovamente l'accesso ai siti o concedere nuovamente le autorizzazioni.
- Impostazioni e preferenze di Chrome: Utilizza le impostazioni e le preferenze di Chrome.
Vulnerabilità- Callback per rubare le credenziali: Le potenziali vulnerabilità includono che a volte è richiesto JavaScript, il che apre la porta ad altre app per eseguire codice malevolo, come la registrazione di callback che tentano di intercettare nomi utente e password.
- Phishing: Inoltre, un'app malevola potrebbe aprire un'altra pagina web che imita il flusso di Link in un tentativo di phishing.
- Google Safe Browsing: Utilizza il Safe Browsing di Google per proteggere sia l'utente che il dispositivo da siti pericolosi.
- Decorazione sicura del browser: Assicura che l'utente veda sempre l'URL esatto con cui sta interagendo e possa visualizzare le informazioni sul certificato del sito web, riducendo il rischio di phishing. Inoltre, i custom tabs non consentono l'iniezione di JavaScript.
Altro- Google ha vietato le WebView per il login degli utenti agli account Google

5. Requisiti di configurazione tecnica#

Indipendentemente dall'approccio di implementazione scelto, devono essere soddisfatti determinati requisiti tecnici per abilitare la funzionalità passkey. Questa sezione fornisce una guida completa sulla configurazione dei file di associazione well-known, degli entitlements di iOS e della configurazione della WebView di Android.

Nota sui dispositivi gestiti: Il comportamento delle passkey cambia significativamente sui dispositivi gestiti in cui le policy di Mobile Device Management (MDM) controllano l'archiviazione delle credenziali. Per testare le passkey su dispositivi gestiti, vedere Passkey su dispositivi iOS e Android gestiti.

5.1 File di associazione Well-Known (Nativo e Embedded)#

I flussi nativi e Embedded WebView richiedono file di associazione per stabilire un trust crittografico tra la tua app e il dominio web. System WebView (ASWebAuthenticationSession) e Chrome Custom Tabs non richiedono l'associazione app-sito.

5.1.1 iOS: File Apple-App-Site-Association (AASA)#

Il file AASA stabilisce la connessione tra la tua app iOS e il tuo dominio web, consentendo alle passkey di funzionare su entrambe le piattaforme.

Posizione del file: https://tuodominio.com/.well-known/apple-app-site-association

Requisiti di configurazione:

  • Ospitare su /.well-known/apple-app-site-association sul tuo dominio
  • Servire su HTTPS con un certificato SSL valido
  • Content-Type: application/json
  • Nessun reindirizzamento sul percorso .well-known
  • Includere il Team ID e il Bundle ID della tua app

Esempio di file AASA:

{ "webcredentials": { "apps": ["TEAMID123.com.example.app"] } }

Caching e test AASA:

Apple mette in cache aggressivamente i file AASA (fino a 24-48 ore) utilizzando una CDN, il che può frustrare lo sviluppo e il testing. Per bypassare la cache durante lo sviluppo:

  1. Abilita la modalità sviluppatore sul tuo dispositivo di test
  2. Aggiungi ?mode=developer al tuo dominio associato in Xcode
  3. Questo forza iOS a recuperare l'ultimo file AASA direttamente dal tuo server

⚠️ Importante: NON usare ?mode=developer nelle versioni di produzione. Questo parametro è solo per lo sviluppo; usarlo in produzione impedirà a iOS di rilevare correttamente il tuo file AASA, interrompendo la funzionalità delle passkey.

Validazione: Usa il validatore AASA di Apple per verificare la tua configurazione.

Android utilizza i Digital Asset Links per verificare la relazione tra la tua app e il tuo sito web.

Posizione del file: https://tuodominio.com/.well-known/assetlinks.json

Requisiti di configurazione:

  • Ospitare su /.well-known/assetlinks.json sul tuo dominio
  • Servire su HTTPS con un certificato valido
  • Content-Type: application/json
  • Includere l'impronta SHA256 della tua app (dal certificato di firma)

Esempio di file assetlinks.json:

[ { "relation": [ "delegate_permission/common.handle_all_urls", "delegate_permission/common.get_login_creds" ], "target": { "namespace": "android_app", "package_name": "com.example.app", "sha256_cert_fingerprints": [ "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99" ] } } ]

Validazione: Usa il generatore di Digital Asset Links di Google per creare e verificare la tua configurazione.

5.2 Configurazione degli Entitlements di iOS#

Le app iOS richiedono entitlements adeguati per accedere alla funzionalità passkey. I requisiti differiscono leggermente in base al tuo approccio di implementazione.

5.2.1 Comprendere Runner.entitlements / LaTuaApp.entitlements#

Il file degli entitlements (spesso chiamato Runner.entitlements nelle app Flutter o LaTuaApp.entitlements nei progetti iOS nativi) definisce autorizzazioni e capacità speciali concesse dal sistema di Apple. Per le passkey, questo file configura i Domini Associati.

Posizione del file: Tipicamente nel tuo progetto Xcode in ios/Runner/Runner.entitlements

5.2.2 Capacità Domini Associati#

L'implementazione nativa e la Embedded WebView richiedono la capacità Domini Associati per collegare la tua app al tuo dominio web. La System WebView (ASWebAuthenticationSession) non richiede questo poiché viene eseguita nel contesto di Safari.

Configurazione in Xcode:

  1. Apri il tuo progetto in Xcode
  2. Seleziona il target della tua app
  3. Vai alla scheda "Signing & Capabilities"
  4. Fai clic su "+ Capability" e aggiungi "Associated Domains"
  5. Aggiungi il tuo dominio con il prefisso webcredentials:

Esempio di configurazione:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>com.apple.developer.associated-domains</key> <array> <string>webcredentials:tuodominio.com</string> <string>webcredentials:sottodominio.tuodominio.com</string> </array> </dict> </plist>

5.2.3 Requisiti per approccio#

ApproccioDomini Associati RichiestiConfigurazione aggiuntiva
Implementazione nativaImplementazione dedicata
System WebViewNon richiestoLa configurazione web predefinita funziona
Embedded WebViewRichiede la configurazione di AndroidX WebKit 1.12.1+

Domini multipli: Se la tua app deve funzionare con più domini, potresti aver bisogno di Related Origin Requests (ROR).

5.3 Configurazione della WebView di Android (Solo Embedded WebView)#

Le Embedded WebView di Android hanno ottenuto il supporto nativo a WebAuthn con AndroidX WebKit 1.12, eliminando la necessità di codice bridge JavaScript personalizzato. La System WebView (Chrome Custom Tabs) non richiede alcuna configurazione: le credenziali funzionano automaticamente.

5.3.1 Supporto nativo WebAuthn (WebKit 1.12.1+, Raccomandato)#

Requisiti:

  • AndroidX WebKit 1.12.1 o più recente (1.14.0+ raccomandato)
  • Digital Asset Links configurati
  • APK della WebView con supporto WebAuthn (verificare tramite rilevamento delle funzionalità)
  • Nota: la libreria AndroidX Credentials NON è richiesta per WebAuthn in WebView, ma solo per implementazioni completamente native

Implementazione:

import androidx.webkit.WebSettingsCompat import androidx.webkit.WebViewFeature // Controlla se l'autenticazione web è supportata if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) { // Abilita l'autenticazione web WebSettingsCompat.setWebAuthenticationSupport( webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP ) // Abilita JavaScript webView.settings.javaScriptEnabled = true }

Punti chiave:

  • Nessun bridge JavaScript necessario: WebAuthn funziona nativamente in WebView
  • Rilevamento delle funzionalità richiesto: Controllare sempre WebViewFeature.WEB_AUTHENTICATION in fase di esecuzione
  • Conditional UI non supportata: mediation:"conditional" (autocompletamento passkey nei campi di input) non funziona in Embedded WebView
  • Strategia di fallback: Se la funzionalità non è disponibile, usare invece i Chrome Custom Tabs

Note sulla versione:

  • Usare WebKit 1.12.1 o più recente (1.12.0 aveva un problema di disponibilità in fase di esecuzione)
  • Il supporto della funzionalità dipende dalla versione dell'APK della WebView dell'utente: le versioni più vecchie dell'APK sul dispositivo non esporranno la funzionalità

5.3.2 Approccio legacy: Bridge JavaScript (Pre-WebKit 1.12.0)#

Prima di AndroidX WebKit 1.12.0, il supporto nativo a WebAuthn non esisteva in Embedded WebView. I team dovevano:

  1. Usare Chrome Custom Tabs o Auth Tab (raccomandato)
  2. Costruire un bridge JavaScript personalizzato

Se devi supportare versioni Android più vecchie o dispositivi senza APK della WebView aggiornati, consulta la guida all'integrazione di Credential Manager WebView di Android per l'approccio con codice bridge. Tuttavia, raccomandiamo vivamente di utilizzare l'approccio nativo con WebKit 1.12.1+ per le app moderne.

Raccomandazione: Utilizzare il supporto nativo WebAuthn con AndroidX WebKit 1.12.1+. Se non disponibile in fase di esecuzione, fare fallback su Chrome Custom Tabs che fornisce un eccellente supporto alle passkey con credenziali condivise.

5.4 Origini, Origini Correlate (ROR) e Verifica dei file Well-Known#

Quando si implementano le passkey in app native, è necessario stabilire una fiducia tra l'app e il/i dominio/i web. Questa sezione spiega come gestire domini singoli, domini multipli correlati (ROR) e come verificare che i file di associazione well-known siano configurati correttamente.

5.4.1 Configurazione a dominio singolo#

Per le app che utilizzano un singolo dominio (es. kayak.com), sono necessari:

5.4.2 Origini Correlate (ROR) per domini multipli#

Related Origins (ROR) è una funzionalità WebAuthn che consente a un singolo set di passkey di funzionare su più domini correlati (es. kayak.com, kayak.de, kayak.co.uk). ROR utilizza l'endpoint /.well-known/webauthn su ogni sito per definire le origini correlate, NON i file AASA o assetlinks.

Punti chiave:

  • Configurazione ROR: Ogni dominio ospita /.well-known/webauthn con l'elenco delle origini correlate
  • File di associazione dell'app (AASA/assetlinks): Utilizzati solo per mappare le app ai loro siti web corrispondenti
  • Embedded WebView iOS 18+: Supporta ROR se configurato correttamente
  • Entitlements Associated Domains: Includere tutti i domini con cui l'app deve autenticarsi

Esempio di configurazione:

Se la tua app funziona con kayak.com e kayak.de, entrambi i domini devono:

  • Ospitare i rispettivi file AASA con lo stesso Team ID e Bundle ID
  • Essere elencati negli entitlements Associated Domains della tua app
  • Avere file well-known configurati correttamente e accessibili

5.4.3 Verifica dei file Well-Known#

Prima di andare online, verifica che i tuoi file well-known siano configurati correttamente e accessibili. Apple e Google forniscono URL di test basati su CDN per controllare la disponibilità dei file:

DominioVerifica AASA AppleVerifica Digital Asset Links Google
kayak.comTesta file AASA
Controlla se la CDN di Apple può recuperare il tuo file
Testa assetlinks.json
Verifica se Google può accedere ai tuoi asset links
kayak.deTesta file AASA
Controlla se la CDN di Apple può recuperare il tuo file
Testa assetlinks.json
Verifica se Google può accedere ai tuoi asset links

Utilizzo di questi URL di test:

  • Clicca sui link per verificare se Apple/Google possono recuperare i tuoi file well-known
  • Il parametro ?nocache=1 di Apple forza un recupero aggiornato, bypassando la cache della CDN
  • Se i file non sono accessibili tramite questi URL, la funzionalità passkey non funzionerà nella tua app
  • Sostituisci kayak.com o kayak.de con il tuo/i tuo/i dominio/i negli schemi URL sopra

Attenzione nei test: Assicurati che tutti i domini abbiano file well-known configurati correttamente. Un file mancante o mal configurato su qualsiasi dominio può interrompere la funzionalità passkey per quel dominio.

Maggiori informazioni: WebAuthn Relying Party ID nelle App Native

6. Raccomandazioni per l'implementazione delle passkey in app native#

Scegliere il giusto approccio di implementazione dipende dall'architettura di autenticazione della tua app, dai requisiti OAuth e dalla necessità di controllo della sessione. Usa questo albero decisionale per determinare il percorso migliore.

6.1 Albero decisionale#

Inizia con queste domande chiave:

  1. La tua app utilizza un login basato su OAuth (OAuth2, OIDC, provider di social login)?

    • System WebView (Sezione 1.2)
      • iOS: Usa ASWebAuthenticationSession
      • Android: Usa Chrome Custom Tabs
      • Eccellente supporto OAuth con credenziali condivise
  2. Vuoi riutilizzare l'autenticazione web in un'interfaccia simile a quella nativa (senza barra URL, pieno controllo UI)?

    • Embedded WebView (Sezione 1.3) con configurazione
    • iOS: WKWebView + entitlements Associated Domains
    • Android: WebView + configurazione AndroidX WebKit 1.12.1+
    • Fornisce un aspetto simile al nativo riutilizzando componenti web
    • Nota: la Conditional UI non è supportata in Embedded WebView
    • No → Considera System WebView o Nativo
  3. Stai costruendo una nuova app nativa o hai schermate di login native?

    • Implementazione nativa (Sezione 1.1)
      • Migliore esperienza utente
      • Autenticazione istantanea e silenziosa
      • Richiede sviluppo specifico per piattaforma
  4. Hai un'autenticazione web esistente che vuoi riutilizzare?

    • System WebView per un'implementazione rapida
    • NoImplementazione nativa per una UX ottimale

6.2 Confronto degli approcci: Dimensioni di adozione#

Ecco come si comporta ogni approccio rispetto a dimensioni chiave:

ApproccioCreare passkeyUsare passkeyGestire passkeyComplessità tecnicaSupporto OAuthTempo di configurazione
Implementazione nativaAdozione elevata
Biometria fluida, UX migliore
Istantaneo, silenzioso
preferImmediatelyAvailableCredentials abilita overlay automatico all'avvio dell'app
Controllo nativo completo
Integrazione con le impostazioni dell'app
Medio-Alta
API specifiche della piattaforma
Richiede implementazione di un flusso OAuth separatoSettimane o mesi
System WebViewBuona adozione
Esperienza simile al browser, familiare
UX standard del browser
Conditional UI nei campi di input, portachiavi condiviso
Basata su browser
Gli utenti gestiscono tramite browser
Bassa
Codice nativo minimo
Eccellente
Costruito per OAuth
Giorni o settimane
Embedded WebViewAdozione più bassa
Richiede configurazione
Supporto nativo WebAuthn
WebKit 1.12.1+, no Conditional UI
Controllo limitato
Nessuna integrazione nativa
Medio-Alta
Configurazione WebView + autorizzazioni
Richiede configurazione1-2 settimane

Spiegazione delle dimensioni:

  • Creare Passkey: Con quale facilità gli utenti possono creare passkey con questo approccio
  • Usare Passkey: L'esperienza di autenticazione quando si usano passkey esistenti
  • Gestire Passkey: Come gli utenti visualizzano, modificano o eliminano le passkey
  • Complessità Tecnica: Sforzo di sviluppo e manutenzione continua
  • Supporto OAuth: Quanto bene l'approccio gestisce i flussi di autenticazione OAuth2/OIDC
  • Tempo di Configurazione: Tempistica tipica di implementazione

6.3 Raccomandazioni specifiche per scenario#

6.3.1 Scenario A: Autenticazione basata su OAuth (il più comune)#

Raccomandato: System WebView

Se la tua app si autentica tramite OAuth2, OIDC o provider di social login (Google, GitHub, Microsoft, ecc.), System WebView è la scelta ottimale:

  • iOS: ASWebAuthenticationSession è progettato per i flussi OAuth
  • Android: I Chrome Custom Tabs forniscono un'integrazione OAuth fluida
  • Vantaggi: Codice nativo minimo, condivisione automatica delle credenziali
  • Implementazione: Aggiungi WebAuthn alla tua pagina di autenticazione web, quindi caricala tramite System WebView

Esempio: App di viaggi come kayak.com e kayak.de usano OAuth per l'autenticazione. System WebView permette loro di mantenere la loro infrastruttura OAuth esistente aggiungendo il supporto alle passkey tramite le loro pagine di autenticazione web.

6.3.2 Scenario B: Login nativo con necessità di controllo della sessione#

Raccomandato: Approccio ibrido

Usa System WebView per l'autenticazione OAuth iniziale, poi Embedded WebView per le sessioni post-autenticazione:

  1. Autenticazione iniziale: System WebView gestisce il login OAuth + passkey
  2. Gestione della sessione: Passa a Embedded WebView per contenuti web autenticati dove hai bisogno di controllo su cookie/sessione
  3. Configurazione tecnica: Configura i requisiti sia per System che per Embedded WebView - per Android, assicurati che AndroidX WebKit 1.12.1+ sia incluso (vedi Sezione 5)

Quando usarlo: App che si autenticano tramite OAuth ma che poi devono visualizzare contenuti web autenticati dove è richiesta la manipolazione diretta della sessione.

6.3.3 Scenario C: Nuova app nativa o Native-First#

Raccomandato: Implementazione nativa

Stai costruendo da zero o hai schermate native? Scegli l'approccio completamente nativo:

  • iOS: Usa il framework AuthenticationServices
  • Android: Usa l'API Credential Manager
  • Vantaggi: Migliore UX, autenticazione istantanea, pieno controllo
  • Vantaggio unico: Usa preferImmediatelyAvailableCredentials per visualizzare un overlay automatico delle passkey all'avvio dell'app - esclusivo delle implementazioni native e che fornisce i più alti tassi di conversione
  • Raccomandazione SDK: Usa gli SDK di Corbado (iOS, Android) per accelerare lo sviluppo con la gestione di casi limite testati in produzione

Per nuove app: Raccomandiamo vivamente di costruire un login nativo fin dal primo giorno. Ti prepara per una UX ottimale ed evita future migrazioni da WebView a nativo.

6.3.4 Scenario D: App esistente con login basato sul web#

Raccomandato: Migrazione graduale

  • Fase 1: Passkey in System WebView - Aggiungi il supporto alle passkey al login web esistente, caricalo tramite System WebView (ASWebAuthenticationSession/Chrome Custom Tabs). Una vittoria rapida con codice nativo minimo.
  • Fase 2: Intercettazione nativa - Aggiungi un controllo nativo delle passkey prima di mostrare la WebView. Esempio: kayak.com tenta prima l'autenticazione nativa con passkey, e ricorre alla WebView se necessario. Fornisce un login biometrico veloce mantenendo la retrocompatibilità.
  • Fase 3: Completamente nativo - Migra gradualmente verso l'autenticazione nativa per gli utenti di passkey, mantenendo la WebView per i metodi legacy.

Questo approccio graduale permette miglioramenti incrementali senza interrompere gli utenti esistenti.

6.4 Requisiti tecnici chiave per approccio#

RequisitoNativoSystem WebViewEmbedded WebView
File well-known (AASA/assetlinks)RichiestoNon richiestoRichiesto
iOS Associated DomainsRichiestoNon richiestoRichiesto
Libreria Android WebKitNon applicabileNon richiestoRichiesto (1.12.1+)
Relying Party IDDeve corrispondere al dominioDeve corrispondere al dominioDeve corrispondere al dominio

Vedi la Sezione 5 per istruzioni dettagliate sulla configurazione.

6.5 Raccomandazioni per i test#

Testare le passkey in app native richiede un approccio strutturato e multi-livello. Segui la piramide dei test: test unitari (logica isolata), test di integrazione (cerimonia WebAuthn su simulatori/emulatori) e test di sistema (end-to-end su dispositivi fisici).

Categorie di test essenziali:

  • Percorsi principali: Registrazione, autenticazione, flussi cross-device, eliminazione di passkey
  • Copertura delle piattaforme: iOS (nativo), Android (nativo), browser web su varie versioni di OS
  • Associazione di dominio: Verifica che i file AASA (iOS) e i Digital Asset Links (Android) siano accessibili
  • Flussi di cancellazione: Testa la cancellazione dell'utente ai prompt del sistema operativo e alle schermate biometriche
  • Gestione degli errori: Fallimenti del backend, timeout di rete, discrepanze delle credenziali
  • Casi limite: Blocco schermo disabilitato, iCloud/Google Password Manager disabilitato
  • Flussi OAuth: Integrazione completa OAuth + passkey end-to-end
  • Dispositivi gestiti: Ambienti controllati da MDM (vedi test su dispositivi gestiti)
  • Gestori di terze parti: Compatibilità con 1Password, Bitwarden, Dashlane
  • Autenticazione cross-device: Flussi con codice QR e test del trasporto ibrido
  • Specifico per Embedded WebView: Se si utilizza Embedded WebView, verificare la configurazione di WebKit 1.12.1+ su Android
  • Monitoraggio in produzione: Dashboard per tassi di successo, fallimenti e latenza

Per una guida completa ai test che include strategie di automazione, problemi specifici della piattaforma e una checklist pre-lancio completa, consulta la nostra guida dedicata: Testare i flussi di passkey in app native iOS e Android.

6.6 Strategia di registrazione opportunistica#

Considera di suggerire agli utenti di creare passkey dopo un login tradizionale riuscito (password, OAuth). Questo approccio di conversione graduale:

  • Non interrompe i flussi di autenticazione esistenti
  • Permette una degradazione graduale se l'utente rifiuta
  • Aumenta l'adozione delle passkey nel tempo senza forzare cambiamenti
  • Funziona bene con tutti e tre gli approcci di implementazione

Esempio: Dopo il login OAuth tramite System WebView, mostra un prompt nativo: "Abilitare un login più veloce con Face ID?" Se accettato, crea la passkey tramite la pagina web caricata in System WebView.

7. Conclusione#

Decidere come implementare le passkey - tramite implementazione nativa, System WebView o Embedded WebView - è una scelta di progettazione cruciale che impatta sicurezza, esperienza utente e complessità di sviluppo. Non esiste una risposta valida per tutti.

Per le app basate su OAuth: System WebView (ASWebAuthenticationSession, Chrome Custom Tabs) è il punto di partenza raccomandato. Fornisce un eccellente supporto OAuth, uno sforzo di implementazione minimo e la condivisione automatica delle credenziali.

Per le app native-first: Passa al nativo il prima possibile. Un login nativo con passkey offre la UX più fluida con funzionalità esclusive come preferImmediatelyAvailableCredentials, che abilita un overlay automatico delle passkey all'avvio dell'app - qualcosa che le implementazioni WebView non possono fornire. Con iOS e Android che ora offrono un supporto di prim'ordine per le passkey, i successi nel mondo reale dimostrano un'alta adozione. Gli strumenti (inclusi SDK open-source e librerie di piattaforma) sono maturati per rendere l'integrazione nativa realizzabile in tempi ragionevoli. Sebbene sia necessario essere consapevoli delle policy di gestione dei dispositivi, della sincronizzazione cross-device e dei provider di terze parti, queste sfide possono essere gestite con un'attenta ingegnerizzazione e test. Il risultato è un login dell'app che delizia gli utenti con la sua facilità e velocità, migliorando significativamente la sicurezza.

Per i requisiti dei frame Embedded WebView: Embedded WebView è comunemente usato in due scenari reali. Primo, le app basate su OAuth usano spesso System WebView per il flusso di login iniziale, per poi passare a Embedded WebView per renderizzare le opzioni di gestione delle passkey nelle schermate delle impostazioni dove è necessario il controllo della sessione - sebbene alcune app semplifichino mantenendo System WebView per entrambi i flussi. Secondo, le app che avevano già incorporato il loro flusso di autenticazione in frame WebView prima di adottare le passkey continuano questo schema per coerenza. Embedded WebView con supporto nativo WebAuthn (AndroidX WebKit 1.12.1+) richiede configurazione e setup (permessi, entitlements, impostazioni della WebView) ma non necessita più di codice bridge JavaScript personalizzato. Nota che la Conditional UI non è supportata in Embedded WebView. Scegli questo approccio quando mantieni schemi di autenticazione incorporati esistenti o quando hai bisogno di controllo su sessione/cookie per le schermate post-autenticazione.

In definitiva, le passkey nelle app native rappresentano un enorme passo avanti sia nella comodità dell'utente che nella sicurezza. Che siano implementate tramite approccio nativo, System WebView o Embedded WebView, eliminano i rischi di phishing e l'onere della gestione delle password per i tuoi utenti. Implementazioni reali come l'integrazione delle passkey nell'app nativa di VicRoads dimostrano che gli approcci native-first offrono la più alta adozione e soddisfazione degli utenti quando eseguiti correttamente con funzionalità come gli overlay automatici delle passkey. Seguendo le migliori pratiche per un'autenticazione user-friendly e scegliendo l'approccio di implementazione che si adatta all'architettura della tua app - native-first per nuove app, System WebView per flussi OAuth, o Embedded WebView per schemi incorporati esistenti - puoi offrire login senza password e biometrici che realizzano veramente la visione delle passkey: un'autenticazione semplice, sicura e piacevole per tutti.

8. Checklist per la risoluzione dei problemi#

Se le passkey non funzionano nella tua app nativa, controlla questi problemi comuni per ogni approccio di implementazione:

Tutti gli approcci: Problemi con i file di associazione#

  • File serviti su HTTPS con certificato valido
  • Tipo MIME corretto: application/json
  • Nessun reindirizzamento sul percorso .well-known
  • iOS: Team ID e Bundle ID corrispondono esattamente nel file AASA
  • Android: L'impronta SHA256 corrisponde al tuo certificato di firma nel file assetlinks.json
  • L'ID della Relying Party corrisponde al tuo dominio (senza protocollo, senza porta)
  • Nessuna barra finale nell'ID RP
  • Origine WebAuthn: https://tuo-dominio.com (non app://)

Implementazione nativa#

  • iOS: Capacità Associated Domains abilitata in Xcode con webcredentials:tuodominio.com
  • Android: Digital Asset Links dichiarati in AndroidManifest.xml
  • L'utente ha il blocco schermo abilitato (biometrico o PIN)
  • Testa con il validatore AASA di Apple e lo strumento Digital Asset Links di Google
  • Verifica che il file Runner.entitlements contenga i domini associati corretti

System WebView#

  • iOS: Uso di ASWebAuthenticationSession (raccomandato) o SFSafariViewController
  • Android: Uso di Chrome Custom Tabs (non una semplice WebView)
  • iOS: Verifica che gli Associated Domains siano configurati se necessario
  • Testa che cookie/credenziali siano condivisi con il browser di sistema
  • Verifica che la pagina di autenticazione web abbia un'implementazione WebAuthn corretta

Embedded WebView#

  • iOS: Configurato con gli entitlements appropriati
  • iOS: Gli Associated Domains includono tutti i domini pertinenti
  • iOS: File AASA accessibile e formattato correttamente
  • iOS: Testa con ?mode=developer durante lo sviluppo (rimuovi per la produzione)
  • Android: AndroidX WebKit 1.12.1+ (o più recente) incluso nel progetto
  • Android: Controllo in fase di esecuzione della funzionalità WebViewFeature.WEB_AUTHENTICATION
  • Android: Chiamata a setWebAuthenticationSupport() con WEB_AUTHENTICATION_SUPPORT_FOR_APP
  • Android: JavaScript abilitato nelle impostazioni della WebView
  • Android: La versione dell'APK della WebView dell'utente supporta la funzionalità WebAuthn (usa il rilevamento delle funzionalità, non la versione del sistema operativo)
  • Conditional UI non utilizzata (non supportata in Embedded WebView)
  • Fallback su Chrome Custom Tabs se la funzionalità WebAuthn non è disponibile

Problemi con provider di terze parti#

  • Controlla se l'utente ha un provider di credenziali non predefinito attivo (1Password, Bitwarden, ecc.)
  • Verifica che il provider supporti le passkey (non tutti i gestori di password lo fanno)
  • Testa con il gestore di credenziali nativo della piattaforma (Portachiavi iCloud, Google Password Manager)

Messaggi di errore comuni#

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

  • Solitamente significa: Entitlements mancanti (iOS) o funzionalità WebView non disponibile/abilitata (Android Embedded WebView)
  • Controlla: Configurazione degli Associated Domains, accessibilità del file AASA, versione di WebKit, rilevamento delle funzionalità, chiamata a setWebAuthenticationSupport()

Nessun prompt di passkey appare

  • Potrebbe significare: AASA/assetlinks.json non caricato, tipo di WebView errato, file AASA in cache
  • Prova: Valida i file di associazione, usa ?mode=developer su iOS per i test, verifica il tipo di WebView

Per un debug dettagliato, consulta il nostro articolo sugli ID di Relying Party nelle app native.

9. Risorse#

SDK Nativi di Corbado:

Documentazione della Piattaforma:

Strumenti di Validazione:

Add passkeys to your app in <1 hour with our UI components, SDKs & guides.

Start Free Trial

Share this article


LinkedInTwitterFacebook