Restore app credentials when setting up a new device

Credential Manager's Restore Credentials feature allows users to restore their app accounts when setting up a new device. This API is in developer preview and available on all devices that have Android 9 or higher and Google Play services (GMS) Core version 242200000 or higher. The benefits of the Restore Credentials feature includes:

• Seamless user experience: Users can restore their app account without needing to manually sign in to each individual app.
• Increased user engagement: Users are more likely to continue using your app if they can restore their account when setting up a new device.
• Reduced development effort: the Restore Credentials feature is integrated with Credential Manager, so developers who already support passkeys can add credential restoration capabilities.

How it works

You can use Restore Credentials to create, get, and clear the relevant credentials.

1. Create the Restore Credential: When the user signs in to your app, create a Restore Credential associated with their account. This credential is stored locally and synced to the cloud if the user has enabled Google Backup and end to end encryption is available (apps can opt out of syncing to the cloud)
2. Get the Restore Credential: When the user sets up a new device, your app can request the Restore Credential from Credential Manager. This lets you sign the user in automatically without requiring any additional input.
3. Clear the Restore Credential: When the user signs out of your app, you should delete the associated Restore Credential.

The Restore Credentials feature can integrate smoothly with backend systems that have already implemented passkeys. This compatibility stems from the fact that both passkeys and restore keys (credential type used by the Restore Credentials feature) adhere to the same underlying technical specifications. This alignment ensures that the Restore Credentials process can effectively retrieve and reinstate user credentials stored in passkey-enabled systems, providing a consistent and user-friendly experience across different platforms and authentication methods.

Implementation

The Restore Credentials API is available through the Credential Manager Jetpack library. To get started, follow these steps:

1. Add the Credential Manager dependency to your project.

   // build.gradle.kts
   implementation("androidx.credentials:credentials:1.5.0-alpha03")
   

2. Create a CreateRestoreCredentialRequest object.

3. Call the createCredential() method on the CredentialManager object.

   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)
   

   This generated restore credential is a type of webauthn credential, and is known as a restore key.

4. When the user sets up a new device, call the getCredential() method on the CredentialManager object.

   // Fetch the Authentication JSON from server
   val authenticationJson = ...
   
   // Create the GetRestoreCredentialRequest object
   val options = GetRestoreCredentialOption(authenticationJson)
   val getRequest = GetCredentialRequest(Immutablelist.of(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)
   

5. When the user signs out of your app, call the clearCredentialState() method on the CredentialManager object.

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

If you're using a backup agent, perform the getCredential part within the onRestore callback. This ensures that the app's credentials are restored immediately after the app data is restored.