Implementare il ripristino delle credenziali con Credential Manager

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

Compatibilità delle versioni

La funzionalità Ripristina credenziali di Credential Manager funziona su dispositivi con Android 9 e versioni successive, Google Play Services (GMS) core versione 24220000 o successive e versione 1.5.0 o successive della libreria androidx.credentials.

Prerequisiti

Configura un server 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.

Dipendenze

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Trendy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

Il ripristino delle credenziali è disponibile a partire 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.

Panoramica

Crea una chiave di ripristino: per creare una chiave di ripristino, completa i seguenti passaggi:
1. Instantiate Credential Manager: 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 ha eseguito l'accesso alla tua app.
4. Gestisci la risposta alla creazione delle credenziali: invia le credenziali dalla tua app client al server dell'app per l'elaborazione e gestisci eventuali eccezioni.
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 Gestione credenziali quando l'utente configura un nuovo dispositivo. In questo modo l'utente può accedere senza ulteriori input.
3. Gestisci la risposta al recupero delle credenziali: invia la chiave di ripristino dall'app client al server dell'app per consentire all'utente di accedere.
Elimina una chiave di ripristino.

Crea una chiave di ripristino

Crea la chiave di ripristino dopo che l'utente si è autenticato nella tua app, immediatamente dopo l'accesso o durante un successivo avvio dell'app se ha già eseguito l'accesso.

Crea un'istanza di Credential Manager

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)

Recuperare 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 le credenziali di ripristino, ad esempio informazioni sull'utente, sull'app e proprietà di configurazione aggiuntive. Per saperne di più sull'implementazione lato server, consulta la Guida 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 racchiudendo queste opzioni in un oggetto CreateRestoreCredentialRequest e chiamando il metodo createCredential() con l'oggetto CredentialManager.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
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 la chiave di ripristino deve essere sottoposta a backup nel cloud. Per impostazione predefinita, questo flag è true. Questo campo ha i seguenti valori:
  - true: (consigliato) questo valore consente il backup delle chiavi di ripristino sul cloud se l'utente ha attivato il backup di Google 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 accedono automaticamente.

Gestire la risposta di creazione delle credenziali

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

Invia la chiave pubblica dalla tua app al server della relying party. 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 della chiave di recupero. Per saperne di più sull'implementazione lato server, consulta la guida per le passkey.

Durante la procedura 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 di backup dei dati o crittografia end-to-end, ad esempio un blocco schermo.
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.

Accedere con una chiave di ripristino

Utilizza Ripristina credenziali per accedere automaticamente all'utente durante la procedura di configurazione del dispositivo.

Recuperare 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 per questo passaggio, consulta Accedere con una passkey. Per saperne di più sull'implementazione lato server, consulta la guida all'autenticazione lato server.

Recuperare la chiave di ripristino

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

Puoi recuperare la chiave di ripristino nei seguenti scenari:

(Consigliato) Immediatamente dopo il ripristino dei dati dell'app. Utilizza BackupAgent per configurare il backup dell'app e completare la funzionalità getCredential all'interno del callback onRestore per assicurarti che le credenziali dell'app vengano ripristinate immediatamente dopo il ripristino dei dati dell'app. In questo modo si evitano potenziali ritardi quando gli utenti aprono il nuovo dispositivo per la prima volta e possono interagire senza dover attendere l'apertura della tua app.
Al primo avvio dell'app sul dispositivo.

Per inviare notifiche a un utente prima che apra l'app per la prima volta su un nuovo dispositivo, recupera la chiave di ripristino all'interno del callback BackupAgent di onRestore. Ciò è particolarmente pertinente per le app di messaggistica o comunicazione.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

Le API di gestione delle credenziali restituiscono una risposta di tipo GetCredentialResponse. Questa risposta contiene la chiave pubblica.

Invia la chiave pubblica dall'app al server della relying party, che può essere utilizzata per accedere all'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 recupero. Per saperne di più sull'implementazione lato server delle passkey, vedi Accedere con una passkey.

Elimina la chiave di ripristino

Credential Manager è stateless e non conosce l'attività utente, quindi non elimina automaticamente le chiavi di ripristino dopo l'uso. Per eliminare una chiave di ripristino, chiama il metodo clearCredentialState(). Per motivi di sicurezza, elimina la chiave ogni volta che un utente esce. In questo modo, la volta successiva che l'utente aprirà l'app sullo stesso dispositivo, verrà disconnesso e gli verrà chiesto di accedere di nuovo.

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

Le chiavi di ripristino vengono rimosse solo nelle seguenti situazioni:

Azioni a livello di sistema: gli utenti disinstallano l'app o cancellano i relativi dati.
Chiamate a livello di app: elimina la chiave a livello di programmazione chiamando clearCredentialState() quando gestisci la disconnessione dell'utente nel codice dell'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)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)