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

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

android skills add restore-credentials

Compatibilidad de versiones

La función Restablecer credenciales 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 terceros similar al servidor de 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 recuperación.

Dependencias

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

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

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

Restablecer credenciales está disponible en la versión 1.5.0 y versiones 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 de Credential Manager: 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 de tu app cliente al servidor de tu app para que las procese y controla las excepciones.
2. Acceder con una clave de recuperación: Para acceder con una clave de recuperación, 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 de tu servidor de la app.
   2. Obtén la clave de restablecimiento: Solicita la clave de restablecimiento a Credential Manager cuando el usuario configure un dispositivo nuevo. Esto permite que el usuario acceda sin ingresar información adicional.
   3. Controla la respuesta de recuperación de credenciales: Envía la clave de restauración de 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 del usuario para garantizar que los usuarios activos tengan una clave de restablecimiento creada. Crea la clave de restauración en los siguientes casos:

• Si el usuario accedió y aún no se creó una clave de restablecimiento (como en el método onCreate para el 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 ya se creó la clave.

Crea una instancia del Credential Manager

Usa el contexto de 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 enviar a la app cliente la información necesaria para crear la credencial de restablecimiento, como información sobre el usuario, la app y 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 claves públicas que envió el servidor, crea una clave de recuperación. Para ello, encapsula 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 la copia de seguridad desde la nube.

Cómo controlar 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 que confía. 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 recuperación. Para obtener más información sobre la implementación del servidor, consulta la guía sobre 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 garantizar que se creen 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 recuperación

Usa Restore Credentials para permitir 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 restauración del servidor. Para obtener orientación similar sobre las llaves de acceso en este paso, consulta Cómo acceder 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 restauración en los siguientes casos:

• En el primer inicio de la app en el dispositivo. El restablecimiento de credenciales en este caso es independiente del restablecimiento de los datos de la app.
• Si la copia de seguridad y el restablecimiento de 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 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 clave-valor, mientras que onRestoreFinished se llama de forma confiable para cualquier tipo de restauración 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 la abra por primera vez en el dispositivo nuevo, lo que es particularmente relevante para las apps de mensajería o comunicación.

Si creas un nuevo BackupAgent y anteriormente tenías habilitada la copia de seguridad con allowBackup="true", establece 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 de Credential Manager devuelven una respuesta de tipo GetCredentialResponse. La credencial que se incluye en 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 acceder al usuario. 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 el acceso con claves de recuperación. 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 usarlas. Para borrar una clave de recuperación, llama al método clearCredentialState. Por motivos de seguridad, borra la clave cada vez que un usuario salga de su cuenta. Esto garantiza que, la próxima vez que el usuario abra la app en el mismo dispositivo, se le pedirá que vuelva a acceder.

Desinstalar una app se interpreta como un intento de borrar la clave de restablecimiento correspondiente del dispositivo, de manera similar a la intención del usuario cuando cierra la sesión.

Las claves de recuperación 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 controlas el cierre de sesión del usuario en el código de tu 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)