Passkey nelle app native: implementazione nativa vs. WebView

Nota: System e Embedded WebView sono spesso combinati: System WebView gestisce il login (con condivisione automatica delle credenziali), mentre Embedded WebView esegue il rendering della gestione delle passkey nelle impostazioni.

Fattori decisionali chiave:

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

Le moderne piattaforme mobili offrono tre approcci distinti per integrare le passkey nella tua app nativa, ciascuno con diversi compromessi per l'esperienza utente, la complessità tecnica e la compatibilità OAuth:

1. Implementazione nativa: Costruisci flussi per 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 un impegno tecnico di implementazione 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 uno scheletro di app nativa. Offre un aspetto nativo senza barra degli URL e pieno controllo sull'interfaccia utente della web view. Richiede configurazioni aggiuntive tra cui permessi ed entitlement (iOS) e configurazione di WebView con AndroidX WebKit 1.12.1+ (Android) per abilitare la funzionalità delle passkey.

La scelta giusta dipende dall'architettura di autenticazione della tua app, se usi provider OAuth, quanto controllo ti serve sull'interfaccia utente e se stai costruendo native-first o riutilizzando componenti web.

Whitepaper Passkey enterprise. Guide pratiche, pattern di distribuzione e KPI per programmi passkey.

Ottieni il whitepaper

Un'implementazione nativa delle passkey fornisce un'esperienza utente ottimale, con flussi di autenticazione costruiti direttamente nell'interfaccia utente della tua app utilizzando API specifiche della piattaforma. Gli utenti beneficiano di finestre di dialogo native della piattaforma, verifica biometrica fluida e tempi di login più veloci possibili.

Quando scegliere l'implementazione nativa:

• Creazione di una nuova app nativa o refactoring dell'autenticazione in schermate native
• Si desidera la migliore esperienza utente possibile con autenticazione istantanea e silenziosa
• Prompt automatici per le passkey all'avvio dell'app: Le implementazioni native possono usare preferImmediatelyAvailableCredentials per mostrare automaticamente l'overlay delle passkey quando le passkey sono disponibili, fornendo l'esperienza di login più veloce senza richiedere l'inserimento di identificatori
• Necessità di pieno controllo sull'interfaccia utente e sul flusso di autenticazione
• Disposizione a investire nell'implementazione specifica per piattaforma (iOS Swift, Android Kotlin)

Vantaggio chiave: preferImmediatelyAvailableCredentials()

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

Il diagramma di seguito illustra come l'autenticazione nativa offra un percorso utente più rapido rispetto all'approccio Conditional UI di WebView:

L'overlay automatico nativo fornisce una UX superiore con tassi di utilizzo delle passkey più elevati poiché l'autenticazione inizia immediatamente all'avvio dell'app, mentre le implementazioni WebView richiedono che gli utenti interagiscano prima con i campi di input.

Panoramica dei requisiti tecnici:

L'integrazione nativa delle passkey richiede una fiducia crittografica tra la tua app e il dominio web. Senza di essa, il sistema operativo rifiuterà tutte le operazioni WebAuthn. Requisiti chiave:

1. File di associazione App-Dominio ospitati in /.well-known/
2. Relying Party ID corretto corrispondente al tuo dominio web
3. Capacità specifiche della piattaforma (dettagliate nella Sezione 4)

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

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 per le passkey
• Tre distinte modalità UI per gestire i login con passkey:
  • Login con campo di testo: Tradizionale campo username con login tramite passkey che inizia all'invio del pulsante
  • Overlay modale delle passkey: Finestra di dialogo del sistema operativo che elenca le passkey disponibili
  • Conditional UI: Suggerimenti per le passkey nella barra QuickType sopra la tastiera

Suggerimenti per lo sviluppo

• Caching AASA: Apple memorizza 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 al tuo URL AASA per forzare recuperi aggiornati
• Test delle prestazioni: Testa 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 salvate

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

Componenti chiave:

• CredentialManager: API centrale per tutte le operazioni sulle credenziali
• CreatePublicKeyCredentialRequest: Per la registrazione delle passkey
• GetCredentialRequest: Per l'autenticazione con passkey
• Due modalità UI principali:
  • Login con campo di testo: Tradizionale campo username con login tramite passkey che inizia all'invio del pulsante
  • Overlay modale delle passkey: Finestra di dialogo del sistema operativo che elenca le passkey disponibili

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

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

