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 Restablecer credenciales del Administrador de credenciales funciona en dispositivos que ejecutan Android 9 y versiones posteriores, la versión principal 24220000 o versiones posteriores de Servicios de Google Play (GMS) y la versión 1.5.0 o versiones posteriores de la biblioteca androidx.credentials.

Requisitos previos

Configura un servidor de entidad emisora 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 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"
}

La función Restablecer credenciales 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.

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 CredentialManager objeto.
    2. Obtén opciones de creación de credenciales del servidor de la app: Envía a la app del cliente los detalles necesarios para crear la clave de restablecimiento desde el servidor de tu 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 del cliente al servidor de tu app para su procesamiento y controla las excepciones.
  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 del cliente los detalles necesarios para recuperar la clave de restablecimiento desde el servidor de tu 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 ingresar información adicional.
    3. Controla la respuesta de recuperación de credenciales: Envía la clave de restablecimiento de la app del 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 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 del 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 restablecimiento envolviendo estas opciones en un CreateRestoreCredentialRequest objeto y llamando al createCredential() método con el CredentialManager objeto.

// 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: 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 restablecerla desde la nube.

Controla la respuesta de creación de credenciales

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

Envía la clave pública de tu app al servidor de la entidad emisora. Esta clave pública es similar a la clave pública 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 claves de restablecimiento, controla estas excepciones:

  • CreateRestoreCredentialDomException: Esta excepción se produce si requestJson no es válida y no sigue el formato 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 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 vuelve a llamar a createCredential 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.

Accede con una clave de restablecimiento

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 del cliente las opciones necesarias para obtener la clave de restablecimiento del servidor. Para obtener una guía similar sobre llaves de acceso para 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:

  • En el primer inicio de la app en el dispositivo (en este caso, el restablecimiento de credenciales es independiente del restablecimiento de los datos de 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 pares clave-valor, mientras que onRestoreFinished se llama 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 la abra por primera vez en el dispositivo nuevo, lo que es especialmente relevante para las apps de mensajería o comunicación.
// 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 muestran una respuesta de tipo GetCredentialResponse. La credencial contenida en esta respuesta es explícitamente de 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 entidad emisora, que luego se puede usar para permitir 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 llaves de acceso, consulta Accede 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 su cuenta. Esto garantiza que la próxima vez que el usuario abra la app en el mismo dispositivo, se cierre la sesión del usuario y se le solicite que vuelva a acceder.

La desinstalación de una app se interpreta como una intención de borrar la clave de restablecimiento correspondiente de ese dispositivo, de manera similar a la intención del usuario cuando sale de su 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 controlas la salida 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)