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 con Android 9 y versiones posteriores, la versión principal 24220000 o posterior de 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 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-alpha01")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha01")
}

Groovy

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

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

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 apps: Envía a la app del cliente los detalles necesarios para crear la clave de restablecimiento desde tu servidor.
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 apps para su procesamiento y controla las excepciones.
**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 apps: Envía a la app del cliente los detalles necesarios para recuperar la clave de restablecimiento desde tu servidor de apps.
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 apps para que el usuario acceda.
Borra una clave de restablecimiento.

Crea una clave de restablecimiento

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

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 apps

Usa una biblioteca compatible con FIDO en el servidor de apps 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 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 claves públicas que envió el servidor, crea una clave de restablecimiento. Para ello, incluye estas opciones en un CreateRestoreCredentialRequest y llama al createCredential() con el 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: Las opciones de creación de credenciales que envió el servidor de apps 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.
Precaución: Se recomienda configurar isCloudBackupEnabled como true. Si la copia de seguridad en la nube está inhabilitada y el usuario restablece la copia de seguridad en la nube, la llamada para recuperar la clave de restablecimiento falla. Los usuarios que restablecen tu app con una copia de seguridad en la nube no reciben la clave de restablecimiento y no acceden automáticamente.

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 entidad emisora. 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 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.
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 apps

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.

Puedes recuperar la clave de restablecimiento en las siguientes situaciones:

(Recomendado) Inmediatamente después de que se restablezcan los datos de la app. Usa BackupAgent para configurar la copia de seguridad de tu app y completar la getCredential funcionalidad dentro de la onRestore devolución de llamada 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 dentro de la devolución de llamada onRestore de BackupAgent. Esto 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)

Las APIs del administrador de credenciales muestran una respuesta de tipo GetCredentialResponse. Esta respuesta contiene la clave pública.

Envía la clave pública de la app al servidor de entidad emisora, que 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 el acceso 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 un intento de borrar la clave de restablecimiento correspondiente de ese dispositivo, de manera similar al intento 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)