Implementa la función Restore Credentials con el Administrador de credenciales

En esta página, se describe cómo crear, acceder y borrar una clave de restablecimiento.

Compatibilidad de versiones

La función Restore Credentials de Credential Manager funciona en dispositivos que ejecutan Android 9 (nivel de API 28) y versiones posteriores, la versión principal 24220000 o posterior de los Servicios de Google Play (GMS) y la versión 1.5.0 o posterior de la biblioteca androidx.credentials.

Requisitos previos

Configura un servidor de la parte que confía similar al servidor para las llaves de acceso. Si ya tienes un servidor configurado para controlar la autenticación con llaves de acceso, usa la misma implementación del servidor para las claves de restablecimiento.

Dependencias

Agrega las siguientes dependencias al archivo build.gradle del módulo de tu app:

Kotlin

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

Groovy

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

Restore Credentials está disponible en la versión 1.5.0 y posteriores de la biblioteca androidx.credentials. Sin embargo, se recomienda usar las versiones estables más recientes de las dependencias siempre que sea posible.

Descripción general

  1. Crea una clave de restablecimiento: Para crear una clave de restablecimiento, completa los siguientes pasos:
    1. Crea una instancia del Administrador de credenciales: Crea un objeto CredentialManager.
    2. Obtén opciones de creación de credenciales del servidor de la app: Envía a la app cliente los detalles necesarios para crear la clave de restablecimiento desde el servidor de la app.
    3. Crea la clave de restablecimiento: Crea una clave de restablecimiento para la cuenta del usuario si este accedió a tu app.
    4. Controla la respuesta de creación de credenciales: Envía las credenciales desde tu app cliente a tu servidor de apps para procesarlas y controlar cualquier excepción.
  2. Accede con una clave de restablecimiento: Para acceder con una clave de restablecimiento, completa los siguientes pasos:
    1. Obtén opciones de recuperación de credenciales del servidor de la app: Envía a la app cliente los detalles necesarios para recuperar la clave de restablecimiento del servidor de la app.
    2. Obtén la clave de restablecimiento: Solicita la clave de restablecimiento al Administrador de credenciales cuando el usuario configure un dispositivo nuevo. Esto permite que el usuario acceda sin necesidad de ingresar más datos.
    3. Controla la respuesta de recuperación de credenciales: Envía la clave de restablecimiento desde la app cliente al servidor de la app para que el usuario acceda.
  3. Borra una clave de restablecimiento.

Crea una clave de restablecimiento

Tu app debe abarcar todos los casos de acceso de un usuario para garantizar que los usuarios activos tengan una clave de restablecimiento creada. Crea la clave de restablecimiento en las siguientes situaciones:

  • Si el usuario accedió y aún no se creó una clave de restablecimiento (como en el método onCreate para la Activity principal).
  • Cuando el usuario accede o completa un flujo de registro de cuenta nueva

Para optimizar el rendimiento y evitar la sobrecarga de crear o verificar una credencial de restablecimiento en cada acceso, establece una marca boolean o una marca de tiempo de creación de credenciales en el almacenamiento local, como has_synced_restore_credential, para hacer un seguimiento de si la clave ya se creó.

Crea una instancia del Administrador de credenciales

Usa el contexto de la actividad de tu app para crear una instancia de un objeto CredentialManager.

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

Obtén opciones de creación de credenciales del servidor de tu app

Usa una biblioteca compatible con FIDO en el servidor de tu app para enviarle a la app cliente la información necesaria para crear la credencial de restablecimiento, como información sobre el usuario, la app y las propiedades de configuración adicionales. Para obtener más información sobre la implementación del servidor, consulta la guía del servidor.

Crea la clave de restablecimiento

Después de analizar las opciones de creación de la clave pública que envió el servidor, crea una clave de restablecimiento. Para ello, une estas opciones en un objeto CreateRestoreCredentialRequest y llama al método createCredential() con el objeto CredentialManager.

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

Puntos clave sobre el código

  • El objeto CreateRestoreCredentialRequest contiene los siguientes campos:

    • requestJson: Son las opciones de creación de credenciales que envía el servidor de la app en el formato de la API de Web Authentication para PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: Campo Boolean para determinar si se debe crear una copia de seguridad de la clave de restablecimiento en la nube. De forma predeterminada, esta marca es true. Este campo tiene los siguientes valores:

      • true: (Recomendado) Este valor habilita la copia de seguridad de las claves de restablecimiento en la nube si el usuario tiene habilitada la copia de seguridad de Google y la encriptación de extremo a extremo, como un bloqueo de pantalla.
      • false: Este valor guarda la clave de forma local y no en la nube. La clave no está disponible en el dispositivo nuevo si el usuario elige restablecer desde la nube.

Controla la respuesta de creación de credenciales

La API de Credential Manager devuelve una respuesta del tipo CreateRestoreCredentialResponse. Esta respuesta contiene la respuesta de registro de credenciales de clave pública en formato JSON.

