Implémenter la restauration des identifiants avec Credential Manager

Cette page explique comment créer, utiliser et supprimer une clé de restauration.

Compatibilité des versions

La fonctionnalité Restaurer les identifiants de Credential Manager fonctionne sur les appareils équipés d'Android 9 ou version ultérieure, des services Google Play (GMS) version 24220000 ou ultérieure, et de la bibliothèque androidx.credentials version 1.5.0 ou ultérieure.

Prérequis

Configurez un serveur de tiers de confiance semblable au serveur pour les clés d'accès. Si vous avez déjà configuré un serveur pour gérer l'authentification avec des clés d'accès, utilisez la même implémentation côté serveur pour les clés de récupération.

Dépendances

Ajoutez les dépendances suivantes au fichier build.gradle du module de votre application :

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 fonctionnalité Restaurer les identifiants est disponible à partir de la version 1.5.0 de la bibliothèque androidx.credentials. Toutefois, nous vous recommandons d'utiliser les dernières versions stables des dépendances dans la mesure du possible.

Présentation

Créer une clé de restauration : pour créer une clé de restauration, procédez comme suit :
1. Instanciez Credential Manager : créez un objet CredentialManager.
2. Obtenez les options de création d'identifiants à partir du serveur d'application : envoyez à l'application cliente les informations nécessaires pour créer la clé de restauration à partir de votre serveur d'application.
3. Créer la clé de restauration : créez une clé de restauration pour le compte de l'utilisateur s'il est connecté à votre application.
4. Gérer la réponse de création des identifiants : envoyez les identifiants de votre application cliente à votre serveur d'application pour traitement et gérez les éventuelles exceptions.
Se connecter avec une clé de récupération : pour vous connecter avec une clé de récupération, procédez comme suit :
1. Obtenez les options de récupération des identifiants à partir du serveur d'application : envoyez à l'application cliente les informations nécessaires pour récupérer la clé de restauration à partir de votre serveur d'application.
2. Obtenir la clé de restauration : demandez la clé de restauration au Gestionnaire d'identifiants lorsque l'utilisateur configure un nouvel appareil. L'utilisateur peut ainsi se connecter sans saisie supplémentaire.
3. Gérer la réponse de récupération des identifiants : envoyez la clé de restauration de l'application cliente au serveur d'application pour connecter l'utilisateur.
Supprimer une clé de restauration

Créer une clé de restauration

Créez la clé de restauration après l'authentification de l'utilisateur dans votre application, immédiatement après la connexion ou lors d'un lancement ultérieur de l'application s'il est déjà connecté.

Instancier le Gestionnaire d'identifiants

Utilisez le contexte d'activité de votre application pour instancier un objet CredentialManager.

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

Obtenir les options de création d'identifiants à partir du serveur de votre application

Utilisez une bibliothèque conforme à FIDO sur le serveur de votre application pour envoyer à votre application cliente les informations nécessaires à la création de l'identifiant de restauration, telles que des informations sur l'utilisateur, l'application et des propriétés de configuration supplémentaires. Pour en savoir plus sur l'implémentation côté serveur, consultez les conseils côté serveur.

Créer la clé de restauration

Après avoir analysé les options de création de clé publique envoyées par le serveur, créez une clé de restauration en encapsulant ces options dans un objet CreateRestoreCredentialRequest et en appelant la méthode createCredential() avec l'objet 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)

Points clés concernant le code

L'objet CreateRestoreCredentialRequest contient les champs suivants :
- requestJson : options de création d'identifiants envoyées par le serveur d'application au format Web Authentication API pour PublicKeyCredentialCreationOptionsJSON.
- Champ isCloudBackupEnabled : Boolean pour déterminer si la clé de restauration doit être sauvegardée dans le cloud. Par défaut, cette option est définie sur true. Ce champ accepte les valeurs suivantes :
  - true : (recommandé) cette valeur permet de sauvegarder les clés de restauration dans le cloud si l'utilisateur a activé la sauvegarde Google et le chiffrement de bout en bout, comme le verrouillage de l'écran.
  - false : cette valeur enregistre la clé en local et non dans le cloud. La clé n'est pas disponible sur le nouvel appareil si l'utilisateur choisit de restaurer les données à partir du cloud.
Attention : Nous vous recommandons de définir isCloudBackupEnabled sur true. Si la sauvegarde dans le cloud est désactivée et que l'utilisateur restaure à partir d'une sauvegarde dans le cloud, l'appel pour récupérer la clé de restauration échoue. Les utilisateurs qui restaurent votre application à l'aide d'une sauvegarde cloud ne reçoivent pas la clé de restauration et ne sont pas automatiquement connectés.

