Migrer depuis Google Sign-In

Ce guide vous explique les changements nécessaires et la marche à suivre pour migrer les bibliothèques JavaScript de l'ancienne bibliothèque de plate-forme Google Sign-In vers la nouvelle bibliothèque Google Identity Services pour l'authentification.

Si votre client utilise la bibliothèque cliente des API Google pour JavaScript ou d'autres bibliothèques antérieures pour l'autorisation, consultez Migrer vers Google Identity Services pour en savoir plus.

Authentification et autorisation

L'authentification établit qui est une personne et est communément appelée "inscription ou connexion des utilisateurs". L'autorisation est le processus qui consiste à accorder ou à refuser l'accès à des données ou à des ressources. Par exemple, votre application demande à l'utilisateur son autorisation pour accéder à Google Drive.

Comme la précédente bibliothèque de plate-forme Google Sign-In, la nouvelle bibliothèque Google Identity Services est conçue pour prendre en charge à la fois les processus d'authentification et d'autorisation.

Toutefois, la bibliothèque plus récente sépare les deux processus pour réduire la complexité de l'intégration des comptes Google à votre application.

Si votre cas d'utilisation ne concerne que l'authentification, poursuivez la lecture de cette page.

Si votre cas d'utilisation inclut une autorisation, consultez Fonctionnement de l'autorisation des utilisateurs et Migrer vers Google Identity Services pour vous assurer que votre application utilise les nouvelles API améliorées.

Modifications apportées

Pour les utilisateurs, la nouvelle bibliothèque Google Identity Services offre de nombreuses améliorations de l'usabilité. Voici quelques-uns des points forts:

• Nouveaux flux de connexion automatique et One Tap à faible friction, avec moins d'étapes individuelles
• un nouveau bouton de connexion avec personnalisation utilisateur,
• un branding cohérent et un comportement de connexion uniforme sur le Web améliorent la compréhension et la confiance ;
• accéder rapidement au contenu : les utilisateurs peuvent s'inscrire et se connecter directement depuis n'importe quelle page de votre site, sans avoir à accéder à une page de connexion ou de compte au préalable.

Pour les développeurs, nous avons mis l'accent sur la réduction de la complexité, l'amélioration de la sécurité et une intégration aussi rapide que possible. Voici quelques-unes de ces améliorations:

• L'option permettant d'ajouter la connexion des utilisateurs au contenu statique de votre site à l'aide du code HTML uniquement
• la séparation entre l'authentification de connexion, l'autorisation et le partage des données utilisateur, l'intégration OAuth 2.0 n'est plus nécessaire pour connecter les utilisateurs à votre site,
• Les modes pop-up et redirection sont toujours acceptés, mais l'infrastructure OAuth 2.0 de Google redirige désormais vers le point de terminaison de connexion de votre serveur backend.
• consolidation des fonctionnalités des anciennes bibliothèques JavaScript Google Identity et Google API en une seule bibliothèque,
• pour les réponses de connexion, vous pouvez maintenant décider d'utiliser ou non une promesse, et l'indirection via les fonctions de style getter a été supprimée par souci de simplicité.

Exemple de migration de connexion

Si vous migrez depuis le bouton de connexion Google existant et que vous ne souhaitez connecter les utilisateurs que sur votre site, la modification la plus simple consiste à passer au nouveau bouton personnalisé. Pour ce faire, échangez les bibliothèques JavaScript et mettez à jour votre codebase pour utiliser un nouvel objet de connexion.

Bibliothèques et configuration

L'ancienne bibliothèque de plate-forme Google Sign-In (apis.google.com/js/platform.js) et la bibliothèque cliente des API Google pour JavaScript (gapi.client) ne sont plus nécessaires pour l'authentification et l'autorisation des utilisateurs. Ils ont été remplacés par une seule nouvelle bibliothèque JavaScript Google Identity Services : accounts.google.com/gsi/client.

