Implementare il ripristino delle credenziali con Credential Manager

Questa pagina descrive come creare, accedere ed eliminare una chiave di ripristino.

Competenze Android

Visualizza su GitHub

Restore Credentials

Utilizza una skill Android per implementare i flussi di backup e ripristino di Restore Credentials utilizzando Gestore delle credenziali.

Per installare lo skill dalla CLI Android, esegui:

android skills add restore-credentials

Compatibilità delle versioni

La funzionalità Restore Credentials di Gestore delle credenziali funziona sui dispositivi con Android 9 (livello API 28) e versioni successive, Google Play Services (GMS) versione core 24220000 o successive e versione 1.5.0 o successive della libreria androidx.credentials.

Prerequisiti

Configura un server della relying party simile al server per le passkey. Se hai già configurato un server per gestire l'autenticazione con le passkey, utilizza la stessa implementazione lato server per le chiavi di ripristino.

Nota: anche se l'implementazione lato server è la stessa per le passkey e le chiavi di ripristino, l'app lato client può supportare le chiavi di ripristino senza supportare le passkey. Poiché le chiavi di ripristino funzionano indipendentemente dal metodo di autenticazione nell'app (ad esempio, password o Accedi con Google), non è necessario apportare ulteriori modifiche ai metodi di autenticazione esistenti nel codice dell'app.

Dipendenze

Aggiungi le seguenti dipendenze al file build.gradle del modulo dell'app:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Trendy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

Restore Credentials è disponibile dalla versione 1.5.0 e successive della libreria androidx.credentials. Tuttavia, ti consigliamo di utilizzare le versioni stabili più recenti delle dipendenze, se possibile.

Nota: la funzionalità Restore Credentials funziona indipendentemente dal fatto che allowBackup sia impostato nel manifest.

Panoramica

1. Crea una chiave di ripristino: per creare una chiave di ripristino, completa i seguenti passaggi:
   1. Crea un'istanza di Gestore delle credenziali: crea un oggetto CredentialManager.
   2. Ottieni le opzioni di creazione delle credenziali dal server dell'app: invia all'app client i dettagli necessari per creare la chiave di ripristino dal server dell'app.
   3. Crea la chiave di ripristino: crea una chiave di ripristino per l'account dell'utente se l'utente ha eseguito l'accesso alla tua app.
   4. Gestisci la risposta alla creazione delle credenziali: invia le credenziali dall'app client al server dell'app per l'elaborazione e gestisci eventuali eccezioni.
2. Accedi con una chiave di ripristino: per accedere con una chiave di ripristino, completa i seguenti passaggi:
   1. Ottieni le opzioni di recupero delle credenziali dal server dell'app: invia all'app client i dettagli necessari per recuperare la chiave di ripristino dal server dell'app.
   2. Recupera la chiave di ripristino: richiedi la chiave di ripristino a Gestore delle credenziali quando l'utente configura un nuovo dispositivo. In questo modo l'utente può accedere senza ulteriori input.
   3. Gestisci la risposta di recupero delle credenziali: invia la chiave di ripristino dall'app client al server dell'app per far accedere l'utente.
3. Elimina una chiave di ripristino.

Crea una chiave di ripristino

L'app deve coprire tutti i casi di accesso di un utente per garantire che gli utenti attivi abbiano una chiave di ripristino creata. Crea la chiave di ripristino nei seguenti scenari:

