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 la skill Android Restore Credentials 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

Restore Credentials di Gestore delle credenziali funziona sui dispositivi con Android 9 (livello API 28) e versioni successive, Google Play Services (GMS) versione core 242200000 (v24.22) o successive e versione 1.5.0 o successive della libreria androidx.credentials. Sui dispositivi senza Google Play Services o con una versione GMS precedente, intercetta CreateCredentialProviderConfigurationException e GetCredentialProviderConfigurationException in modo che l'app torni correttamente all'accesso standard.

Prerequisiti

Configura un server della relying party WebAuthn simile al server per le passkey. Se hai già configurato un server per gestire l'autenticazione con le passkey, puoi riutilizzare gli stessi endpoint di registrazione e asserzione WebAuthn per le chiavi di ripristino.

Nota: anche se la convalida crittografica 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 rivolte agli utenti. Archivia le chiavi di ripristino con un flag di credenziali distinto nel database di backend in modo che non vengano visualizzate nelle schermate di gestione delle passkey rivolte agli utenti.

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, se possibile, ti consigliamo di utilizzare le versioni stabili più recenti delle dipendenze.

In che modo android:allowBackup influisce su Restore Credentials

L'attributo manifest android:allowBackup controlla il backup dei dati dell'app, che interagisce con Restore Credentials in tre modi distinti:

• Ripristina il trasferimento della chiave (indipendente da allowBackup): Google Play Services trasferisce la coppia di chiavi RestoreCredential utilizzando il backup sul cloud con crittografia end-to-end o il trasferimento locale da dispositivo a dispositivo (D2D), indipendentemente dal fatto che android:allowBackup sia true o false. Per i trasferimenti D2D, la chiave di ripristino viene sempre trasferita. L'unica condizione in cui non viene trasferita è durante un backup sul cloud quando l'utente ha disattivato il backup sul cloud nelle Impostazioni di Android.
• Ripristino in background in BackupAgent (richiede android:allowBackup="true"): l'accesso in background silenzioso prima che l'utente apra l'app sul nuovo dispositivo (BackupAgent.onRestoreFinished()) viene eseguito solo quando android:allowBackup="true" e android:backupAgent sono configurati nel manifest. Se android:allowBackup="false", ripristina la sessione quando l'utente avvia per la prima volta la tua Activity principale. Puoi anche implementare entrambi gli approcci per rendere il ripristino più efficace.
• Test del backup sul cloud di Android Studio (richiede android:allowBackup="true"): il test del tipo di backup Cloud nello strumento di backup e ripristino di Android Studio richiede android:allowBackup="true", mentre il test Da dispositivo a dispositivo funziona indipendentemente da allowBackup.

Panoramica

Restore Credentials segue un ciclo di vita in tre fasi sui dispositivi precedenti e nuovi dell'utente:

1. Crea una chiave di ripristino sul dispositivo precedente: dopo che l'utente ha eseguito l'accesso (o all'avvio dell'app se l'utente ha già eseguito l'accesso e non è registrata alcuna chiave di ripristino nello spazio di archiviazione locale), recupera le opzioni di creazione dal server della relying party e chiama credentialManager.createCredential().
2. Accedi con il tasto di ripristino sul nuovo dispositivo: Recupera il trasferitoRestoreCredential utilizzando una strategia a due livelli: prima silenziosamente inBackupAgent.onRestoreFinished() (Quandoandroid:allowBackup="true" ) in modo che la sincronizzazione in background e le notifiche push riprendano immediatamente, e in secondo luogo come soluzione di ripiego nel tuo launcherActivity.onCreate() al primo avvio dell'app.
3. Elimina la chiave di ripristino al momento della disconnessione: quando l'utente si disconnette o la sua sessione viene invalidata dal server, chiama credentialManager.clearCredentialState() con ClearCredentialStateRequest(ClearCredentialStateRequest.TYPE_CLEAR_RESTORE_CREDENTIAL) e cancella il flag di sincronizzazione locale.

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'Activity principale).
• Quando l'utente accede o completa un nuovo flusso di registrazione dell'account.

Per evitare di chiamare createCredential() a ogni avvio dell'app, memorizza un flag di sincronizzazione locale, ad esempio has_synced_restore_credential, nello spazio di archiviazione locale. Non memorizzare questo flag in SharedPreferences o DataStore di cui è stato eseguito il backup per impostazione predefinita, a meno che il file non sia escluso in data_extraction_rules.xml; in caso contrario, il backup automatico copia has_synced_restore_credential = true sul nuovo dispositivo e impedisce a quest'ultimo di generare o ruotare la propria chiave di ripristino.

Nota: una chiave di ripristino è associata al nome di 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 il codice JSON PublicKeyCredentialCreationOptions richiesto per creare la credenziale di ripristino. Per saperne di più sull'implementazione lato server, consulta le indicazioni lato server.

