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.

Compatibilidad de versiones

La función Restore Credentials de Credential Manager funciona en dispositivos que ejecutan Android 9 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.

Nota: Si bien la implementación del servidor es la misma para las llaves de acceso y las claves de recuperación, tu app del cliente puede admitir claves de recuperación sin admitir llaves de acceso. Dado que las claves de restablecimiento funcionan de forma independiente del método de autenticación de tu app (por ejemplo, contraseñas o Acceder con Google), no es necesario que realices ningún cambio adicional en los métodos de autenticación existentes en el código de tu app.

Dependencias

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

Kotlin

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

Groovy

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

La función Restore Credentials está disponible a partir de 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.

Nota: La función Restore Credentials funciona independientemente de si allowBackup está configurado en manifest.

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 recuperación: Crea una clave de recuperación 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 restauración 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

Crea la clave de restauración después de que el usuario se autentique en tu app, inmediatamente después de acceder o durante un inicio posterior de la app si ya accedió.

Nota: Una clave de restablecimiento está vinculada al nombre de paquete único de una aplicación. Si la app principal y las subapps de tu organización tienen nombres de paquete diferentes, crea una clave de restablecimiento independiente para cada app.

Crea una instancia del Administrador de credenciales

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 envolviendo estas opciones en un objeto CreateRestoreCredentialRequest y llamando al método createCredential() con el objeto 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)

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 permite hacer una copia de seguridad de las claves de restauración 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.
  Precaución: Se recomienda establecer isCloudBackupEnabled en true. Si la copia de seguridad en la nube está inhabilitada y el usuario restablece el dispositivo desde una copia de seguridad en la nube, falla la llamada para recuperar la clave de restablecimiento. Los usuarios que restablecen tu app con una copia de seguridad en la nube no reciben la clave de restablecimiento ni acceden automáticamente.

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.
• 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 Restablecer credenciales 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 para 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.

Puedes recuperar la clave de restablecimiento en los siguientes casos:

• (Recomendado) Inmediatamente después de que se restablecen los datos de la app Usa BackupAgent para configurar la copia de seguridad de tu app y completar la funcionalidad de getCredential dentro de la devolución de llamada onRestore para garantizar que las credenciales de la app se restablezcan inmediatamente después de que se restablezcan los datos de la app. Esto evita posibles demoras cuando los usuarios abren su dispositivo nuevo por primera vez y les permite interactuar sin esperar a que abran tu app.
• En el primer inicio de la app en el dispositivo

Para enviar notificaciones a un usuario antes de que abra la app por primera vez en un dispositivo nuevo, recupera la clave de restablecimiento en la devolución de llamada onRestore de BackupAgent. Esto es especialmente relevante para las apps de mensajería o comunicación.

// 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)

Las APIs de Credential Manager devuelven una respuesta del tipo GetCredentialResponse. Esta respuesta 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.

Nota: Aunque las claves de restablecimiento y las llaves de acceso usan la misma implementación del servidor subyacente, diferéncialas cuando las guardes en la base de datos del servidor de tu app. Esta distinción es fundamental cuando existe una página de administración de llaves de acceso, ya que los usuarios pueden administrar las llaves de acceso creadas por el usuario directamente, mientras que las claves de recuperación son administradas por el sistema y están ocultas en la página de administración de llaves 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 llave 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 cierre su sesión y se le solicite 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 manejes 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)

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