• Se l'utente ha eseguito l'accesso e non è già stata creata una chiave di ripristino (ad esempio nel metodo onCreate per l'elemento Activity principale).
• Quando l'utente accede o completa un flusso di registrazione di un nuovo account.

Per ottimizzare le prestazioni ed evitare l'overhead della creazione o del controllo di una credenziale di ripristino a ogni singolo accesso, imposta un flag boolean o un timestamp di creazione delle credenziali nello spazio di archiviazione locale, ad esempio has_synced_restore_credential, per monitorare se la chiave è già stata creata.

Nota: una chiave di ripristino è associata al nome del pacchetto univoco di un'applicazione. Se l'app principale e le app secondarie della tua organizzazione hanno nomi di pacchetti diversi, crea una chiave di ripristino separata per ogni app.

Crea un'istanza di Gestore delle credenziali

Utilizza il contesto dell'attività della tua app per creare un'istanza di un oggetto CredentialManager.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Recupera le opzioni di creazione delle credenziali dal server dell'app

Utilizza una libreria conforme a FIDO nel server dell'app per inviare all'app client le informazioni necessarie per creare la credenziale di ripristino, ad esempio informazioni sull'utente, sull'app e su proprietà di configurazione aggiuntive. Per saperne di più sull'implementazione lato server, consulta le indicazioni lato server.

Crea la chiave di ripristino

Dopo aver analizzato le opzioni di creazione della chiave pubblica inviate dal server, crea una chiave di ripristino inserendo queste opzioni in un oggetto CreateRestoreCredentialRequest e chiamando il metodo createCredential() con l'oggetto CredentialManager.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

Punti chiave sul codice

• L'oggetto CreateRestoreCredentialRequest contiene i seguenti campi:

  • requestJson: le opzioni di creazione delle credenziali inviate dal server dell'app nel formato dell'API Web Authentication per PublicKeyCredentialCreationOptionsJSON.

  • isCloudBackupEnabled: campo Boolean per determinare se eseguire il backup della chiave di ripristino nel cloud. Per impostazione predefinita, questo flag è true. Questo campo ha i seguenti valori:

    • true: (consigliato) questo valore attiva il backup delle chiavi di ripristino nel cloud se l'utente ha attivato Google Backup e la crittografia end-to-end, ad esempio un blocco schermo.
    • false: questo valore salva la chiave localmente e non nel cloud. La chiave non è disponibile sul nuovo dispositivo se l'utente sceglie di eseguire il ripristino dal cloud.
  Attenzione: ti consigliamo di impostare isCloudBackupEnabled su true. Se il backup sul cloud è disattivato e l'utente esegue il ripristino da un backup sul cloud, la chiamata per recuperare la chiave di ripristino non va a buon fine. Gli utenti che ripristinano la tua app con un backup sul cloud non ricevono la chiave di ripristino e non viene eseguito l'accesso automatico.

Gestisci la risposta alla creazione delle credenziali

L'API Credential Manager restituisce una risposta di tipo CreateRestoreCredentialResponse. Questa risposta contiene la risposta di registrazione delle credenziali della chiave pubblica in formato JSON.

Invia la chiave pubblica dalla tua app al server della terza parte attendibile. Questa chiave pubblica è simile a quella generata quando crei una passkey. Lo stesso codice che gestisce la creazione delle passkey sul server può gestire anche la creazione delle chiavi di ripristino. Per ulteriori informazioni sull'implementazione lato server, consulta le indicazioni per le passkey.

Durante il processo di creazione della chiave di ripristino, gestisci queste eccezioni:

• CreateRestoreCredentialDomException: questa eccezione si verifica se requestJson non è valido e non segue il formato WebAuthn per PublicKeyCredentialCreationOptionsJSON.
• E2eeUnavailableException: questa eccezione si verifica se isCloudBackupEnabled è true, ma il dispositivo dell'utente non dispone del backup dei dati o della crittografia end-to-end, ad esempio un blocco schermo.
  Per assicurarti che le credenziali di ripristino vengano create in tutti i casi, devi gestire E2eeUnavailableException in modo esplicito chiamando createCredential con isCloudBackupEnabled impostato su true. Se viene generato E2eeUnavailableException, intercettalo e chiama di nuovo createCredential con isCloudBackupEnabled impostato su false.
• IllegalArgumentException: questa eccezione si verifica se createRestoreRequest è vuoto o non è un JSON valido oppure se non ha un user.id valido conforme alle specifiche di WebAuthn.

Accedi con una chiave di ripristino

Utilizza Restore Credentials per far accedere l'utente in modo invisibile durante la procedura di configurazione del dispositivo.

Recupera le opzioni di recupero delle credenziali dal server dell'app

Invia all'app client le opzioni necessarie per ottenere la chiave di ripristino dal server. Per indicazioni simili sulle passkey per questo passaggio, consulta Accedi con una passkey. Per saperne di più sull'implementazione lato server, consulta la guida all'autenticazione lato server.

Ottieni la chiave di ripristino

Per ottenere la chiave di ripristino sul nuovo dispositivo, chiama il metodo getCredential() sull'oggetto CredentialManager.

Ti consigliamo di recuperare la chiave di ripristino in entrambi i seguenti scenari:

• Al primo avvio dell'app sul dispositivo. Il ripristino delle credenziali in questo scenario è indipendente dal ripristino dei dati dell'app.
• Se il backup e il ripristino dei dati dell'app sono attivi, recupera la chiave di ripristino immediatamente dopo il ripristino dei dati dell'app. Utilizza BackupAgent per configurare il backup della tua app e assicurati di completare la funzionalità getCredential all'interno del callback onRestoreFinished. Non utilizzare il metodo onRestore, in quanto viene chiamato solo per i backup di coppie chiave-valore, mentre onRestoreFinished viene chiamato in modo affidabile per qualsiasi tipo di ripristino del backup. In questo modo si evitano potenziali ritardi quando gli utenti aprono il nuovo dispositivo per la prima volta e si consente loro di interagire con l'app senza attendere che la aprano. Ad esempio, in questo modo la tua app può inviare notifiche all'utente prima che apra l'app per la prima volta sul nuovo dispositivo, il che è particolarmente importante per le app di messaggistica o di comunicazione.

Se crei un nuovo BackupAgent e in precedenza avevi attivato il backup con allowBackup="true", imposta il valore booleano android:fullBackupOnly="true" nel manifest dell'app. In questo modo, il comportamento di backup e ripristino dell'app viene mantenuto.

Importante: le notifiche non vengono ripristinate automaticamente dopo il recupero delle credenziali di ripristino. Se utilizzi Firebase per gestire le notifiche, devi recuperare e inviare il token Firebase Cloud Messaging (FCM) al backend per riprendere correttamente la messaggistica e le notifiche in background.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

Le API Credential Manager restituiscono una risposta di tipo GetCredentialResponse. La credenziale contenuta in questa risposta è esplicitamente di tipo RestoreCredential, che contiene la chiave pubblica.

Gestisci la risposta di accesso

Invia la chiave pubblica dall'app al server della relying party, che potrà poi essere utilizzata per far accedere l'utente. Sul lato server, questa azione è simile all'accesso con una passkey. Lo stesso codice che gestisce l'accesso con le passkey sul server può gestire anche gli accessi con le chiavi di ripristino. Per ulteriori informazioni sull'implementazione lato server per le passkey, consulta Accedi con una passkey.

Nota: anche se le chiavi di ripristino e le passkey utilizzano la stessa implementazione del server sottostante, differenziale quando le salvi nel database del server dell'app. Questa distinzione è fondamentale quando esiste una pagina di gestione delle passkey, perché gli utenti possono gestire direttamente le passkey create dagli utenti, mentre le chiavi di ripristino sono gestite dal sistema e nascoste dalla pagina di gestione delle passkey.

Elimina la chiave di ripristino

Gestore delle credenziali è stateless e non è a conoscenza dell'attività utente, pertanto non elimina automaticamente le chiavi di ripristino dopo l'utilizzo. Per eliminare una chiave di ripristino, chiama il metodo clearCredentialState. Per sicurezza, elimina la chiave ogni volta che un utente esce. In questo modo, la volta successiva che l'utente apre l'app sullo stesso dispositivo, viene disconnesso e gli viene chiesto di accedere di nuovo.

Nota: la disconnessione di un utente può avvenire anche da remoto, ad esempio quando un utente cambia la password sul web o quando viene disconnesso da remoto dal server. Se la tua app rileva un'annullamento della convalida della sessione lato server di questo tipo, assicurati di eliminare la chiave di ripristino sul dispositivo. (un esempio è il server che restituisce un errore HTTP 401 Unauthorized)

La disinstallazione di un'app viene interpretata come un'intenzione di eliminare la chiave di ripristino corrispondente da quel dispositivo, in modo simile all'intenzione dell'utente quando esce.

Le chiavi di ripristino vengono rimosse solo nelle seguenti situazioni:

• Azioni a livello di sistema: gli utenti disinstallano l'app o ne cancellano i dati.
• Chiamate a livello di app: elimina la chiave in modo programmatico chiamando clearCredentialState() quando gestisci la disconnessione dell'utente nel codice della tua app.

Quando l'utente esce dalla tua app, chiama il metodo clearCredentialState() sull'oggetto CredentialManager.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)