Choisir la bonne implémentation de clé d'accès pour votre application Android

Les clés d'accès sont devenues la norme pour une authentification sécurisée et conviviale, et un nombre croissant de services les adoptent sur les sites Web et les applications Android. Toutefois, lorsque vous commencez à ajouter des clés d'accès à une application Android, vous êtes souvent confronté à une question d'architecture clé : devez-vous appeler directement les API natives, ouvrir votre page de connexion Web existante dans un onglet de navigateur ou exécuter des clés d'accès dans une WebView intégrée à l'application ?

Présentation

Vous pouvez prendre en charge les clés d'accès dans les applications Android de trois manières différentes : Credential Manager, Auth Tab et WebView. La documentation officielle décrit en détail la procédure d'implémentation de chaque option. Pour choisir une architecture qui minimise les frictions pour les utilisateurs tout en maintenant les coûts de développement et de maintenance à un niveau gérable, il faut comprendre les caractéristiques et les contraintes de chaque option à un niveau élevé. Ce guide explique comment choisir la bonne approche en fonction de la conception de votre application et de l'infrastructure d'authentification existante. Le tableau suivant compare ces approches :

Fonctionnalité Gestionnaire d'identifiants Onglet "Authentification" WebView
Cas d'utilisation recommandé Applications avec une UI de connexion native Réutiliser une page de connexion Web existante, ou un fournisseur d'identité (IdP) OAuth ou OpenID Connect (OIDC) Applications WebView hybrides existantes (domaine propriétaire uniquement)
UI et expérience utilisateur Intégration de la bottom sheet de l'OS natif et de la saisie automatique au clavier Onglet de navigateur dédié et minimal pour l'authentification Page Web intégrée avec bottom sheet de l'OS natif
Saisie automatique et UI conditionnelle Compatible (saisie automatique de Credential Manager) Compatible (UI conditionnelle WebAuthn) Non compatible
Partage de session et d'identifiants Partage les clés d'accès sur le Web et dans l'application à l'aide de assetlinks.json et de rpId partagé (les cookies Chrome ne sont pas partagés) Partage les cookies et l'état des identifiants avec Chrome (peut être désactivé à l'aide de la navigation éphémère) Partage les clés d'accès à l'aide de assetlinks.json, mais isole les cookies et les sessions de Chrome
Digital Asset Links (assetlinks.json) Obligatoire sur le domaine Web de la partie de confiance Obligatoire sur le domaine de votre URI de redirection pour les redirections HTTPS (recommandé par rapport aux schémas personnalisés, qui ne l'exigent pas) Obligatoire sur le domaine Web de la partie de confiance (ne peut pas être utilisé avec des IdP externes ou tiers)

Gestionnaire d'identifiants

Si votre application Android comporte des écrans de connexion ou d'inscription natifs, nous vous recommandons d'utiliser la bibliothèque Jetpack Credential Manager.

Le principal avantage du Gestionnaire d'identifiants est qu'il unifie les clés d'accès, les mots de passe et la fonctionnalité Se connecter avec Google dans une seule bottom sheet système simplifiée. Lorsqu'un utilisateur se connecte, il effectue une authentification biométrique d'un simple geste sans quitter votre application, ce qui réduit les frictions lors de la connexion. Même si un utilisateur ferme la bottom sheet initiale et appuie sur un champ de saisie de nom d'utilisateur ou de mot de passe, vous pouvez utiliser PendingGetCredentialRequest pour afficher les clés d'accès, les mots de passe et l'option "Se connecter avec Google" directement dans le clavier ou dans les suggestions de saisie automatique du menu déroulant. Cette solution de remplacement fournit une intégration de saisie automatique native équivalente à l'UI conditionnelle WebAuthn.

Bottom sheet du gestionnaire d'identifiants montrant les options de clé d'accès, de connexion avec Google et de mot de passe.
Figure 1. Le Gestionnaire d'identifiants unifie les clés d'accès, Se connecter avec Google et les mots de passe dans une bottom sheet du système.

Credential Manager offre également une parité complète des fonctionnalités avec les capacités modernes de cycle de vie des clés d'accès Web. Le Gestionnaire d'identifiants vous permet d'effectuer les opérations suivantes :

Les clés d'accès sont compatibles avec les appareils équipés d'Android 9 (niveau d'API 28) ou version ultérieure, tandis que les autres identifiants, tels que les mots de passe, restent compatibles avec les versions antérieures d'Android via les services Google Play. Sur Android 14 (niveau d'API 34) ou version ultérieure, le Gestionnaire d'identifiants fonctionne également avec n'importe quel fournisseur d'identifiants tiers sélectionné par l'utilisateur. Les fonctionnalités supplémentaires, telles que l'intégration de la saisie automatique basée sur View (PendingGetCredentialRequest) et l'API Signal, nécessitent Android 15 (niveau d'API 35) ou version ultérieure.

Partager des identifiants entre le Web et l'application

Pour commencer, suivez les conditions préalables pour héberger un fichier Digital Asset Links (assetlinks.json) sur votre domaine Web afin d'associer votre site Web et votre application Android. L'association de votre site Web et de votre application via assetlinks.json signifie qu'ils partagent le même ID de tiers de confiance (rpId). Ainsi, les clés d'accès créées sur votre site Web dans Chrome fonctionnent dans votre application Android native via le Gestionnaire d'identifiants, et les clés d'accès créées dans votre application fonctionnent sur votre site Web. Credential Manager partage les identifiants entre votre site Web et votre application. Vous n'avez besoin de l'onglet d'authentification que lorsque vous souhaitez réutiliser l'UI de connexion Web ou la page de l'IdP.

Comme décrit dans Créer une clé d'accès, vous devez également configurer votre serveur pour qu'il vérifie les origines de l'application Android (android:apk-key-hash:ENCODED_SHA256_HASH, au format hachage SHA-256 encodé en Base64URL sans remplissage de votre certificat de signature d'APK). Si votre application dispose d'une UI native et que vous souhaitez une expérience intégrée à l'OS pour vous connecter avec des clés d'accès, choisissez Credential Manager.

Onglet "Authentification"

De nombreux services exploitent un microservice de fournisseur d'identité (IdP) basé sur OAuth ou OpenID Connect (OIDC), ou souhaitent réutiliser une page de connexion Web existante compatible avec les clés d'accès dans les applications mobiles. Auparavant, les applications utilisaient des onglets personnalisés pour ces flux. À partir de Chrome 137 et d'AndroidX Browser 1.9.0, l'onglet d'authentification fournit un onglet de navigateur dédié spécialement conçu pour les flux d'authentification.

Onglet d'authentification affichant une interface de connexion de navigateur minimale sans éléments de menu de navigateur à usage général.
Figure 2. L'onglet d'authentification présente une interface de navigateur ciblée et adaptée aux flux d'authentification.

Les onglets personnalisés standards sont conçus comme des navigateurs intégrés dans l'application à usage général. Ils affichent des éléments d'interface utilisateur sans rapport avec la procédure de connexion, tels que le menu de partage, les favoris et Ouvrir dans Chrome, qui peuvent distraire les utilisateurs. Ils nécessitent également de déclarer des filtres d'intent dans votre fichier manifeste pour recevoir les redirections post-authentification, d'ajouter du code récurrent et de mettre en place des mesures de protection contre l'interception d'intents par des applications malveillantes.

L'onglet d'authentification résout ces problèmes spécifiques à l'authentification. Elle supprime les éléments d'interface utilisateur du navigateur inutiles, tels que le bouton de réduction et le menu de partage, et présente une interface ciblée ne contenant que les fonctionnalités de connexion essentielles, y compris la saisie automatique des clés d'accès et des mots de passe. Au lieu de passer par des intents d'OS, l'onglet d'authentification transmet les redirections d'authentification directement à un rappel intégré à l'application à l'aide d'un schéma personnalisé ou d'une URL HTTPS validée avec Digital Asset Links. Cela renforce la sécurité et réduit le code récurrent d'implémentation.

Partage de session et solution de secours pour les onglets personnalisés

Par défaut, l'onglet d'authentification partage également les cookies et l'état des identifiants directement avec le navigateur Chrome du système. Ce partage permet à votre application de profiter des sessions de connexion actives dans Chrome et d'exécuter votre implémentation WebAuthn existante telle quelle, y compris l'UI conditionnelle et le mode UI immédiat (l'équivalent Web de preferImmediatelyAvailableCredentials de Credential Manager). À l'inverse, si votre cas d'utilisation nécessite une session d'authentification isolée qui ne partage pas les cookies ni l'historique de navigation avec le navigateur, vous pouvez activer la navigation éphémère en appelant AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true).