1. Ad esempio, il nostro team ha riscontrato problemi come il caching aggressivo da parte di Apple del file apple-app-site-association (utilizzato per il collegamento delle credenziali tra app e web) e sottili differenze UI in alcuni prompt biometrici OEM Android.
2. Inoltre, considera che in alcuni scenari aziendali, i dispositivi gestiti potrebbero avere la sincronizzazione delle passkey disabilitata dai criteri. Negli ambienti aziendali in cui la sincronizzazione del Portachiavi di iCloud o di Google Password Manager è disattivata, le passkey diventano legate al dispositivo e non si sposteranno, uno scenario importante da pianificare (ad es. garantendo che gli utenti possano ancora accedere se ricevono un nuovo telefono).
3. Inoltre, le app di gestione credenziali di terze parti possono influenzare il flusso. Ad esempio, se un utente ha un password manager come 1Password impostato come provider di credenziali attivo, esso spesso intercetterà la creazione e la memorizzazione delle passkey, avendo la priorità sul gestore di credenziali nativo della piattaforma.

Mentre puoi implementare le passkey utilizzando API di piattaforma raw, SDK appositamente realizzati accelerano significativamente lo sviluppo gestendo la complessità di WebAuthn, i casi limite e fornendo telemetria integrata. Gli SDK offrono anche interfacce mockabili per gli unit test (cruciale poiché non puoi testare la biometria negli emulatori).

Raccomandazione: Per le implementazioni native, raccomandiamo l'uso degli SDK Corbado (iOS Swift Passkey SDK, Android Kotlin Passkey SDK) che gestiscono i numerosi casi limite scoperti tramite distribuzioni in produzione, forniscono telemetria aggiuntiva e strumenti di testing.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

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

Quando scegliere System WebView:

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

Vantaggi chiave:

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

Componenti di piattaforma:

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

Grandi aziende come Google e GitHub hanno adottato questo approccio per aggiungere il login tramite passkey alle loro app mobili tramite overlay WebView sulle pagine di autenticazione web esistenti. Questo funziona bene quando non sono immediatamente fattibili ricostruzioni di autenticazione completamente native.

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

ASWebAuthenticationSession (Consigliato per l'Autenticazione):

• Appositamente creato per i flussi di login sicuri e OAuth/OIDC
• Avvisa automaticamente l'utente che l'app vuole autenticarsi
• Condivide cookie e credenziali con Safari
• Supporta le passkey tramite il Portachiavi di iCloud

SFSafariViewController (Navigazione Generale):

• Esperienza Safari completa all'interno dell'app
• Mostra barra degli URL e indicatori di sicurezza
• Non condivide i cookie di Safari su iOS 11+; usa ASWebAuthenticationSession quando è richiesta la condivisione della sessione di Safari
• Meno personalizzabile ma più affidabile per gli utenti

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

Le Chrome Custom Tabs (CCT) forniscono un'esperienza di autenticazione potenziata da Chrome all'interno della tua app:

Funzionalità chiave:

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

Integrazione OAuth: Le Chrome Custom Tabs sono l'equivalente Android di iOS ASWebAuthenticationSession, fornendo un eccellente supporto OAuth pur mantenendo l'accesso alle passkey salvate.

Prova le passkey in una demo live.

Prova le passkey

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

Quando scegliere Embedded WebView:

• Esperienza simil-nativa: La tua app incorpora già l'autenticazione all'interno di una web view personalizzata per mantenere un aspetto nativo, e desideri mantenere questa esperienza utente coerente
• Necessità di controllo della sessione/cookie: La tua app richiede la manipolazione diretta dei token di autenticazione e dello stato della sessione al completamento dell'autenticazione OAuth
• Flusso di autenticazione esistente dove l'autenticazione System WebView restituisce un codice di autorizzazione ma nessuna sessione nei contesti incorporati
• Si deve 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 consulta qui
• AndroidX WebKit 1.12.1+ con rilevamento delle funzionalità a runtime
• 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 usano un approccio ibrido: System WebView gestisce l'autenticazione OAuth iniziale (dove le passkey funzionano perfettamente), poi passano a Embedded WebView per la fase post-autenticazione per gestire le passkey nelle impostazioni. Le sfide sorgono quando si cerca di usare le passkey direttamente all'interno delle Embedded WebView.

Requisiti tecnici:

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

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

Componenti di piattaforma:

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

Compromessi:

• Media complessità: Richiede la configurazione della WebView (Android WebKit 1.12.1+) e la configurazione degli entitlement (iOS)
• Minore adozione delle passkey: Gli utenti potrebbero incontrare più attriti rispetto a quella nativa
• Conditional UI non supportata: La compilazione automatica delle passkey nei campi di input non funziona in Android Embedded WebView
• Supporto limitato della piattaforma: Alcune funzionalità potrebbero non funzionare in modo coerente (ad es. creazione automatica delle passkey)

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

Su iOS, hai a disposizione più opzioni per mostrare contenuti web in-app:

• WKWebView è una WebView personalizzabile che fa parte del framework WebKit (introdotta in iOS 8). Ti dà molto controllo sull'aspetto e sul comportamento del contenuto web.
• SFSafariViewController è un view controller fornito da Apple che agisce come un browser Safari leggero all'interno della tua app. Usa il motore di Safari. Su iOS 11+, ha un archivio 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 a partire da iOS 11/12) destinate specificamente a flussi di login sicuri o OAuth/OpenID. Anche queste sfruttano Safari dietro le quinte, 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 activity. È altamente personalizzabile ma viene eseguito nel processo della tua app.
• Chrome Custom Tabs (CCT) è una funzionalità che apre una scheda potenziata da Chrome all'interno del contesto della tua app. Le Custom Tabs appaiono come parte della tua app ma sono alimentate dal browser Chrome (se installato) con funzionalità come pre-caricamento, cookie condivisi e la familiare barra degli URL per la fiducia dell'utente.

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

Iscriviti al nostro Substack sulle passkey per le ultime novità.

Iscriviti

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

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

WKWebView è un componente WebView versatile per iOS. Gli sviluppatori possono incorporare una WKWebView per eseguire il rendering di contenuti web con un alto grado di controllo sull'UI e sul comportamento. WKWebView usa 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 tieni presente che alcune funzionalità avanzate del browser potrebbero essere limitate per motivi di sicurezza. Una cosa a cui prestare attenzione è che WKWebView di default non condivide cookie o dati del portachiavi con Mobile Safari. Gli utenti potrebbero dover accedere di nuovo 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'UI di Safari - il che è ottimo per il branding, ma significa che l'utente ha meno segnali per verificare la legittimità della pagina (una preoccupazione per l'anti-phishing). Alcune app hanno persino abusato di WKWebView per iniettare script o alterare i contenuti (ad es. è stato notato che TikTok iniettava JS di tracciamento tramite il proprio browser in-app), quindi bisogna fare attenzione a utilizzare WKWebView in un modo sicuro e affidabile per l'utente.

