Le passkey sono diventate lo standard per un'autenticazione sicura e facile da usare e un numero crescente di servizi le sta adottando sia sui siti web sia sulle app per Android. Tuttavia, quando inizi ad aggiungere passkey a un'app per Android, spesso ti trovi di fronte a una domanda fondamentale sull'architettura: chiami direttamente le API native, apri la pagina di accesso web esistente in una scheda del browser o esegui le passkey all'interno di una WebView in-app?
Panoramica
Puoi supportare le passkey nelle app per Android tramite tre approcci principali: Gestore delle credenziali, scheda Auth e WebView. La documentazione ufficiale illustra i dettagli di implementazione passo passo per ogni opzione. La scelta di un'architettura che riduca al minimo l'attrito per gli utenti, mantenendo al contempo gestibili i costi di sviluppo e manutenzione, si riduce alla comprensione delle caratteristiche e dei vincoli di ciascuna opzione a un livello generale. Questa guida spiega come scegliere l'approccio giusto in base al design dell'app e all'infrastruttura di autenticazione esistente. La seguente tabella confronta questi approcci:
| Funzionalità | Gestore delle credenziali | Scheda Auth | WebView |
|---|---|---|---|
| Caso d'uso consigliato | App con UI di accesso nativa | Riutilizzo di una pagina di accesso web esistente o di un provider di identità (IdP) OAuth o OpenID Connect (OIDC) | App WebView ibride esistenti (solo dominio proprietario) |
| UI ed esperienza utente | Integrazione della compilazione automatica della tastiera e del riquadro inferiore del sistema operativo nativo | Scheda del browser dedicata e minimale per l'autenticazione | Pagina web incorporata con riquadro inferiore del sistema operativo nativo |
| Compilazione automatica e UI condizionale | Supportato (compilazione automatica di Gestore delle credenziali) | Supportato (UI condizionale WebAuthn) | Non supportata |
| Condivisione di sessioni e credenziali | Condivide le passkey tra web e app utilizzando assetlinks.json e rpId condiviso (i cookie di Chrome non vengono condivisi) |
Condivide i cookie e lo stato delle credenziali con Chrome (può essere disattivato utilizzando la navigazione temporanea) | Condivide le passkey utilizzando assetlinks.json, ma isola i cookie e le sessioni da Chrome |
Digital Asset Links (assetlinks.json) |
Obbligatorio sul dominio web della relying party | Obbligatorio nel dominio dell'URI di reindirizzamento per i reindirizzamenti HTTPS (consigliato rispetto agli schemi personalizzati, che non lo richiedono) | Obbligatorio nel dominio web della relying party (non può essere utilizzato con IdP esterni o di terze parti) |
Gestore delle credenziali
Se la tua app per Android ha schermate di accesso o registrazione native, la libreria Jetpack Gestore delle credenziali è l'approccio principale consigliato.
Il vantaggio principale di Gestore delle credenziali è che unifica passkey, password e Accedi con Google in un unico riquadro inferiore del sistema semplificato. Quando un utente
esegue l'accesso, completa l'autenticazione biometrica con un tocco senza uscire
dalla tua app, riducendo l'attrito durante l'accesso. Anche se un utente ignora il riquadro inferiore iniziale e tocca un campo di immissione del nome utente o della password, puoi utilizzare PendingGetCredentialRequest per visualizzare passkey, password e Accedi con Google direttamente nella tastiera o nei suggerimenti di compilazione automatica del menu a discesa. Questo
fallback fornisce un'integrazione della compilazione automatica nativa equivalente alla UI
condizionale di WebAuthn.
Gestore delle credenziali offre inoltre la parità completa delle funzionalità con le moderne funzionalità del ciclo di vita delle passkey web. Con Gestore delle credenziali puoi:
- Utilizza la creazione automatica delle passkey (
isConditional = trueinCreatePublicKeyCredentialRequest) per creare silenziosamente una passkey dopo un accesso con password riuscito. - Utilizza l'API Signal per mantenere le credenziali e i nomi utente coerenti con i provider di credenziali.
- Implementa Restore Credentials per consentire agli utenti di accedere automaticamente alla tua app quando configurano un nuovo dispositivo.
Le passkey sono supportate sui dispositivi con Android 9 (livello API 28) e versioni successive,
mentre altre credenziali, come le password, rimangono supportate sulle versioni di Android
precedenti tramite Google Play Services. Su Android 14 (livello API 34) e versioni successive,
Gestore delle credenziali funziona anche con qualsiasi fornitore di credenziali di terze parti selezionato
dall'utente. Funzionalità aggiuntive, come l'integrazione della compilazione automatica basata su View
(PendingGetCredentialRequest) e l'API Signal, richiedono Android 15 (livello API
35) e versioni successive.
Condividi le credenziali tra web e app
Per iniziare, segui i Prerequisiti per ospitare un file Digital Asset Links (assetlinks.json) sul tuo dominio web per associare il tuo sito web e la tua app per Android. L'associazione del tuo sito web e della tua app tramite assetlinks.json significa che condividono lo stesso ID della relying party (rpId), quindi le passkey create sul tuo sito web in Chrome funzionano nella tua app per Android nativa tramite Gestore delle credenziali e le passkey create nella tua app funzionano sul tuo sito web. Gestore delle credenziali condivide le credenziali tra il tuo sito web e la tua app; hai bisogno della scheda Auth solo quando vuoi riutilizzare la UI di accesso web o la pagina IdP.
Come descritto in Crea una passkey, devi anche configurare il server per verificare le origini delle app per Android (android:apk-key-hash:ENCODED_SHA256_HASH, formattate utilizzando l'hash SHA-256 con codifica Base64URL senza padding del certificato di firma dell'APK). Se la tua app ha una UI nativa e vuoi un'esperienza integrata con il sistema operativo per accedere con le passkey, scegli Gestore delle credenziali.
Scheda Auth
Molti servizi utilizzano un microservizio del provider di identità (IdP) basato su OAuth o OpenID Connect (OIDC) oppure vogliono riutilizzare una pagina di accesso web esistente abilitata per le passkey nelle app mobile. In passato, le app utilizzavano le schede personalizzate per questi flussi. A partire da Chrome 137 e AndroidX Browser 1.9.0, la scheda Auth fornisce una scheda del browser dedicata, personalizzata appositamente per i flussi di autenticazione.
Le schede personalizzate standard sono progettate come browser in-app per uso generico, che mostrano elementi UI non correlati all'accesso, come il menu di condivisione, i preferiti e Apri in Chrome, che possono distrarre gli utenti. Inoltre, richiedono la dichiarazione di filtri per intent nel file manifest per ricevere i reindirizzamenti post-autenticazione, l'aggiunta di codice boilerplate e la necessità di misure di protezione contro l'intercettazione degli intent da parte di app dannose.
La scheda Auth risolve queste sfide specifiche dell'autenticazione. Rimuove gli elementi dell'interfaccia utente del browser non necessari, come il pulsante di minimizzazione e il menu di condivisione, e presenta un'interfaccia mirata con solo le funzionalità di accesso essenziali, tra cui la compilazione automatica di passkey e password. Anziché eseguire il routing tramite gli intent del sistema operativo, la scheda Auth invia i reindirizzamenti di autenticazione direttamente a un callback in-app utilizzando uno schema personalizzato o un URL HTTPS verificato con Digital Asset Links, rafforzando la sicurezza e riducendo il boilerplate di implementazione.
Condivisione della sessione e fallback delle schede personalizzate
Per impostazione predefinita, la scheda Auth condivide anche i cookie e lo stato delle credenziali direttamente con il browser Chrome di sistema. Questa condivisione consente alla tua app di sfruttare le sessioni di accesso attive in Chrome ed eseguire l'implementazione WebAuthn esistente così com'è, incluse la UI condizionale e la modalità UI immediata (l'equivalente web di preferImmediatelyAvailableCredentials di Gestore delle credenziali). Al contrario, se il tuo caso d'uso richiede una sessione di autenticazione isolata che non condivide i cookie o la cronologia di navigazione con il browser, puoi attivare la navigazione temporanea chiamando AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true).
Anche se raggruppi androidx.browser:browser (versione 1.9.0 o successive) con la tua app, l'esecuzione della scheda di autenticazione in fase di runtime dipende dal browser predefinito dell'utente. Se il browser predefinito è una versione di Chrome precedente alla 137 o un browser di terze parti che non supporta la scheda Auth, quest'ultima torna automaticamente all'avvio di una scheda personalizzata standard. Quando si verifica questo fallback, il reindirizzamento post-autenticazione viene restituito tramite un filtro per intent in AndroidManifest.xml come nelle schede personalizzate standard, anziché tramite il callback della scheda di autenticazione (ActivityResultCallback). In produzione, Google consiglia di verificare in anticipo il supporto del browser predefinito utilizzando CustomTabsClient.isAuthTabSupported(context, provider) per creare un ramo del flusso o di mantenere il filtro per intent del manifest in modo che l'app possa gestire i risultati di entrambi i percorsi. Per esempi concreti di implementazione del comportamento di riserva, consulta
Android Browser Helper.
Requisiti di sicurezza OAuth e OIDC
La scheda Auth protegge e semplifica solo il canale di reindirizzamento lato client dal browser alla tua app; non protegge automaticamente il protocollo OAuth o OIDC. In particolare, dato il comportamento di fallback delle schede personalizzate, devi seguire OAuth 2.0 per app native (RFC 8252). In particolare, combina PKCE (Proof Key for Code Exchange, RFC 7636) utilizzando i parametri code_challenge e code_verifier per impedire l'intercettazione del codice di autorizzazione, la convalida del parametro state per impedire la falsificazione di richiesta cross-site (CSRF) e gli attacchi di fissazione della sessione, nonché la generazione e la convalida del parametro nonce in OpenID Connect per impedire gli attacchi di replay dei token ID. Con queste protezioni in atto, Google consiglia di eseguire la migrazione delle architetture di accesso basate sul web dalle schede personalizzate standard alla scheda Auth.
WebView
Alcune app sono basate su un'architettura WebView ibrida in cui non è pratico suddividere solo la schermata di accesso in UI nativa (Gestore delle credenziali) o in una scheda del browser (scheda Auth). In questi casi, puoi attivare il supporto di WebAuthn direttamente all'interno di WebView.
Per utilizzare le passkey in WebView, aggiungi sia la libreria AndroidX WebKit
(androidx.webkit:webkit versione 1.12.0 o successive) sia le dipendenze di Gestore delle credenziali (androidx.credentials:credentials e
androidx.credentials:credentials-play-services-auth) al file build.gradle. Successivamente, verifica il supporto delle funzionalità utilizzando WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) e attiva esplicitamente il supporto di WebAuthn chiamando WebSettingsCompat.setWebAuthenticationSupport(webView.settings,
WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP).
Questa configurazione collega automaticamente le richieste di creazione e autenticazione delle passkey dalle pagine web in WebView a Gestore delle credenziali.
Vincoli di dominio e UX
Come per le integrazioni native di Gestore delle credenziali, devi seguire i Prerequisiti per ospitare un file Digital Asset Links (assetlinks.json) sul dominio web della tua relying party per associare la tua app. Il tuo server riceve android:apk-key-hash:ENCODED_SHA256_HASH (l'hash del certificato SHA-256 con codifica Base64URL) come origine. Poiché questo approccio richiede l'hosting di assetlinks.json sul dominio della relying party per considerare attendibile il certificato di firma dell'app per Android, funziona solo se controlli il dominio web della relying party (accesso web proprietario). Se il flusso di autenticazione
reindirizza a un IdP esterno o di terze parti in cui non puoi ospitare
assetlinks.json per il tuo pacchetto applicativo, devi utilizzare la scheda Auth (o Accedi con Google
nativo tramite Gestore delle credenziali) anziché WebView.
Tieni presente due vincoli funzionali e di UX: WebView non supporta la UI condizionale (integrazione della compilazione automatica di mediation: "conditional" quando un utente attiva un campo di immissione) e non condivide i cookie o le sessioni di accesso con il browser Chrome di sistema. A causa di questi vincoli, Google consiglia
Gestore delle credenziali o Auth Tab per la progettazione di nuovi flussi di autenticazione. Tuttavia, se vuoi aggiungere il supporto delle passkey a un'app ibrida proprietaria esistente senza apportare modifiche significative all'architettura, puoi integrare le passkey con WebView.
Riepilogo
Partire dall'UI e dall'infrastruttura di autenticazione attuali della tua app ti aiuta a scegliere l'approccio giusto per le passkey:
- Se la tua app ha una UI di accesso nativa e vuoi un'esperienza integrata con il sistema operativo senza passare a una schermata del browser, scegli Gestore delle credenziali per accedere con una passkey.
- Se gestisci un microservizio IdP OAuth o OIDC, esegui il reindirizzamento a un IdP esterno o vuoi riutilizzare la tua pagina di accesso web esistente abilitata per le passkey (inclusa la UI condizionale) e condividere le sessioni del browser attive con Chrome, adotta Auth Tab e implementa i requisiti di sicurezza in OAuth 2.0 per le app native (RFC 8252), in particolare PKCE,
stateenonce. - Se la tua app è basata su un'architettura WebView ibrida in cui l'accesso deve rimanere all'interno di schermate web proprietarie incorporate, utilizza WebView tenendo conto della mancanza di supporto della UI condizionale e dei cookie isolati.
Passaggi successivi
- Informazioni sulle passkey
- Crea una passkey
- Accedi con una passkey
- Autenticazione utente con passkey
- Autentica gli utenti con WebView
- Guida alla scheda Auth
- Documentazione di Chrome Identity