Bien que vous regroupiez androidx.browser:browser (version 1.9.0 ou ultérieure) avec votre application, l'exécution de l'onglet d'authentification dépend du navigateur par défaut de l'utilisateur. Si le navigateur par défaut est une version de Chrome antérieure à la version 137 ou un navigateur tiers non compatible avec l'onglet d'authentification, l'onglet d'authentification lance automatiquement un onglet personnalisé standard. Lorsque ce remplacement se produit, la redirection post-authentification est renvoyée via un filtre d'intent dans AndroidManifest.xml, comme dans les onglets personnalisés standards, plutôt que via le rappel de l'onglet d'authentification (ActivityResultCallback). En production, Google recommande de vérifier au préalable la compatibilité du navigateur par défaut à l'aide de CustomTabsClient.isAuthTabSupported(context, provider) pour brancher votre flux ou de conserver le filtre d'intent du fichier manifeste afin que votre application puisse gérer les résultats de l'un ou l'autre chemin. Pour obtenir des exemples concrets d'implémentation de remplacement, consultez Android Browser Helper.

Exigences de sécurité OAuth et OIDC

L'onglet d'authentification sécurise et simplifie uniquement le canal de redirection côté client du navigateur vers votre application. Il ne sécurise pas automatiquement le protocole OAuth ou OIDC lui-même. En particulier, compte tenu du comportement de remplacement des onglets personnalisés, vous devez suivre la spécification OAuth 2.0 pour les applications natives (RFC 8252). Plus précisément, combinez PKCE (clé de vérification pour l'échange de code, RFC 7636) à l'aide des paramètres code_challenge et code_verifier pour empêcher l'interception du code d'autorisation, la validation du paramètre state pour empêcher les attaques de falsification de requêtes intersites (CSRF) et de fixation de session, ainsi que la génération et la validation du paramètre nonce dans OpenID Connect pour empêcher les attaques par relecture de jeton d'ID. Une fois ces protections en place, Google recommande de migrer les architectures de connexion Web des onglets personnalisés standards vers l'onglet d'authentification.

WebView

Certaines applications sont basées sur une architecture WebView hybride, où il n'est pas pratique de séparer l'écran de connexion dans une UI native (Gestionnaire d'identifiants) ou un onglet de navigateur (onglet d'authentification). Dans ce cas, vous pouvez activer la compatibilité avec WebAuthn directement dans WebView.

Pour utiliser des clés d'accès dans WebView, ajoutez la bibliothèque AndroidX WebKit (androidx.webkit:webkit version 1.12.0 ou ultérieure) et les dépendances de Credential Manager (androidx.credentials:credentials et androidx.credentials:credentials-play-services-auth) à votre fichier build.gradle. Ensuite, vérifiez la compatibilité des fonctionnalités à l'aide de WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) et activez explicitement la compatibilité avec WebAuthn en appelant WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP). Cette configuration relie automatiquement les demandes de création et d'authentification de clés d'accès des pages Web de WebView au Credential Manager.