SFSafariViewController offre un'esperienza Safari in-app. Quando apri un URL con SFSafariViewController, è quasi come aprirlo nel vero browser Safari, tranne per il fatto che l'utente rimane all'interno dell'UI della tua app. Il vantaggio per le passkey è significativo: poiché è essenzialmente Safari, il Portachiavi di iCloud e le passkey salvate dell'utente 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'autocomplete della Conditional UI per un facile accesso. SFSafariViewController è meno personalizzabile (non puoi modificare molto la sua barra degli strumenti), ma gestisce automaticamente molte funzionalità di sicurezza e privacy. La barra degli URL viene mostrata, completa dell'icona del lucchetto per HTTPS, che dà agli utenti la sicurezza di trovarsi sul dominio corretto. In generale, SFSafariViewController è considerato più sicuro di una WKWebView grezza ed è più semplice da implementare (Apple lo fornisce come un componente pronto all'uso). Il compromesso principale è che sacrifichi un po' di controllo sul look & feel. Per un flusso di autenticazione, questo è di solito accettabile. La priorità qui è la sicurezza e la facilità di accesso, in cui SFSafariViewController eccelle utilizzando il contesto di Safari.

SFAuthenticationSession / ASWebAuthenticationSession – Queste classi (l'ultima essendo il nome più recente orientato a Swift) sono create appositamente per flussi di login come OAuth o OpenID Connect. Quando hai bisogno di autenticare un utente tramite una pagina web (magari a un IdP esterno), queste sessioni sono la scelta consigliata su iOS. Sono molto simili a SFSafariViewController in quanto utilizzano il browser Safari dietro le quinte e condividono cookie/archiviazione con Safari. La differenza chiave è che SFAuthenticationSession chiederà sempre all'utente se desidera che l'app si autentichi tramite una pagina web (per consapevolezza dell'utente) e utilizzerà automaticamente la sessione Safari esistente dell'utente, se disponibile.

