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 (niveau d'API 28) ou version ultérieure, des services Google Play (GMS) version 24220000 ou ultérieure, et de la version 1.5.0 ou ultérieure de la bibliothèque androidx.credentials.

Prérequis

Configurez un serveur de tiers de confiance semblable à celui des 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.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"
}

Restauration d'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

  1. 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éez 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.
  2. 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.
  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 (comme dans la méthode onCreate pour le Activity principal).
  • Lorsque l'utilisateur se connecte ou suit le processus d'enregistrement d'un nouveau 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'identifiant 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 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 des identifiants de restauration, comme 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 récupération en encapsulant ces options dans un objet CreateRestoreCredentialRequest et en appelant la méthode createCredential() 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.

    • 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 la sauvegarde des 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é 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.

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 de la 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.
    Pour vous assurer que les identifiants de restauration sont créés dans tous les cas, vous devez gérer explicitement E2eeUnavailableException en appelant createCredential avec isCloudBackupEnabled défini sur true. Si E2eeUnavailableException est généré, capturez-le et appelez à nouveau createCredential avec isCloudBackupEnabled défini sur false.
  • 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 de WebAuthn.

Se connecter avec une clé de restauration

Utilisez Restauration d'identifiants pour connecter l'utilisateur en arrière-plan 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.

Nous vous recommandons de récupérer la clé de restauration dans les deux cas suivants :

  • Lors du premier lancement de l'application sur l'appareil. La restauration des identifiants dans ce scénario est indépendante de la restauration des données de l'application.
  • Si la sauvegarde et la restauration des données d'application sont activées, récupérez la clé de restauration immédiatement après la restauration des données d'application. Utilisez BackupAgent pour configurer la sauvegarde de votre application et assurez-vous d'implémenter la fonctionnalité getCredential dans le rappel onRestoreFinished. N'utilisez pas la méthode onRestore, car elle n'est appelée que pour les sauvegardes clé-valeur, tandis que onRestoreFinished est appelée 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.

Si vous créez un BackupAgent et que vous aviez précédemment activé la sauvegarde avec allowBackup="true", définissez la valeur booléenne android:fullBackupOnly="true" dans le fichier manifeste de votre application. Cela garantit que le comportement de sauvegarde et de restauration de votre application est conservé.

// 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 la partie de confiance, qui peut ensuite être utilisé pour connecter l'utilisateur. Côté 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)

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