Contraintes de domaine et d'expérience utilisateur

Comme pour les intégrations natives de Credential Manager, vous devez suivre les conditions préalables pour héberger un fichier Digital Asset Links (assetlinks.json) sur le domaine Web de votre tiers de confiance afin d'associer votre application. Votre serveur reçoit android:apk-key-hash:ENCODED_SHA256_HASH (le hachage du certificat SHA-256 encodé en Base64URL) comme origine. Comme cette approche nécessite d'héberger assetlinks.json sur le domaine de la partie de confiance pour approuver le certificat de signature de votre application Android, elle ne fonctionne que lorsque vous contrôlez le domaine Web de la partie de confiance (connexion Web propriétaire). Si votre flux d'authentification redirige vers un IdP externe ou tiers sur lequel vous ne pouvez pas héberger assetlinks.json pour votre package d'application, vous devez utiliser l'onglet d'authentification (ou la connexion native avec Google via Credential Manager) au lieu de WebView.

Tenez compte de deux contraintes d'expérience utilisateur et fonctionnelles : WebView n'est pas compatible avec l'UI conditionnelle (intégration de la saisie automatique mediation: "conditional" lorsqu'un utilisateur sélectionne un champ de saisie) et ne partage pas les cookies ni les sessions de connexion avec le navigateur Chrome du système. En raison de ces contraintes, Google recommande d'utiliser Credential Manager ou l'onglet d'authentification lors de la conception de nouveaux flux d'authentification. Toutefois, si vous souhaitez ajouter la compatibilité avec les clés d'accès à une application hybride propriétaire existante sans modifier l'architecture de manière significative, vous pouvez intégrer les clés d'accès à WebView.

Résumé

En partant de l'interface utilisateur et de l'infrastructure d'authentification actuelles de votre application, vous pouvez choisir l'approche de clé d'accès appropriée :

  • Si votre application dispose d'une UI de connexion native et que vous souhaitez une expérience intégrée à l'OS sans passer à un écran de navigateur, choisissez Credential Manager pour vous connecter avec une clé d'accès.
  • Si vous exploitez un microservice IdP OAuth ou OIDC, que vous redirigez vers un IdP externe ou que vous souhaitez réutiliser votre page de connexion Web existante compatible avec les clés d'accès (y compris l'UI conditionnelle) et partager des sessions de navigateur actives avec Chrome, adoptez l'onglet d'authentification et implémentez les exigences de sécurité de OAuth 2.0 pour les applications natives (RFC 8252), en particulier PKCE, state et nonce.
  • Si votre application est basée sur une architecture WebView hybride dans laquelle la connexion doit rester dans des écrans Web propriétaires intégrés, utilisez WebView tout en tenant compte de l'absence de compatibilité avec l'UI conditionnelle et les cookies isolés.

Étapes suivantes