Envía la clave pública de tu app al servidor de la parte de confianza. Esta clave pública es similar a la que se genera cuando creas una llave de acceso. El mismo código que controla la creación de llaves de acceso en el servidor también puede controlar la creación de claves de restablecimiento. Para obtener más información sobre la implementación del servidor, consulta la guía para llaves de acceso.

Durante el proceso de creación de la clave de restablecimiento, controla estas excepciones:

  • CreateRestoreCredentialDomException: Esta excepción se produce si requestJson no es válido y no sigue el formato de WebAuthn para PublicKeyCredentialCreationOptionsJSON.
  • E2eeUnavailableException: Esta excepción se produce si isCloudBackupEnabled es true, pero el dispositivo del usuario no tiene copia de seguridad de datos ni encriptación de extremo a extremo, como un bloqueo de pantalla.
    Para asegurarte de que se creen las credenciales de restablecimiento en todos los casos, debes controlar E2eeUnavailableException de forma explícita llamando a createCredential con isCloudBackupEnabled establecido en true. Si se arroja E2eeUnavailableException, captura y llama a createCredential de nuevo con isCloudBackupEnabled establecido en false.
  • IllegalArgumentException: Esta excepción se produce si createRestoreRequest está vacío o no es un JSON válido, o si no tiene un user.id válido que cumpla con las especificaciones de WebAuthn.

Cómo acceder con una clave de restablecimiento

Usa Restore Credentials para que el usuario acceda de forma silenciosa durante el proceso de configuración del dispositivo.

Obtén opciones de recuperación de credenciales del servidor de la app

Envía a la app cliente las opciones necesarias para obtener la clave de restablecimiento del servidor. Para obtener orientación similar sobre las llaves de acceso en este paso, consulta Accede con una llave de acceso. Para obtener más información sobre la implementación del servidor, consulta la guía de autenticación del servidor.

Obtén la clave de restablecimiento

Para obtener la clave de restablecimiento en el dispositivo nuevo, llama al método getCredential() en el objeto CredentialManager.

Se recomienda recuperar la clave de restablecimiento en las siguientes situaciones:

  • Cuando se inicia la app por primera vez en el dispositivo El restablecimiento de credenciales en esta situación es independiente del restablecimiento de los datos de la app.
  • Si la copia de seguridad y el restablecimiento de los datos de app están habilitados, obtén la clave de restablecimiento inmediatamente después de que se restablezcan los datos de app. Usa BackupAgent para configurar la copia de seguridad de tu app y asegúrate de completar la funcionalidad de getCredential dentro de la devolución de llamada onRestoreFinished. No uses el método onRestore, ya que solo se llama para las copias de seguridad de pares clave-valor, mientras que se llama a onRestoreFinished de manera confiable para cualquier tipo de restablecimiento de copia de seguridad. Esto evita posibles demoras cuando los usuarios abren su dispositivo nuevo por primera vez y les permite interactuar con la app sin esperar a que la abran. Por ejemplo, esto permite que tu app envíe notificaciones al usuario antes de que abra la app por primera vez en el dispositivo nuevo, lo que es particularmente relevante para las apps de mensajería o comunicaciones.

Si creas un BackupAgent nuevo y, antes, tenías habilitada la copia de seguridad con allowBackup="true", configura el valor booleano android:fullBackupOnly="true" en el manifiesto de tu app. Esto garantiza que se mantenga el comportamiento de copia de seguridad y restablecimiento de tu 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

Las APIs del administrador de credenciales devuelven una respuesta de tipo GetCredentialResponse. La credencial que contiene esta respuesta es explícitamente del tipo RestoreCredential, que contiene la clave pública.

Controla la respuesta de acceso

Envía la clave pública de la app al servidor de la parte que confía, que luego se puede usar para que el usuario acceda. En el servidor, esta acción es similar a acceder con una llave de acceso. El mismo código que controla el acceso con llaves de acceso en el servidor también puede controlar los accesos con claves de restablecimiento. Para obtener más información sobre la implementación del servidor para las llaves de acceso, consulta Cómo acceder con una llave de acceso.

Borra la clave de restablecimiento

Credential Manager no tiene estado y no conoce la actividad del usuario, por lo que no borra automáticamente las claves de restablecimiento después de su uso. Para borrar una clave de restablecimiento, llama al método clearCredentialState. Por seguridad, borra la clave cada vez que un usuario salga de la sesión. Esto garantiza que, la próxima vez que el usuario abra la app en el mismo dispositivo, se cierre su sesión y se le solicite que vuelva a acceder.

La desinstalación de una app se interpreta como un intento de borrar la clave de restablecimiento correspondiente de ese dispositivo, de manera similar a la intención del usuario cuando sale de la cuenta.

Las claves de restablecimiento solo se quitan en las siguientes situaciones:

  • Acciones a nivel del sistema: Los usuarios desinstalan la app o borran sus datos.
  • Llamadas a nivel de la app: Borra la clave de forma programática llamando a clearCredentialState() cuando se controle la salida del usuario en el código de la app.

Cuando el usuario salga de tu app, llama al método clearCredentialState() en el objeto 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)