Introducing Restore Credentials: Effortless account restoration for Android apps

Posted by Neelansh Sahai – Developer Relations Engineer

Did you know that, on average, 40% of the people in the US reset or replace their smartphones every year? This frequent device turnover presents a challenge – and an opportunity – for maintaining strong user relationships. When users get a new phone, the friction of re-entering login credentials can lead to frustration, app abandonment, and churn.

To address this issue, we’re introducing Restore Credentials, a new feature of Android’s Credential Manager API. With Restore Credentials, apps can seamlessly onboard users to their accounts on a new device after they restore their apps and data from their previous device. This makes the transition to a new device effortless and fosters loyalty and long term relationships.

On top of all this, there’s no developer effort required for the transfer of a restore key from one device to the other, as this process is tied together with the android system’s backup and restore mechanism. However, if you want to login your users silently as soon as the restore is completed, you might want to implement BackupAgent and add your logic in the onRestore callback. The experience is delightful – users will continue being signed in as they were on their previous device, and they will be able to get notifications to easily access their content without even needing to open the app on the new device.

Some of the benefits of the Restore Credentials feature include:

• Seamless user experience: Users can easily transition to a new Android device.
• Immediate engagement: Engage users with notifications or other prompts as soon as they start using their new device.
• Silent login with backup agent integration: If you’re using a backup agent, users can be automatically logged back in after data restoration is complete.
• Restore key checks without backup agent integration: If a backup agent isn’t being used, the app can check for a restore key upon first launch and then log the user in automatically.

How does Restore Credentials work?

The Restore Credentials feature enables seamless user account restoration on a new device. This process occurs automatically in the background during device setup when a user restores apps and data from a previous device. By restoring app credentials, the feature allows the app to sign the user back in without requiring any additional interaction.

The credential type that’s supported for this feature is called restore key, which is a public key compatible with passkey / FIDO2 backends.

User flow

On the old device:

1. If the current signed-in user is trusted, you can generate a restore key at any point after they’ve authenticated in your app. For instance, this could be immediately after login or during a routine check for an existing restore key.
2. The restore key is stored locally and backed up to the cloud. Apps can opt-out of backing it up to the cloud.

On the new device:

1. When setting up a new device, the user can select one of the two options to restore data. Either they can restore data from a cloud backup, or can locally transfer the data. If the user transfers locally, the restore key is transferred locally from the old to the new device. Otherwise, if the user restores using the cloud backup, the restore key gets downloaded along with the app data from cloud backup to the new device.
2. Once this restore key is available on the new device, the app can use it to log in the user on the new device silently in the background.

Note: You should delete the restore key as soon as the user signs out. You don’t want your user to get stuck in a cycle of signing out intentionally and then automatically getting logged back in.

How to implement Restore Credentials

Using the Jetpack Credential Manager let you create, get, and clear the relevant Restore Credentials:

• Create a 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.
• Get the Restore Credential: When the user sets up a new device, your app requests the Restore Credential from Credential Manager. This allows your user to sign in automatically.
• Clear the Restore Credential: When the user signs out of your app, delete the associated Restore Credential.

Restore Credentials is available through the Credential Manager Jetpack library. The minimum version of the Jetpack Library is 1.5.0-beta01, and the minimum GMS version is 242200000. For more on this, refer to the Restore Credentials DAC page. To get started, follow these steps:

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

// Fetch Registration JSON from server
// Same as the registrationJson created at the time of creating a Passkey
// See documentation for more info
val registrationJson = ... 

// Create the CreateRestoreCredentialRequest object
// Pass in the registrationJSON 
val createRequest = CreateRestoreCredentialRequest(
  registrationJson,
  /* isCloudBackupEnabled = */ true
)

NOTE: Set the isCloudBackupEnabled flag to false if you want the restoreKey to be stored locally and not in the cloud. It’s set as true by default

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
)

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)

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.

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

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(/* requestType = */ 1)

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

Conclusion

The Restore Credentials feature provides significant benefits, ensuring users experience a smooth transition between devices, and allowing them to log in quickly and easily through backup agents or restore key checks. For developers, the feature is straightforward to integrate and leverages existing passkey server-side infrastructure. Overall, Restore Credentials is a valuable tool that delivers a practical and user-friendly authentication solution.