Migrer depuis Google Sign-In

Ce guide vous explique les modifications nécessaires et les étapes à suivre pour migrer les bibliothèques JavaScript de l'ancienne bibliothèque de plate-forme Google Sign-In vers la bibliothèque Google Identity Services plus récente 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 permet d'identifier une personne. On parle communément d'inscription ou de connexion d'utilisateur. L'autorisation est le processus qui consiste à accorder ou à refuser l'accès aux données ou aux ressources. Par exemple, votre application demande l'autorisation de l'utilisateur pour accéder à son Google Drive.

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

Cependant, la nouvelle bibliothèque sépare les deux processus afin de simplifier l'intégration des comptes Google à votre application pour les développeurs.

Si votre cas d'utilisation concerne uniquement l'authentification, poursuivez votre lecture.

Si votre cas d'utilisation inclut des autorisations, 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 la facilité d'utilisation. Points forts:

  • Nouvelles procédures de connexion simple et automatique avec One Tap et moins d'étapes individuelles,
  • un nouveau bouton de connexion avec la personnalisation de l'utilisateur,
  • une image de marque cohérente et une 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 quel emplacement de votre site, sans avoir à accéder à une page de connexion ou de compte.

Pour les développeurs, notre priorité a été de réduire la complexité, d'améliorer la sécurité et de rendre votre intégration aussi rapide que possible. Voici quelques-unes de ces améliorations:

  • La possibilité d'ajouter une connexion utilisateur au contenu statique de votre site en utilisant uniquement du code HTML,
  • séparation de l'authentification de la connexion de l'autorisation et du partage des données utilisateur, l'intégration d'OAuth 2.0 n'est plus nécessaire pour connecter les utilisateurs à votre site,
  • les modes pop-up et de redirection sont toujours pris en charge, mais l'infrastructure OAuth 2.0 de Google redirige désormais vers le point de terminaison de connexion de votre serveur backend,
  • la consolidation des fonctionnalités des deux anciennes bibliothèques Google Identity et JavaScript de l'API Google en une seule nouvelle 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 pour plus de simplicité.

Exemple de migration de connexion

Si vous effectuez la migration depuis le bouton Google Sign-In existant et que vous souhaitez uniquement connecter les utilisateurs à votre site, le changement le plus simple consiste à passer au nouveau bouton personnalisé. Pour ce faire, vous pouvez permuter les bibliothèques JavaScript et mettre à 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. Elles ont été remplacées 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,
  • une image de bouton personnalisée 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 l'ID client de votre application Web existants. Lors 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 ont leurs propres ID client,
  • le type d'ID client OAuth 2.0 est "Web application" (Application Web) ;
  • HTTPS est utilisé pour les origines JavaScript autorisées et les URI de redirection.

Identifier le code affecté et tester

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

Dans les applications volumineuses ou complexes, il peut être difficile de trouver tout le code concerné par l'abandon du module gapi.auth2. Pour consigner dans la console l'utilisation existante des fonctionnalités qui seront bientôt obsolètes, définissez la valeur du cookie G_AUTH2_MIGRATION sur informational. Vous pouvez également ajouter deux-points, suivi d'une clé-valeur pour consigner également dans le stockage de la 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 après l'abandon avant la date d'application.

Valeurs possibles pour les cookies G_AUTH2_MIGRATION:

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

Pour minimiser l'impact sur les utilisateurs, nous vous recommandons de définir 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 avec authentification uniquement, des exemples de code et d'affichages du bouton Google Sign-In existant sont présentés. Sélectionnez le mode Pop-up ou Redirection pour voir les différences dans la manière dont la réponse d'authentification est gérée, soit par un rappel JavaScript, soit par une redirection sécurisée vers le point de terminaison de connexion de votre serveur backend.

La première méthode

Affichez le bouton Google Sign-In et utilisez un rappel pour gérer la connexion directement à partir du navigateur de l'utilisateur.

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

Mode redirection

Affichez le bouton Google Sign-In, qui se termine par un appel AJAX depuis le navigateur de l'utilisateur vers le point de terminaison de connexion de votre serveur backend.

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

Rendu

Les nouveaux attributs visuels simplifient la méthode précédente de création de boutons personnalisés. Ils éliminent les appels à gapi.signin2.render() et vous n'avez plus besoin d'héberger et de gérer des images et des éléments visuels sur votre site.

Google Sign-In

Connecté à Google