Il vantaggio è un'esperienza SSO senza interruzioni: se l'utente è già connesso 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/Portachiavi di iCloud può essere usata anche qui. La linea guida ufficiale di Apple è quella di usare ASWebAuthenticationSession per qualsiasi cosa sembri un flusso di login. I pro sono una maggiore privacy (la tua app non vede mai le credenziali o i cookie, Safari li gestisce) e supporto SSO integrato. Il contro è che è limitata ai flussi di autenticazione (non la useresti solo per eseguire il rendering di 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é è sicura, condivide lo stato con Safari ed è appositamente creata per l'autenticazione.

Scopri quante persone usano davvero le passkey.

Vedi dati di adozione

Su Android, la decisione relativa a WebView è tra la classica WebView e Chrome Custom Tabs:

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

Android WebView (android.webkit.WebView) è un componente che ti permette di incorporare pagine web nel layout della tua activity. È simile a WKWebView in quanto ti dà il pieno controllo: puoi intercettare la navigazione, iniettare JavaScript, personalizzare l'UI, ecc. Viene anche eseguito all'interno del processo della tua app. Utilizzare una WebView per le passkey significa che la tua app carica la pagina di login web, e quella pagina può avviare una cerimonia di passkey WebAuthn. La moderna Android WebView supporta WebAuthn (a condizione che l'implementazione WebView del dispositivo sia aggiornata tramite Android System WebView o il componente Chrome). Una considerazione importante: per impostazione predefinita, una WebView Android non condivide i cookie o le credenziali salvate con il browser Chrome dell'utente. Quindi qualsiasi passkey creata o utilizzata nella WebView potrebbe non essere nota a Chrome, e viceversa. Questo isolamento può essere positivo per la sicurezza (la tua app non può leggere i cookie del browser), ma potrebbe costringere gli utenti ad accedere nuovamente 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 che la tua app non li sottoponga a phishing. Google ha persino vietato l'uso di WebView per gli accessi OAuth di Google a causa dei potenziali rischi di phishing. In termini di prestazioni, le WebView vanno bene, ma possono essere più lente o utilizzare più memoria rispetto all'uso del browser predefinito dell'utente, specialmente se si caricano pagine pesanti.

Le Chrome Custom Tabs (CCT) sono un approccio ibrido. Consentono alla tua app di aprire una pagina renderizzata da Chrome che sembra far parte della tua app. Puoi personalizzare il colore della barra degli strumenti, aggiungere un logo dell'app, ecc., ma il contenuto viene renderizzato da Chrome in un processo separato. Per le passkey, le 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), la Custom Tab può accedervi. L'utente vedrà anche l'URL reale e gli indicatori di sicurezza, che costruiscono la fiducia. Le prestazioni sono spesso migliori: Chrome può essere "riscaldato" in background per un caricamento più rapido. Ed è importante che la sicurezza sia forte: poiché è essenzialmente l'app Chrome, elementi come Google Safe Browsing proteggono la sessione, e la tua app non può iniettare script arbitrari nella pagina (prevenendo certi attacchi).

Il lato negativo è che richiede che l'utente abbia Chrome (o un browser supportato) installato e aggiornato. La maggior parte degli utenti Android lo fa, ma su alcuni dispositivi in certe regioni, questo potrebbe essere un problema. Nel complesso, se opti per un approccio web integrato su Android, si raccomandano le Chrome Custom Tabs per i flussi con passkey, poiché offrono un buon equilibrio di integrazione e sicurezza. Infatti, sono per molti versi analoghe a SFSafariViewController/ASWebAuthSession di iOS: sfruttano il browser predefinito per l'autenticazione.

(Nota a margine: WKWebView di Apple vs SFSafariViewController e WebView di Android vs CCT hanno molti paralleli. Sia Safari VC che le Chrome Tabs condividono lo stato del browser e offrono una migliore sicurezza, mentre WKWebView/Android WebView danno più controllo ma isolano i contenuti web. Per le passkey, condividere lo stato (cookie, archivi credenziali) è di solito auspicabile affinché la passkey possa essere accessibile e creata senza problemi.)

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

Nota sui dispositivi gestiti: Il comportamento delle passkey cambia in modo significativo sui dispositivi gestiti dove i criteri Mobile Device Management (MDM) controllano l'archiviazione delle credenziali. Per testare le passkey su dispositivi gestiti, consulta le passkey sui dispositivi gestiti iOS e Android.

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

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:

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

Esempio di file AASA:

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

Caching AASA e Test:

Apple memorizza nella cache in modo aggressivo i file AASA (fino a 24-48 ore) utilizzando una CDN, il che può frustrare lo sviluppo e i test. Per bypassare il caching durante lo sviluppo:

1. Abilita la Developer Mode 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: utilizzarlo in produzione impedirà a iOS di rilevare correttamente il tuo file AASA, interrompendo la funzionalità delle passkey.

Convalida: Usa AASA Validator di Apple per verificare la tua configurazione.

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

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

Requisiti di configurazione:

• Ospitalo su /.well-known/assetlinks.json sul tuo dominio
• Distribuiscilo tramite HTTPS con certificato valido
• Content-Type: application/json
• Includi l'impronta digitale 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"
            ]
        }
    }
]

Convalida: Usa Digital Asset Links Generator di Google per creare e verificare la tua configurazione.

Le app iOS richiedono i corretti entitlement per accedere alla funzionalità delle passkey. I requisiti differiscono leggermente in base al tuo approccio di implementazione.

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

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

L'implementazione nativa e la Embedded WebView richiedono la capacità Associated Domains per collegare la tua app al tuo dominio web. System WebView (ASWebAuthenticationSession) non lo richiede poiché viene eseguito 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>

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