Les trois modules JavaScript précédents, api, client et platform, utilisés pour la connexion, sont tous chargés à partir de apis.google.com. Pour vous aider à identifier les emplacements où la bibliothèque précédente pourrait être incluse sur votre site, généralement:

• Le bouton de connexion par défaut charge apis.google.com/js/platform.js.
• Un graphique de bouton personnalisé charge apis.google.com/js/api:client.js, et
• L'utilisation directe de gapi.client charge apis.google.com/js/api.js.

Dans la plupart des cas, vous pouvez continuer à utiliser les identifiants de votre ID client d'application Web existant. Dans le cadre de votre migration, nous vous recommandons de consulter nos Règles OAuth 2.0 et d'utiliser la console Google APIs pour vérifier et, si nécessaire, mettre à jour les paramètres client suivants:

• vos applications de test et de production utilisent des projets distincts et disposent de leurs propres ID client ;
• Le type d'ID client OAuth 2.0 est "Application Web".
• HTTPS est utilisé pour les origines JavaScript autorisées et les URI de redirection.

Identifier le code concerné et effectuer un test

Un cookie de débogage peut aider à localiser le code concerné et à tester le comportement après l'abandon.

Dans les applications volumineuses ou complexes, il peut être difficile de trouver tout le code affecté par l'abandon du module gapi.auth2. Pour consigner l'utilisation existante de fonctionnalités bientôt obsolètes dans la console, définissez la valeur du cookie G_AUTH2_MIGRATION sur informational. Vous pouvez également ajouter un deux-points suivi d'une valeur de clé pour enregistrer également les journaux dans le stockage de session. Après la connexion et la réception des identifiants, examinez ou envoyez les journaux collectés à un backend pour une analyse ultérieure. Par exemple, informational:showauth2use enregistre l'origine et l'URL dans une clé de stockage de session nommée showauth2use.

Pour vérifier le comportement de l'application lorsque le module gapi.auth2 n'est plus chargé, définissez la valeur du cookie G_AUTH2_MIGRATION sur enforced. Cela permet de tester le comportement post-abandon avant la date d'application.

Valeurs possibles pour le cookie G_AUTH2_MIGRATION:

• enforced Ne chargez pas le module gapi.auth2.
• informational Enregistre l'utilisation des fonctionnalités obsolètes dans la console JS. Enregistrez également dans le stockage de la session lorsqu'un nom de clé facultatif est défini : informational:key-name.

Pour minimiser l'impact sur l'utilisateur, nous vous recommandons de définir d'abord ce cookie localement lors du développement et du test, avant de l'utiliser dans des environnements de production.

HTML et JavaScript

Dans ce scénario de connexion par authentification uniquement, un exemple de code et les rendus du bouton Google Sign-In existant sont affichés. Sélectionnez le mode "Popup" ou "Redirection" pour voir les différences de traitement de la réponse d'authentification par un rappel JavaScript ou par une redirection sécurisée vers le point de terminaison de connexion de votre serveur backend.

L'ancienne méthode

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Nouvelle méthode

Pour utiliser la nouvelle bibliothèque dans un scénario de connexion par authentification uniquement, sélectionnez le mode Pop-up ou Redirection, et utilisez l'exemple de code pour remplacer votre implémentation existante sur votre page de connexion.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Dans cet exemple d'authentification uniquement, la nouvelle bibliothèque accounts.google.com/gsi/client, la classe g_id_signin et l'objet g_id_onload remplacent la bibliothèque apis.google.com/js/platform.js et l'objet g-signin2 précédents.

En plus d'afficher le nouveau bouton personnalisé, l'exemple de code affiche également le nouveau pop-up One Tap. Partout où vous affichez le bouton personnalisé, nous vous recommandons vivement d'afficher également la fenêtre pop-up One Tap pour réduire les frictions utilisateur lors de l'inscription et de la connexion.

Bien que cela ne soit pas recommandé en raison des difficultés de connexion, le nouveau bouton personnalisé peut s'afficher seul, sans afficher simultanément la boîte de dialogue One Tap. Pour ce faire, définissez l'attribut data-auto_prompt sur false.