Texte du bouton permettant de mettre à jour l'état de connexion de l'utilisateur.

Nouvelle méthode

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

Utilisez un rappel pour gérer la connexion directement à partir du navigateur de l'utilisateur.

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

Mode redirection

Google appelle votre point de terminaison de connexion comme spécifié par l'attribut data-login_url. Auparavant, vous étiez responsable de l'opération POST et du nom du paramètre. La nouvelle bibliothèque publie le jeton d'ID sur votre point de terminaison dans le paramètre credential. Enfin, vérifiez le jeton d'ID sur votre serveur backend.

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

Rendu

Utilisez les visual-attributes pour personnaliser la taille, la forme et la couleur du bouton "Se connecter avec Google". Affichez le pop-up One Tap et le bouton personnalisé pour améliorer le taux de connexion.

Bouton &quot;Se connecter avec Google&quot; Pop-up One Tap

L'état de connexion de l'utilisateur ne fait pas passer le texte du bouton "Se connecter" à "Connecté". Une fois l'autorisation accordée, ou lors de ses prochaines visites, le bouton personnalisé comprend le nom, l'adresse e-mail et la photo de profil de l'utilisateur.

Dans cet exemple d'authentification uniquement, la nouvelle bibliothèque accounts.google.com/gsi/client, la nouvelle 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. Nous vous recommandons vivement d'afficher également le pop-up One Tap partout où vous affichez le bouton personnalisé afin de limiter les frictions des utilisateurs lors de l'inscription et de la connexion.

Bien que cela ne soit pas recommandé en raison de la friction de connexion, le nouveau bouton personnalisé peut être affiché 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 des informations de connexion à votre site Web. Vous pouvez également utiliser l'API JavaScript fonctionnellement équivalente ou combiner les 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. Vous pouvez l'utiliser pour comparer rapidement différentes options et générer des extraits HTML à utiliser sur votre site.

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

One Tap est un nouveau moyen simple pour les utilisateurs de s'inscrire ou de se connecter à votre site. Elle vous permet de se connecter directement depuis n'importe quelle page de votre site et évite aux utilisateurs d'avoir à accéder à une page de connexion dédiée. Autrement dit, elle permet de simplifier l'inscription et la connexion en offrant aux utilisateurs la possibilité de s'inscrire et de se connecter depuis des pages autres que votre page de connexion.

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 tout autre objet partagé inclus 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. Offrez aux utilisateurs des options d'inscription ou de connexion en affichant le bouton à côté d'autres boutons de fournisseurs d'identité fédérés et de champs de saisie de nom d'utilisateur et de mot de passe.

Réponse du jeton

Avec la connexion utilisateur, vous n'avez plus besoin 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'ID JWT (JSON Web Token) 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'accesseur de style "getter" pour travailler avec les données de profil utilisateur.

Un identifiant de 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 ; ou
  • 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:

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

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

En outre, et pour le mode redirection uniquement, veillez à empêcher la falsification des requêtes intersites (CSRF) et à vérifier le jeton d'ID Google sur votre serveur backend.

Pour mieux comprendre comment les utilisateurs interagissent avec votre site, vous pouvez utiliser le champ select_by de la réponse CredentialResponse pour déterminer le résultat du consentement des utilisateurs et le flux de connexion spécifique utilisé.

Lorsqu'un utilisateur se connecte pour la première fois à votre site Web, Google l'invite à 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 d'identifiant. 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 des autorisations et dissocier votre application de leur compte Google en accédant à 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. L'ancienne méthode disconnect 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 déconnecter 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 de la connexion de l'utilisateur.

État de la session et écouteurs

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

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

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

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

  • vous autorisez à partager leur profil utilisateur lors de leur inscription ou de leur connexion sur votre site,
  • et ultérieurement, lors de visites ultérieures 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 permettait de 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

La fonctionnalité Se connecter avec Google n'utilise qu'un nombre limité de cookies. Vous trouverez ci-après une description de ces cookies. Pour en savoir plus sur les autres types de cookies utilisés par Google, consultez Comment utilisons-nous les cookies ?.

Le cookie G_ENABLED_IDPS défini par l'ancienne bibliothèque de plate-forme Google Sign-In n'est plus utilisé.

La nouvelle bibliothèque Google Identity Services peut éventuellement définir ces cookies multidomaines 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 d'envoi double qui permet d'empêcher les attaques CSRF. Il est défini lorsque votre point de terminaison de connexion est appelé. La valeur de votre URI de connexion peut être définie explicitement ou définie par défaut sur 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

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