Le Embedded WebView di Android supportano le passkey tramite due approcci distinti: il nuovo approccio basato su WebKit (Sezione 5.3.1) e il vecchio approccio con bridge JavaScript (Sezione 5.3.2). System WebView (Chrome Custom Tabs) non richiede alcuna configurazione: le credenziali funzionano automaticamente.

Android fornisce esempi ufficiali per le passkey in WebView che dimostrano entrambi gli approcci di implementazione.

La moderna integrazione di WebKit con la gestione nativa delle passkey. Questo approccio fornisce supporto WebAuthn nativo senza richiedere codice bridge personalizzato.

Esempio ufficiale: Webkit WebView MainActivity

Requisiti:

• AndroidX WebKit 1.12.1 o versioni successive (consigliato 1.14.0+)
• Digital Asset Links configurati
• WebView APK con supporto WebAuthn (controllare tramite rilevamento delle funzionalità)
• Nota: La libreria AndroidX Credentials NON è richiesta per la WebView WebAuthn, solo per le implementazioni completamente native

Implementazione:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Check if Web Authentication is supported
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Enable Web Authentication
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Enable JavaScript
    webView.settings.javaScriptEnabled = true
}

Punti chiave:

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

Note sulla versione:

• Usa WebKit 1.12.1 o più recente (la 1.12.0 presentava un problema di disponibilità a runtime)
• Il supporto della funzionalità dipende dalla versione dell'APK WebView dell'utente: gli APK precedenti sul dispositivo non esporranno la funzionalità

Prima di AndroidX WebKit 1.12.0, il supporto WebAuthn nativo non esisteva nella Embedded WebView. Questo vecchio approccio utilizza un bridge Web-to-Native per gestire le passkey per i dispositivi senza supporto WebAuthn nativo per la WebView.

Esempi Ufficiali:

• PasskeyWebListener (Gestore Bridge)
• Utilità di codifica JavaScript

Quando utilizzarlo: Quando si supportano versioni precedenti di Android o dispositivi con implementazioni WebView legacy.

I team dovevano o:

1. Utilizzare le Chrome Custom Tabs o Auth Tab (consigliato)
2. Costruire un bridge JavaScript personalizzato

Per l'implementazione dettagliata, vedi Guida all'integrazione della Credential Manager WebView di Android. Tuttavia, raccomandiamo vivamente l'uso dell'approccio nativo WebKit 1.12.1+ per le app moderne.

Raccomandazione: Usa il supporto WebAuthn nativo con AndroidX WebKit 1.12.1+. Se non è disponibile a runtime, passa alle Chrome Custom Tabs che offrono un eccellente supporto alle passkey con credenziali condivise.

Quando implementi le passkey in app native, devi stabilire una fiducia tra la tua app e il dominio/i web. Questa sezione copre come gestire i domini singoli, i domini multipli correlati (ROR) e come verificare che i file di associazione well-known siano configurati correttamente.

Per le app che usano un singolo dominio (ad es. kayak.com), hai bisogno di:

• Un file AASA per iOS su https://kayak.com/.well-known/apple-app-site-association
• Un assetlinks.json per Android su https://kayak.com/.well-known/assetlinks.json
• Entitlement Associated Domains configurati con webcredentials:kayak.com

Le origini correlate (ROR - Related Origins) sono una funzionalità WebAuthn che consente a un singolo set di passkey di funzionare su più domini correlati (ad es. kayak.com, kayak.de, kayak.co.uk). Il ROR utilizza l' endpoint /.well-known/webauthn su ciascun 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 rispettivi siti web
• Embedded WebView su iOS 18+: Supporta il ROR quando adeguatamente configurato
• Entitlement Associated Domains: Includono tutti i domini con cui la tua 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 entitlement Associated Domains della tua app
• Avere i file well-known adeguatamente configurati e accessibili

Prima di passare alla produzione, verifica che i file well-known siano adeguatamente configurati e accessibili. Apple e Google forniscono URL di test basati su CDN per verificare la disponibilità dei file:

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 il recupero aggiornato, aggirando la cache CDN
• Se i file non sono accessibili tramite questi URL, la funzionalità delle passkey non funzionerà nella tua app
• Sostituisci kayak.com o kayak.de con il tuo/i dominio/i nei modelli URL sopra

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

Maggiori informazioni: Relying Party ID di WebAuthn nelle app native

La scelta del giusto approccio di implementazione dipende dall'architettura di autenticazione della tua app, dai requisiti OAuth e dalla necessità di controllare le sessioni. Usa questo albero decisionale per determinare il percorso migliore da seguire.