API HTML et JavaScript

L'exemple précédent montre comment utiliser la nouvelle API HTML pour ajouter une fonctionnalité de connexion à votre site Web. Vous pouvez également utiliser l'API JavaScript fonctionnellement équivalente ou combiner des API HTML et JavaScript sur votre site.

Pour afficher de manière interactive les options de personnalisation des boutons, telles que le type de rappel et les attributs tels que la couleur, la taille, la forme, le texte et le thème, consultez notre générateur de code. Il permet de comparer rapidement différentes options et de générer des extraits HTML à utiliser sur votre site.

Connectez-vous depuis n'importe quelle page avec One Tap

One Tap est une nouvelle méthode simple d'inscription ou de connexion à votre site pour les utilisateurs. Il vous permet d'activer la connexion des utilisateurs directement depuis n'importe quelle page de votre site, et les utilisateurs n'ont plus besoin d'accéder à une page de connexion dédiée. En d'autres termes, cela réduit les problèmes d'inscription et de connexion en offrant aux utilisateurs la possibilité de s'inscrire et de se connecter à partir d'autres pages que la vôtre.

Pour activer la connexion depuis n'importe quelle page, nous vous recommandons d'inclure g_id_onload dans un en-tête, un pied de page ou un autre objet partagé sur l'ensemble de votre site.

Nous vous recommandons également d'ajouter g_id_signin, qui affiche le bouton de connexion personnalisé, uniquement sur vos pages de connexion ou de gestion des comptes utilisateur. Proposez aux utilisateurs des options d'inscription ou de connexion en affichant le bouton à côté d'autres boutons de fournisseur d'identité fédéré, ainsi que des champs de saisie de nom d'utilisateur et de mot de passe.

Réponse du jeton

La connexion des utilisateurs ne nécessite plus de comprendre ni d'utiliser les codes d'autorisation, les jetons d'accès ou les jetons d'actualisation OAuth 2.0. À la place, un jeton d'identification JSON Web Token (JWT) est utilisé pour partager l'état de connexion et le profil utilisateur. Pour simplifier davantage, vous n'êtes plus obligé d'utiliser des méthodes d'accès de style "getter" pour travailler avec les données de profil utilisateur.

Un jeton d'ID JWT signé par Google sécurisé est renvoyé:

• au gestionnaire de rappel JavaScript basé sur le navigateur de l'utilisateur en mode pop-up ;
• vers votre serveur backend via une redirection Google vers votre point de terminaison de connexion lorsque le bouton Se connecter avec Google ux_mode est défini sur redirect.

Dans les deux cas, mettez à jour vos gestionnaires de rappel existants en supprimant:

• appels à googleUser.getBasicProfile() ;
• références à BasicProfile et appels associés aux méthodes getId(), getName(), getGivenName(), getFamilyName(), getImageUrl() et getEmail() ;
• Utilisation de l'objet AuthResponse

Utilisez plutôt des références directes aux sous-champs credential dans le nouvel objet JWT CredentialResponse pour travailler avec les données de profil utilisateur.

De plus, et pour le mode Redirection uniquement, veillez à empêcher la falsification de requête intersites (CSRF) et à valider le jeton d'ID Google sur votre serveur backend.

Pour mieux comprendre comment les utilisateurs interagissent avec votre site, le champ select_by de CredentialResponse peut être utilisé pour déterminer le résultat du consentement de l'utilisateur et le flux de connexion spécifique utilisé.

Consentement des utilisateurs et révocation d'autorisations

Lorsqu'un utilisateur se connecte pour la première fois à votre site Web, Google lui demande son consentement pour partager son profil de compte avec votre application. Ce n'est qu'après avoir donné son consentement que le profil de l'utilisateur est partagé avec votre application dans une charge utile des identifiants de jeton d'ID. Révoquer l'accès à ce profil équivaut à révoquer un jeton d'accès dans la bibliothèque de connexion précédente.