Gérer la réponse de création d'identifiants

L'API Credential Manager renvoie une réponse de type CreateRestoreCredentialResponse. Cette réponse contient la réponse à l'enregistrement des identifiants de clé publique au format JSON.

Envoyez la clé publique de votre application au serveur de la partie de confiance. Cette clé publique est semblable à celle générée lorsque vous créez une clé d'accès. Le même code qui gère la création de clés d'accès sur le serveur peut également gérer la création de clés de récupération. Pour en savoir plus sur l'implémentation côté serveur, consultez les conseils concernant les clés d'accès.

Lors du processus de création de la clé de restauration, gérez ces exceptions :

CreateRestoreCredentialDomException : cette exception se produit si requestJson n'est pas valide et ne respecte pas le format WebAuthn pour PublicKeyCredentialCreationOptionsJSON.
E2eeUnavailableException : cette exception se produit si isCloudBackupEnabled est défini sur true, mais que l'appareil de l'utilisateur ne dispose pas de la sauvegarde des données ni du chiffrement de bout en bout, comme un verrouillage d'écran.
IllegalArgumentException : cette exception se produit si createRestoreRequest est vide ou n'est pas un code JSON valide, ou s'il ne comporte pas de user.id valide conforme aux spécifications WebAuthn.

Se connecter avec une clé de restauration

Utilisez "Restore Credentials" (Restaurer les identifiants) pour connecter l'utilisateur en mode silencieux lors de la configuration de l'appareil.

Obtenir les options de récupération des identifiants à partir du serveur d'application

Envoyez à l'application cliente les options requises pour obtenir la clé de restauration du serveur. Pour obtenir des conseils similaires sur les clés d'accès pour cette étape, consultez Se connecter avec une clé d'accès. Pour en savoir plus sur l'implémentation côté serveur, consultez le guide d'authentification côté serveur.

Obtenir la clé de restauration

Pour obtenir la clé de restauration sur le nouvel appareil, appelez la méthode getCredential() sur l'objet CredentialManager.

Vous pouvez récupérer la clé de restauration dans les cas suivants :

(Recommandé) Immédiatement après la restauration des données de l'application. Utilisez BackupAgent pour configurer la sauvegarde de votre application et compléter la fonctionnalité getCredential dans le rappel onRestore afin de vous assurer que les identifiants de l'application sont restaurés immédiatement après la restauration des données de l'application. Cela évite les retards potentiels lorsque les utilisateurs ouvrent leur nouvel appareil pour la première fois et leur permet d'interagir sans attendre qu'ils ouvrent votre application.
Lors du premier lancement de l'application sur l'appareil.

Pour envoyer des notifications à un utilisateur avant qu'il n'ouvre l'application pour la première fois sur un nouvel appareil, récupérez la clé de restauration dans le rappel onRestore de BackupAgent. Cela est particulièrement important pour les applications de messagerie ou de communication.

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

Les API du gestionnaire d'identifiants renvoient une réponse de type GetCredentialResponse. Cette réponse contient la clé publique.

Envoyez la clé publique de l'application au serveur de la partie de confiance, qui peut ensuite être utilisé pour connecter l'utilisateur. Du côté du serveur, cette action est semblable à une connexion à l'aide d'une clé d'accès. Le même code qui gère la connexion avec des clés d'accès sur le serveur peut également gérer les connexions avec des clés de récupération. Pour en savoir plus sur l'implémentation côté serveur des clés d'accès, consultez Se connecter avec une clé d'accès.

Supprimer la clé de restauration

Le Gestionnaire d'identifiants est sans état et ne tient pas compte de l'activité de l'utilisateur. Il ne supprime donc pas automatiquement les clés de restauration après utilisation. Pour supprimer une clé de restauration, appelez la méthode clearCredentialState(). Pour des raisons de sécurité, supprimez la clé chaque fois qu'un utilisateur se déconnecte. Ainsi, la prochaine fois que l'utilisateur ouvrira l'application sur le même appareil, il sera déconnecté et invité à se reconnecter.

La désinstallation d'une application est interprétée comme une intention de supprimer la clé de restauration correspondante de cet appareil, de la même manière que l'intention de l'utilisateur lorsqu'il se déconnecte.

Les clés de restauration ne sont supprimées que dans les cas suivants :

Actions au niveau du système : les utilisateurs désinstallent l'application ou effacent ses données.
Appels au niveau de l'application : supprimez la clé de manière programmatique en appelant clearCredentialState() lorsque vous gérez la déconnexion de l'utilisateur dans le code de votre application.

Lorsque l'utilisateur se déconnecte de votre application, appelez la méthode clearCredentialState() sur l'objet 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)