Si l'un de vos services gère les cookies, veillez à ajouter les deux nouveaux cookies et à supprimer le cookie précédent une fois la migration terminée.

Si vous gérez plusieurs domaines ou sous-domaines, consultez la section Afficher avec One Tap sur plusieurs sous-domaines pour en savoir plus sur l'utilisation du cookie g_state.

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

Anciennes offres Nouveau Notes
Bibliothèques JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Remplacez l'ancien par le nouveau.
apis.google.com/js/api.js accounts.google.com/gsi/client Remplacez l'ancien par le nouveau.
Objet GoogleAuth et méthodes associées:
GoogleAuth.attachClickHandler() IdConfiguration.callback pour data-callback en JavaScript et HTML Remplacez l'ancien par le nouveau.
GoogleAuth.currentUser.get() CredentialResponse (Réponse d'identification) Utilisez CredentialResponse à la place, qui n'est plus nécessaire.
GoogleAuth.currentUser.listen() Supprimer. L'état de connexion actuel d'un utilisateur sur Google n'est pas disponible. Les utilisateurs doivent être connectés à Google pour donner leur consentement et se connecter. Le champ select_by de CredentialResponse peut être utilisé pour déterminer le résultat du consentement de l'utilisateur ainsi que la méthode de connexion utilisée.
GoogleAuth.disconnect() google.accounts.id.revoke. Remplacez l'ancien par le nouveau. La révocation peut aussi se produire sur https://myaccount.google.com/permissions
GoogleAuth.grantofflineAccess() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
GoogleAuth.isSignedIn.get() Supprimer. L'état de connexion actuel d'un utilisateur sur Google n'est pas disponible. Les utilisateurs doivent être connectés à Google pour donner leur consentement et se connecter.
GoogleAuth.isSignedIn.listen() Supprimer. L'état de connexion actuel d'un utilisateur sur Google n'est pas disponible. Les utilisateurs doivent être connectés à Google pour donner leur consentement et se connecter.
GoogleAuth.signIn() Supprimer. Le chargement du DOM HTML de l'élément g_id_signin ou de l'appel JS à google.accounts.id.renderButton déclenche la connexion de l'utilisateur à un compte Google.
GoogleAuth.signOut() Supprimer. L'état de connexion de l'utilisateur pour votre application et un compte Google sont indépendants. Google ne gère pas l'état de session pour votre application.
GoogleAuth.then() Supprimer. GoogleAuth est obsolète.
Objet GoogleUser et méthodes associées:
GoogleUser.disconnect() google.accounts.id.revoke. Remplacez l'ancien par le nouveau. La révocation peut aussi se produire sur https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse (Réponse d'identification) Utilisez directement credential et les sous-champs au lieu des méthodes BasicProfile.
GoogleUser.getGrantedScopes() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
GoogleUser.getHostDomain() CredentialResponse (Réponse d'identification) Utilisez plutôt directement credential.hd.
UtilisateurGoogle.getId() CredentialResponse (Réponse d'identification) Utilisez plutôt directement credential.sub.
GoogleUser.grantofflineAccess() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
GoogleUser.grant() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
GoogleUser.hasGrantedScopes() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
GoogleUser.isSignedIn() Supprimer. L'état de connexion actuel d'un utilisateur sur Google n'est pas disponible. Les utilisateurs doivent être connectés à Google pour donner leur consentement et se connecter.
GoogleUser.reloadAuthResponse() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
Objet gapi.auth2 et méthodes associées:
Objet gapi.auth2.AuthorizeConfig Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
Objet gapi.auth2.AuthorizeResponse Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
Objet gapi.auth2.AuthResponse Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
gapi.auth2.authorize() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
gapi.auth2.ClientConfig(). Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
gapi.auth2.getAuthInstance() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
gapi.auth2.init() Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
Objet gapi.auth2.offlineAccessOptions Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
Objet gapi.auth2.SignInOptions Supprimer. Un jeton d'ID a remplacé les jetons d'accès et les champs d'application OAuth 2.0.
Objet gapi.signin2 et méthodes associées:
gapi.signin2.render() Supprimer. Le chargement du DOM HTML de l'élément g_id_signin ou de l'appel JS à google.accounts.id.renderButton déclenche la connexion de l'utilisateur à un compte Google.