Les utilisateurs peuvent révoquer les autorisations et dissocier votre application de leur compte Google en accédant à la page https://myaccount.google.com/permissions. Ils peuvent également se déconnecter directement de votre application en déclenchant un appel d'API que vous implémentez. La méthode disconnect précédente a été remplacée par la nouvelle méthode revoke.

Lorsqu'un utilisateur supprime son compte sur votre plate-forme, il est recommandé d'utiliser revoke pour dissocier votre application de son compte Google.

Auparavant, auth2.signOut() pouvait être utilisé pour gérer la déconnexion des utilisateurs de votre application. Toute utilisation de auth2.signOut() doit être supprimée, et votre application doit gérer directement l'état de la session et l'état de connexion par utilisateur.

État de la session et écouteurs

La nouvelle bibliothèque ne conserve pas l'état de connexion ni l'état de la session pour votre application Web.

L'état de connexion d'un compte Google, ainsi que l'état de session et l'état de connexion de votre application sont des concepts distincts.

L'état de connexion de l'utilisateur à son compte Google et à votre application est indépendant l'un de l'autre, sauf au moment de la connexion elle-même, lorsque vous savez que l'utilisateur s'est authentifié et est connecté à son compte Google.

Lorsque Se connecter avec Google, One Tap ou la connexion automatique sont inclus sur votre site, les utilisateurs doivent d'abord se connecter à leur compte Google pour:

• qu'ils autorisent le partage de leur profil utilisateur lors de leur première inscription ou connexion à votre site ;
• et plus tard pour une connexion lors d'une visite ultérieure sur votre site.

Les utilisateurs peuvent rester connectés, se déconnecter ou passer à un autre compte Google tout en conservant une session active et connectée sur votre site Web.

Vous êtes désormais responsable de la gestion directe de l'état de connexion des utilisateurs de votre application Web. Auparavant, Google Sign-In vous aidait à surveiller l'état de la session de l'utilisateur.

Supprimez toutes les références à auth2.attachClickHandler() et à ses gestionnaires de rappel enregistrés.

Auparavant, les écouteurs étaient utilisés pour partager les modifications de l'état de connexion du compte Google d'un utilisateur. Les écouteurs ne sont plus acceptés.

Supprimez toutes les références à listen(), auth2.currentUser et auth2.isSignedIn.

Cookies

Se connecter avec Google utilise des cookies de manière limitée. Vous trouverez ci-dessous une description de ces cookies. Pour en savoir plus sur les autres types de cookies utilisés par Google, consultez Comment Google utilise les cookies.

Le cookie G_ENABLED_IDPS défini par la bibliothèque de plate-forme Google Sign-In précédente n'est plus utilisé.

La nouvelle bibliothèque Google Identity Services peut éventuellement définir ces cookies interdomaines en fonction de vos options de configuration:

• g_state stocke l'état de déconnexion de l'utilisateur et est défini lors de l'utilisation du pop-up One Tap ou de la connexion automatique.

• g_csrf_token est un cookie de double envoi utilisé pour empêcher les attaques CSRF. Il est défini lorsque votre point de terminaison de connexion est appelé. La valeur de l'URI de connexion peut être définie explicitement ou utiliser par défaut l'URI de la page actuelle. Votre point de terminaison de connexion peut être appelé dans les conditions suivantes lorsque vous utilisez:

  • API HTML avec data-ux_mode=redirect ou lorsque data-login_uri est défini, ou

  • L'API JavaScript avec ux_mode=redirect et où google.accounts.id.prompt() n'est pas utilisé pour afficher One Tap ou la connexion automatique.

Si vous disposez d'un service qui gère les cookies, veillez à ajouter les deux nouveaux cookies et à supprimer l'ancien cookie une fois la migration terminée.

Si vous gérez plusieurs domaines ou sous-domaines, consultez Display One Tap sur les sous-domaines pour obtenir des instructions supplémentaires sur l'utilisation du cookie g_state.

Documentation de référence sur la migration des objets pour la connexion des utilisateurs