Implémenter la restauration des identifiants avec Credential Manager

Présentation

1. Créer une clé de restauration : pour créer une clé de restauration, procédez comme suit :
   1. Instancier le Gestionnaire d'identifiants : créez un CredentialManager objet.
   2. Obtenir les options de création d'identifiants à partir du serveur d'application : envoyez à l' application cliente les informations requises 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 d'identifiants : envoyez les identifiants de votre application cliente à votre serveur d'application pour traitement, et gérez toutes les exceptions.
2. Se connecter avec une clé de restauration : pour vous connecter avec une clé de restauration, procédez comme suit :
   1. Obtenir les options de récupération d'identifiants à partir du serveur d'application : envoyez à l' application cliente les informations requises 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. Cela permet à l'utilisateur de se connecter sans saisie supplémentaire.
   3. Gérer la réponse de récupération d'identifiants : envoyez la clé de restauration de l'application cliente au serveur d'application pour connecter l'utilisateur.
3. Supprimer une clé de restauration.

Créer une clé de restauration

Votre application doit couvrir tous les cas de connexion d'un utilisateur pour s'assurer que les utilisateurs actifs disposent d'une clé de restauration. Créez la clé de restauration dans les scénarios suivants :

• Si l'utilisateur est connecté et qu'une clé de restauration n'a pas encore été créée (par exemple, dans la méthode onCreate de l'Activity principale).
• Lorsque l'utilisateur se connecte ou termine un nouveau flux d'enregistrement de compte.

Pour optimiser les performances et éviter la surcharge liée à la création ou à la vérification d'un identifiant de restauration à chaque connexion, définissez un indicateur boolean ou un code temporel de création d'identifiants dans le stockage local, tel que has_synced_restore_credential, pour savoir si la clé a déjà été créée.

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 de votre serveur d'application

Utilisez une bibliothèque compatible avec FIDO sur votre serveur d'application pour envoyer à votre application cliente les informations requises pour créer 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 CreateRestoreCredentialRequest objet et en appelant la createCredential() méthode avec l'objet CredentialManager.

// createRestoreRequest contains the details sent by the server 
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 de l'API Web Authentication pour PublicKeyCredentialCreationOptionsJSON.

  • isCloudBackupEnabled: champ Boolean permettant de déterminer si la clé de restauration doit être sauvegardée dans le cloud. Par défaut, cet indicateur est true. Ce champ comporte 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 un verrouillage de l'écran.
    • false : cette valeur enregistre la clé localement et non dans le cloud. La clé n'est pas disponible sur le nouvel appareil si l'utilisateur choisit de restaurer à partir du cloud.

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 d'enregistrement des identifiants de clé publique au format JSON.

Envoyez la clé publique de votre application au serveur de 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 restauration. Pour en savoir plus sur l'implémentation côté serveur, consultez the conseils concernant les clés d'accès.

Lors du processus de création de clé de restauration, gérez les exceptions suivantes :

• CreateRestoreCredentialDomException : cette exception se produit si requestJson n'est pas valide et ne suit pas le format WebAuthn pour PublicKeyCredentialCreationOptionsJSON.
• E2eeUnavailableException: cette exception se produit si isCloudBackupEnabled est true, mais que l'appareil de l'utilisateur ne dispose pas de sauvegarde des données ni de chiffrement de bout en bout, comme un verrouillage de l'écran.
  Pour vous assurer que les identifiants de restauration sont créés dans tous les cas, vous devez gérer explicitement l'exception E2eeUnavailableException en appelant createCredential avec isCloudBackupEnabled défini sur true. Si l'exception E2eeUnavailableException est générée, interceptez-la et appelez à nouveau createCredential avec isCloudBackupEnabled défini sur false.
• IllegalArgumentException : cette exception se produit si createRestoreRequest est vide ou n'est pas un JSON valide, ou s'il ne comporte pas de user.id valide qui est conforme aux spécifications WebAuthn.

Se connecter avec une clé de restauration

Utilisez la fonctionnalité de restauration des identifiants pour connecter l'utilisateur en mode silencieux lors du processus de configuration de l'appareil.

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

Envoyez à l'application cliente les options requises pour obtenir la clé de restauration à partir du serveur. Pour obtenir des conseils similaires concernant 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.

Il est recommandé de récupérer la clé de restauration dans les deux scénarios suivants :

• Lors du premier lancement de l'application sur l'appareil. Dans ce scénario, la restauration des identifiants est indépendante de la restauration des données de l'application.
• Si la sauvegarde et la restauration des données de l'application sont activées, récupérez la clé de restauration immédiatement après la restauration des données de l'application. Utilisez BackupAgent pour configurer la sauvegarde de votre application et assurez-vous d'exécuter la fonctionnalité getCredential dans le rappel onRestoreFinished. N'utilisez pas la onRestore méthode, car elle n'est appelée que pour les sauvegardes de paires clé-valeur, tandis que onRestoreFinished est appelé de manière fiable pour tout type de restauration de sauvegarde. Cela évite les retards potentiels lorsque les utilisateurs ouvrent leur nouvel appareil pour la première fois et leur permet d'interagir avec l'application sans attendre qu'ils l'ouvrent. Par exemple, cela permet à votre application d'envoyer des notifications à l'utilisateur avant qu'il n'ouvre l'application pour la première fois sur le nouvel appareil, ce qui est particulièrement pertinent pour les applications de messagerie ou de communication.

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

Les API du Gestionnaire d'identifiants renvoient une réponse de type GetCredentialResponse. L'identifiant contenu dans cette réponse est explicitement de type RestoreCredential, qui contient la clé publique.

Gérer la réponse de connexion

Envoyez la clé publique de l'application au serveur de partie de confiance, qui peut ensuite être utilisé pour connecter l'utilisateur. Côté serveur, cette action est semblable à la 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 restauration. Pour en savoir plus sur l'implémentation côté serveur pour les 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, semblable à l'intention de l'utilisateur lorsqu'il se déconnecte.

Les clés de restauration ne sont supprimées que dans les situations suivantes :

• 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é par programmation en appelant clearCredentialState() lors de la gestion de 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)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)