Il seguente diagramma di flusso ti guida attraverso la selezione del giusto approccio di implementazione in base ai requisiti della tua app:

Riferimento rapido per ogni percorso:

• Login basato su OAuth? → System WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• Riutilizzare l'autenticazione web nella shell nativa? → Embedded WebView con configurazione (WKWebView / Android WebView + WebKit 1.12.1+)
• Sviluppo native-first? → Implementazione nativa (AuthenticationServices / Credential Manager)
• Autenticazione web esistente da riutilizzare? → System WebView per un'implementazione rapida; altrimenti Nativa per la UX ottimale

Ecco come ogni approccio si comporta rispetto alle dimensioni chiave:

Spiegazione delle dimensioni:

• Creazione di passkey: Quanto facilmente gli utenti possono creare passkey attraverso questo approccio
• Uso delle passkey: L'esperienza di autenticazione quando si usano passkey esistenti
• Gestione delle passkey: Come gli utenti visualizzano, modificano o eliminano le passkey
• Complessità tecnica: Impegno nello sviluppo e manutenzione continua
• Supporto OAuth: Come l'approccio gestisce i flussi di autenticazione OAuth2/OIDC
• Tempo di setup: Tipica tempistica di implementazione

Consigliata: System WebView

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

• iOS: ASWebAuthenticationSession è progettato specificamente per i flussi OAuth
• Android: Le Chrome Custom Tabs offrono una perfetta integrazione OAuth
• Vantaggi: Minimo codice nativo, condivisione automatica delle credenziali
• Implementazione: Aggiungi WebAuthn alla tua pagina web di autenticazione, poi caricala tramite System WebView

Esempio: App Viaggi come kayak.com e kayak.de utilizzano OAuth per l'autenticazione. La System WebView consente loro di mantenere la loro infrastruttura OAuth esistente aggiungendo il supporto passkey tramite le loro pagine di autenticazione web.

Consigliato: Approccio Ibrido

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

1. Autenticazione iniziale: System WebView gestisce l'accesso OAuth + passkey
2. Gestione sessione: Passa alla Embedded WebView per il contenuto web autenticato in cui è richiesto il controllo di cookie/sessioni
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 utilizzarlo: App che autenticano tramite OAuth ma poi hanno bisogno di mostrare contenuti web autenticati in cui è richiesta la manipolazione diretta della sessione.

Consigliato: Implementazione nativa

Stai costruendo da zero o hai schermate native? Passa al nativo in modo completo:

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

Per le nuove app: Si consiglia vivamente di costruire l'accesso nativo sin dal primo giorno. Ti prepara per una UX ottimale ed evita future migrazioni da WebView a nativo.

Consigliato: Migrazione graduale

Il diagramma seguente mostra il percorso di migrazione incrementale:

Ogni fase si basa sulla precedente, consentendo miglioramenti incrementali senza interrompere gli utenti esistenti.

Vedi la Sezione 5 per istruzioni dettagliate sulla configurazione.

Testare le passkey in app native richiede un approccio strutturato e a più livelli. Segui la piramide dei test: unit test (logica isolata), test di integrazione (cerimonia WebAuthn su simulatori/emutatori) e test di sistema (end-to-end su dispositivi fisici).

Categorie di test essenziali:

• Percorsi chiave: Registrazione, autenticazione, flussi cross-device, eliminazione della passkey
• Copertura piattaforma: iOS (nativo), Android (nativo), browser web su varie versioni OS
• Associazione del dominio: Verifica che i file AASA (iOS) e Digital Asset Links (Android) siano accessibili
• Flussi di annullamento: Testa l'annullamento dell'utente nei prompt del sistema operativo e nelle schermate biometriche
• Gestione degli errori: Errori del backend, timeout di rete, mancata corrispondenza delle credenziali
• Casi limite: Blocco schermo disabilitato, iCloud/Google Password Manager disabilitati
• Flussi OAuth: Completa l'integrazione 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 di codici QR e testing di trasporto ibrido
• Specifico per Embedded WebView: Se si utilizza Embedded WebView, verificare la configurazione di WebKit 1.12.1+ su Android
• Monitoraggio di produzione: Dashboard per i tassi di successo, errori e latenza

Per una guida completa ai test, incluse le strategie di automazione, i problemi specifici della piattaforma e una lista di controllo pre-lancio completa, consulta la nostra guida dedicata: Testing dei flussi passkey nelle app native iOS e Android.

Prendi in considerazione la possibilità di suggerire agli utenti di creare passkey dopo un login tradizionale effettuato con successo (password, OAuth). Questo approccio di conversione graduale:

• Non interrompe i flussi di autenticazione esistenti
• Consente una graceful degradation 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 l'accesso OAuth tramite System WebView, mostra un prompt nativo: "Abilitare il login più veloce con Face ID?". Se accettato, crea la passkey tramite la pagina web caricata nella System WebView.