Il JSON delle opzioni di creazione segue la stessa struttura della registrazione della passkey:

{
  "challenge": "<base64url-encoded challenge>",
  "rp": {
    "name": "<relying party name>",
    "id": "<relying party host name>"
  },
  "user": {
    "id": "<base64url-encoded user ID>",
    "name": "<user name>",
    "displayName": "<user display name>"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "attestation": "none",
  "excludeCredentials": [
    {
        "id": "<base64url-encoded credential ID to exclude>", 
        "type": "public-key"
    }
  ],
  "authenticatorSelection": {
    "requireResidentKey": true,
    "residentKey": "required",
    "userVerification": "required"
  }
}

Assicurati che il JSON delle opzioni di creazione soddisfi questi requisiti:

• challenge e user.id: codifica entrambi i valori come stringhe Base64URL senza spaziatura interna (sostituendo + con -, / con _ e rimuovendo = finale). I caratteri Base64 standard o gli ID interi non elaborati causano CreateRestoreCredentialDomException o IllegalArgumentException.
• rp.id: imposta il dominio della tua relying party (ad esempio, example.com).
• pubKeyCredParams: includi {"type": "public-key", "alg": -7} (ES256) e {"type": "public-key", "alg": -257} (RS256).

Crea la chiave di ripristino

Dopo aver ricevuto il JSON delle opzioni di creazione della chiave pubblica dal tuo server, inserisci il JSON in un oggetto CreateRestoreCredentialRequest e chiama createCredential() sull'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, ma viene comunque trasferita durante una configurazione locale device-to-device (D2D) tramite cavo o Wi-Fi.
  Attenzione: imposta isCloudBackupEnabled su true nella chiamata iniziale e utilizza isCloudBackupEnabled = false come riserva solo se viene generato E2eeUnavailableException. Se l'utente ha disattivato il backup sul cloud (o isCloudBackupEnabled è false) e in un secondo momento 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 response.registrationResponseJson dalla tua app al server della relying party per verificare e archiviare la chiave pubblica insieme all'account dell'utente, quindi registra l'indicatore di sincronizzazione locale nello spazio di archiviazione locale. Per saperne di più sulla verifica 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 per i trasferimenti locali da dispositivo a dispositivo (D2D) anche quando la crittografia end-to-end (E2EE) sul cloud non è disponibile, intercetta E2eeUnavailableException e riprova immediatamente createCredential() con CreateRestoreCredentialRequest(requestJson, isCloudBackupEnabled = false).
• IllegalArgumentException: questa eccezione si verifica se requestJson è vuoto, non è un JSON valido o non ha un user.id con codifica Base64URL 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.

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

Prima di chiamare getCredential() sul nuovo dispositivo, richiedi una verifica JSON WebAuthn PublicKeyCredentialRequestOptions dal server dell'app. Poiché l'app sul nuovo dispositivo non sa ancora quale utente sta eseguendo l'accesso, questo endpoint deve essere non autenticato (rilevamento senza utente). Per indicazioni relative al server, consulta Accedi con una passkey e la guida all'autenticazione lato server.

Il file JSON delle opzioni di recupero ha la seguente struttura:

{
  "challenge": "<your app challenge>",
  "allowCredentials": [],
  "rpId": "<your app server domain>"
}

Configura il file JSON delle opzioni di recupero sul tuo server come segue:

• allowCredentials: ometti questo campo o passa un array vuoto ([]) perché l'account dell'utente non è noto prima del ripristino. Dopo che getCredential() restituisce il risultato, il tuo server identifica l'utente dal campo response.userHandle (che corrisponde a user.id registrato durante la creazione) e cerca la chiave pubblica in base a id (credentialId).
• userVerification: impostato su "discouraged" (o "preferred"). Poiché Restore Credentials viene eseguito in modo silenzioso senza UI biometrica o di blocco schermo, Android esegue l'override di "required" in "discouraged" e i dati dell'autenticatore restituiti al server hanno il flag Utente verificato (uv) impostato su false. Configura il verificatore del server WebAuthn in modo che accetti uv = false per le asserzioni della chiave di ripristino.

Ottieni la chiave di ripristino

Per ottenere la chiave di ripristino sul nuovo dispositivo, inserisci il requestJson del server in un GetRestoreCredentialOption all'interno di un GetCredentialRequest e chiama getCredential() sull'oggetto CredentialManager.

Attenzione: non combinare GetRestoreCredentialOption con altri CredentialOption (come GetPublicKeyCredentialOption o GetPasswordOption) nello stesso GetCredentialRequest. Il passaggio di più opzioni con GetRestoreCredentialOption genera un IllegalArgumentException.

Implementa una strategia di ripristino a due livelli in modo che gli utenti possano accedere indipendentemente dall'esecuzione o meno del ripristino dei dati dell'app in background:

• Livello 1 (ripristino in background in BackupAgent.onRestoreFinished()): se il backup dei dati dell'app è abilitato (android:allowBackup="true"), crea una sottoclasse di BackupAgent ed esegui l'override di onRestoreFinished() (non utilizzare onRestore(), che viene chiamato solo per i backup di coppie chiave-valore legacy). Poiché onRestoreFinished() è sincrono e getCredential() è una funzione suspend Kotlin, collega la chiamata utilizzando runBlocking(Dispatchers.IO). Intercetta NoCredentialException senza problemi quando non è presente alcuna chiave di ripristino.
• Livello 2 (fallback in primo piano nell'Avvio app Activity.onCreate()): al primo avvio dell'app, quando non esiste una sessione locale, chiama getCredential() da lifecycleScope prima di mostrare la schermata di accesso. In questo modo vengono gestite le app con android:allowBackup="false" e viene eseguito il recupero se il dispositivo era offline quando onRestoreFinished() è stato eseguito.

Se aggiungi un nuovo BackupAgent a un'app che utilizza già il backup automatico con android:allowBackup="true", imposta anche android:fullBackupOnly="true" sull'elemento <application> in AndroidManifest.xml in modo che Android continui a utilizzare il backup automatico anziché passare al backup di coppie chiave-valore precedente.

Importante: le notifiche push non vengono ripristinate automaticamente quando vengono recuperate le credenziali. All'interno di BackupAgent.onRestoreFinished() (o immediatamente dopo l'accesso di livello 2), recupera un nuovo token di registrazione di Firebase Cloud Messaging (FCM) utilizzando FirebaseMessaging.getInstance().token.await() e registralo con il tuo backend in modo che le notifiche in background vengano riprese prima che l'utente apra l'app.

// 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

L'API Credential Manager restituisce un GetCredentialResponse la cui proprietà credential è un RestoreCredential (non un PublicKeyCredential) contenente authenticationResponseJson.

Gestisci la risposta di accesso

Invia restoreCredential.authenticationResponseJson dall'app al server della relying party per verificare l'asserzione crittografica ed emettere un nuovo token di sessione per l'utente. Per i dettagli sulla verifica lato server, consulta Accedi con una passkey.

Quando progetti lo spazio di archiviazione di backend e le policy del ciclo di vita per le chiavi di ripristino, segui queste linee guida:

• Differenzia le chiavi di ripristino dalle passkey utente: tagga le chiavi di ripristino nel tuo database in modo che siano nascoste dalle schermate di gestione delle passkey rivolte agli utenti ed esenti dai controlli di verifica utente (uv = true).
• Supporta più dispositivi attivi per utente: un utente può avere più dispositivi (ad esempio uno smartphone e un tablet). Consenti più chiavi di ripristino attive per account utente (ad esempio, con chiave per dispositivo o ID installazione) anziché sovrascrivere una singola riga.
• Imposta un TTL appropriato e ripulisci le chiavi orfane: la disinstallazione di un'app o la cancellazione dei dati dell'app elimina la chiave di ripristino locale senza inviare una notifica al server. Conserva le chiavi di ripristino per un periodo di tempo sufficiente a coprire le finestre di upgrade del dispositivo (anche se l'utente esce dal vecchio dispositivo dopo il trasferimento) ed elimina le chiavi obsolete in base al TTL di inattività o ai limiti delle chiavi per utente.

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 motivi di sicurezza, elimina la chiave ogni volta che un utente esce, in modo che non venga eseguito l'accesso silenzioso al successivo avvio dell'app.

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 (ad esempio quando il server restituisce un errore HTTP 401 Unauthorized). Se la tua app rileva un'annullamento della convalida della sessione lato server, elimina la chiave di ripristino anche sul dispositivo.

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.

Poiché un ClearCredentialStateRequest() predefinito cancella solo lo stato della sessione standard e lascia intatta la chiave di ripristino, esegui una doppia cancellazione al momento della disconnessione:

1. Chiama credentialManager.clearCredentialState(ClearCredentialStateRequest()) per cancellare lo stato della sessione del provider di credenziali attivo.
2. Chiama credentialManager.clearCredentialState() con ClearCredentialStateRequest(ClearCredentialStateRequest.TYPE_CLEAR_RESTORE_CREDENTIAL) per eliminare il RestoreCredential archiviato.
3. Elimina l'indicatore has_synced_restore_credential locale dallo spazio di archiviazione locale.

// 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)

Passaggi successivi

• Testa Restore Credentials: testa i flussi di ripristino da cloud e da dispositivo a dispositivo (D2D) utilizzando Android Studio o adb shell bmgr.
• Test automatici di backup e ripristino: scrivi test host JUnit 5 con BackupRestoreController per verificare i ripristini di CLOUD_ENCRYPTED e DEVICE_TO_DEVICE in CI.