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" du Gestionnaire d'identifiants fonctionne sur les appareils exécutant Android 9 ou version ultérieure, les services Google Play (GMS) Core version 24220000 ou ultérieure, et la version 1.5.0 ou ultérieure de la bibliothèque androidx.credentials.

Prérequis

Configurez un serveur de partie de confiance semblable au serveur pour les clés d’accès. Si vous disposez déjà d'un serveur configuré 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 restauration.

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-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"
}

La fonctionnalité "Restaurer les identifiants" est disponible à partir de la version 1.5.0 de la bibliothèque androidx.credentials. Toutefois, il est recommandé d'utiliser les dernières versions stables des dépendances lorsque cela est possible.

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

Créez la clé de restauration une fois que l'utilisateur s'est authentifié auprès de 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 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 :

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 défini sur 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.
  • 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é "Restaurer les 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.

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 implémentez la fonctionnalité getCredential dans le rappel onRestore afin de vous assurer que les identifiants de l'application sont restaurés immédiatement après les données de l'application restaurées. 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 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)

Les API du Gestionnaire d'identifiants renvoient une réponse de type GetCredentialResponse. Cette réponse 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 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é par programmation 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)