Decidere come implementare le passkey - tramite implementazione nativa, System WebView o Embedded WebView - è una scelta di progettazione cruciale che incide sulla sicurezza, l'esperienza utente e la 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 consigliato. Offre un eccellente supporto OAuth, uno sforzo di implementazione minimo e una condivisione automatica delle credenziali.

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

Per i requisiti del frame Embedded WebView: La Embedded WebView è comunemente utilizzata in due scenari del mondo reale. In primo luogo, le app basate su OAuth spesso utilizzano la System WebView per il flusso iniziale di login, poi passano alla Embedded WebView per il rendering delle opzioni di gestione delle passkey nelle schermate delle impostazioni dove è richiesto il controllo della sessione - sebbene alcune app semplifichino ciò mantenendo la System WebView per entrambi i flussi. In secondo luogo, le app che già incorporavano il proprio flusso di autenticazione nei frame WebView prima di adottare le passkey continuano su questo modello per coerenza. L'Embedded WebView con supporto WebAuthn nativo (AndroidX WebKit 1.12.1+) richiede configurazione e impostazione (permessi, entitlement, impostazioni WebView) ma non necessita più del codice del bridge JavaScript personalizzato. Nota che la Conditional UI non è supportata nella Embedded WebView. Scegli questo approccio quando mantieni modelli di autenticazione incorporati esistenti o quando hai bisogno del controllo della sessione/cookie per le schermate post-autenticazione.

In definitiva, le passkey nelle app native rappresentano un enorme passo in avanti sia per la comodità dell'utente che per la sicurezza. Che siano implementate tramite Native, System WebView o Embedded WebView, eliminano i rischi di phishing e il peso della gestione delle password per i tuoi utenti. Implementazioni nel mondo reale come l'integrazione nativa delle passkey nell'app VicRoads dimostrano che gli approcci native-first offrono la massima adozione e soddisfazione dell'utente se adeguatamente eseguiti 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 le nuove app, System WebView per i flussi OAuth o Embedded WebView per i modelli incorporati esistenti - puoi offrire accessi biometrici e senza password che realizzano appieno la visione delle passkey: un'autenticazione semplice, sicura e piacevole per tutti.

Se le passkey non funzionano nella tua app nativa, controlla questi problemi comuni in base all'approccio di implementazione:

• File serviti tramite 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 digitale SHA256 corrisponde al certificato di firma in assetlinks.json
• L'ID Relying Party corrisponde al tuo dominio (nessun protocollo, nessuna porta)
• Nessuno slash finale nel RP ID
• Origine WebAuthn: https://tuo-dominio.com (non app://)

• 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 (biometria o PIN)
• Testare con l'AASA Validator di Apple e lo strumento Digital Asset Links di Google
• Verificare che il file Runner.entitlements contenga i domini associati corretti

• iOS: Utilizzo di ASWebAuthenticationSession (consigliato) o SFSafariViewController
• Android: Utilizzo di Chrome Custom Tabs (non WebView semplice)
• iOS: Verificare che i Domini Associati siano configurati se necessario
• Testare che i cookie/le credenziali siano condivisi con il browser di sistema
• Verificare che la pagina web di autenticazione abbia una corretta implementazione WebAuthn

• iOS: Configurato con i corretti entitlement
• iOS: I Domini Associati includono tutti i domini rilevanti
• iOS: File AASA accessibile e formattato correttamente
• iOS: Testare con ?mode=developer durante lo sviluppo (rimuovere per la produzione)
• Android: AndroidX WebKit 1.12.1+ (o successivi) incluso nel progetto
• Android: Controllo delle funzionalità in runtime per WebViewFeature.WEB_AUTHENTICATION
• Android: setWebAuthenticationSupport() chiamato con WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: JavaScript abilitato nelle impostazioni della WebView
• Android: La versione dell'APK 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 a Chrome Custom Tabs se la funzionalità WebAuthn non è disponibile

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

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

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

Nessun prompt per la passkey compare

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

Per un debugging dettagliato, consulta il nostro articolo sui Relying Party ID nelle app native.

Una trappola comune: gli ambienti di staging con accesso limitato (IP whitelist, solo VPN) falliranno perché le CDN di Apple e Google devono essere in grado di recuperare i tuoi file di associazione.

• I file AASA/assetlinks sono pubblicamente accessibili (nessun IP whitelist, nessun requisito VPN)
• Verifica che la CDN Apple possa raggiungere il tuo file: https://app-site-association.cdn-apple.com/a/v1/il-tuo-dominio-staging.com?nocache=1
• Verifica che Google possa raggiungere il tuo file: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://il-tuo-dominio-staging.com&relation=delegate_permission/common.handle_all_urls

Sottodominio di staging con rpID di produzione:

Se il tuo ambiente di staging (ad es., stg.login.example.com) utilizza il dominio di produzione come rpID (ad es., example.com), la ricerca AASA avviene sul dominio rpID, non sul tuo sottodominio di staging. Ciò significa:

• Aggiungi gli ID bundle dell'app di staging al tuo file AASA di produzione
• Sii consapevole che le passkey create nello staging appariranno nei flussi di login in produzione (potenziale confusione)

Esempio (ambienti multipli che condividono un solo AASA):

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

Raccomandazione: Usa un rpID di staging separato che corrisponda al tuo dominio di staging per evitare sovrapposizioni di credenziali tra gli ambienti. Questo richiede file AASA accessibili pubblicamente sul dominio di staging.

Chiarimento su ?mode=developer:

Il parametro ?mode=developer nei Domini Associati elude la cache CDN di Apple ma non elude il requisito di accessibilità. Il tuo file AASA deve essere ancora raggiungibile dal dispositivo (non tramite la CDN di Apple, ma direttamente). Questo aiuta durante lo sviluppo quando si itera sulle modifiche AASA, ma non aiuterà se il tuo server di staging è limitato ad una whitelist di IP.

SDK Nativi Corbado:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Flutter Package

Documentazione della piattaforma:

• Apple: Supporting Passkeys
• Google: Credential Manager

Strumenti di convalida:

• Apple AASA Validator
• Google Digital Asset Links Generator

Chi siamo

Corbado è la Passkey Intelligence Platform per i team CIAM che gestiscono l'autenticazione consumer su larga scala. Ti aiutiamo a vedere ciò che i log IDP e gli strumenti di analytics generici non mostrano: quali dispositivi, versioni di OS, browser e gestori di credenziali supportano i passkey, perché gli enrollment non si trasformano in login, dove il flusso WebAuthn fallisce e quando un aggiornamento di OS o browser interrompe silenziosamente il login — tutto senza sostituire Okta, Auth0, Ping, Cognito o il tuo IDP interno. Due prodotti: Corbado Observe aggiunge osservabilità per i passkey e qualsiasi altro metodo di login. Corbado Connect introduce passkey gestiti con analytics integrato (insieme al tuo IDP). VicRoads gestisce i passkey per oltre 5M di utenti con Corbado (+80 % di attivazione passkey). Parla con un esperto di Passkey →

La scelta dipende dalla tua architettura di autenticazione. Se la tua app utilizza OAuth2 o OIDC, System WebView (ASWebAuthenticationSession su iOS o Chrome Custom Tabs su Android) richiede il minor sforzo di implementazione e nessuna configurazione di file di associazione. Per le nuove app native-first, l'implementazione nativa offre un'UX superiore, mentre l'Embedded WebView è adatta alle app che incorporano già l'autenticazione in un frame WebView e necessitano di controllo di sessione o cookie dopo l'accesso.

SFSafariViewController sfrutta il motore di Safari, mostra la barra degli URL con indicatori SSL e offre protezione dal phishing, rendendolo più affidabile per i flussi di autenticazione. WKWebView offre più personalizzazione della UI ma ha un archivio cookie isolato separato da Safari, richiede entitlement Associated Domains e un file AASA per abilitare le passkey, e non mostra la barra degli URL, riducendo i segnali di fiducia dell'utente.

Le Chrome Custom Tabs condividono i cookie e le credenziali salvate con il browser Chrome dell'utente, il che significa che le passkey salvate in Google Password Manager sono accessibili durante l'autenticazione. La WebView standard di Android ha un archivio cookie isolato, non mostra l'URL o gli indicatori SSL, e Google ne ha esplicitamente vietato l'utilizzo per gli accessi agli account Google a causa dei rischi di phishing.

Se un utente ha un gestore di credenziali di terze parti come 1Password impostato come provider attivo, esso intercetterà spesso la creazione e l'archiviazione delle passkey, prendendo la priorità rispetto al gestore di credenziali nativo della piattaforma (Portachiavi di iCloud o Google Password Manager). Ciò significa che le passkey potrebbero essere archiviate nell'app di terze parti anziché nel portachiavi della piattaforma, influendo sulla sincronizzazione cross-device e sul comportamento di gestione delle passkey.

Quando le politiche MDM disabilitano la sincronizzazione delle credenziali, le passkey si legano al dispositivo e non possono passare a un dispositivo sostitutivo, a differenza dei tipici scenari dei consumatori. Le app destinate agli ambienti aziendali dovrebbero pianificare meccanismi di autenticazione di ripiego (fallback) come la password o il login con magic link per gestire i casi in cui un utente riceve un nuovo dispositivo gestito.