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 les services d'identité Google pour en savoir plus.

Authentification et autorisation

L'authentification permet d'établir l'identité d'une personne. Elle est généralement appelée "inscription" ou "connexion" de l'utilisateur. 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 d'autoriser l'accès à son compte Google Drive.

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

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

Si votre cas d'utilisation ne concerne que l'authentification, continuez à lire cette page.

Si votre cas d'utilisation inclut l'autorisation, consultez Fonctionnement de l'autorisation utilisateur et Migrer vers les services d'identité Google 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 en termes d'usabilité. En voici quelques-unes :

  • Nouveaux flux de connexion One Tap et automatique à faible friction avec moins d'étapes individuelles.
  • un bouton de connexion repensé avec personnalisation pour l'utilisateur ;
  • Une image de marque cohérente 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.

Pour les développeurs, nous nous sommes concentrés sur la réduction de la complexité, l'amélioration de la sécurité et l'accélération de l'intégration. Voici quelques-unes de ces améliorations :

  • L'option permettant d'ajouter la connexion des utilisateurs au contenu statique de votre site en utilisant uniquement HTML,
  • La séparation de l'authentification de connexion de l'autorisation et du partage des données utilisateur rend inutile la complexité d'une intégration OAuth 2.0 pour connecter les utilisateurs à votre site.
  • Les modes pop-up et redirection restent compatibles, mais l'infrastructure OAuth 2.0 de Google redirige désormais vers le point de terminaison de connexion de votre serveur backend.
  • regroupement des fonctionnalités des anciennes bibliothèques JavaScript Google Identity et Google API dans une seule et même bibliothèque ;
  • Pour les réponses de connexion, vous pouvez désormais choisir d'utiliser ou non une Promise. L'indirection via les fonctions de style getter a été supprimée pour plus de simplicité.

Exemple de migration de la connexion

Si vous migrez depuis le bouton Se connecter avec Google existant et que vous souhaitez uniquement connecter les utilisateurs à votre site, la modification la plus simple consiste à passer au nouveau bouton personnalisé. Pour ce faire, vous pouvez remplacer 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 nouvelle bibliothèque JavaScript Google Identity Services unique : 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ù l'ancienne bibliothèque peut ê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é se charge apis.google.com/js/api:client.js.
  • L'utilisation directe de gapi.client charge apis.google.com/js/api.js.

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

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

Identifier le code concerné et le tester

Un cookie de débogage peut vous aider à localiser le code concerné et à tester le comportement post-obsolescence.

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 des 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 clé pour consigner les données 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 après l'abandon avant la date d'application.

Valeurs possibles du cookie G_AUTH2_MIGRATION :

  • Ne chargez pas le module gapi.auth2 de enforced.
  • informational Consignez l'utilisation des fonctionnalités obsolètes dans la console JS. Enregistrez également dans le stockage de 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 d'abord ce cookie localement pendant le développement et le test, avant de l'utiliser dans les environnements de production.

HTML et JavaScript

Dans ce scénario de connexion uniquement pour l'authentification, des exemples de code et des rendus 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 façon dont la réponse d'authentification est gérée par un rappel JavaScript ou par une redirection sécurisée vers le point de terminaison de connexion de votre serveur backend.

Ancienne méthode

Affichez le bouton "Se connecter avec Google" et utilisez un rappel pour gérer la connexion directement depuis le 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 de redirection

Affichez le bouton "Se connecter avec Google", en terminant par un appel AJAX depuis le navigateur de l'utilisateur vers le point de terminaison de connexion de vos serveurs 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

De nouveaux attributs visuels simplifient l'ancienne méthode de création d'un bouton personnalisé, éliminent les appels à gapi.signin2.render() et vous évitent d'héberger et de gérer des images et des éléments visuels sur votre site.

Google Sign-In

Connexion à Google

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

Nouvelle méthode

Pour utiliser la nouvelle bibliothèque dans un scénario de connexion uniquement pour l'authentification, 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 depuis le 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 de redirection

Google appelle votre point de terminaison de connexion tel que 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'identité sur votre point de terminaison dans le paramètre credential. Enfin, validez le jeton d'identité 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 visual-attributes pour personnaliser la taille, la forme et la couleur du bouton "Se connecter avec Google". Affichez le pop-up "S'inscrire en un clic" avec 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 met pas à jour le texte du bouton "Se connecter" en "Connecté". Après avoir donné son consentement ou lors de visites ultérieures, le bouton personnalisé inclut 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 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 "Connexion en un clic". Où que vous affichiez le bouton personnalisé, nous vous recommandons vivement d'afficher également le pop-up One Tap pour minimiser les frictions pour les utilisateurs lors de l'inscription et de la connexion.

Bien que cela ne soit pas recommandé en raison de la friction accrue lors de la 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 la connexion à votre site Web. Vous pouvez également utiliser l'API JavaScript, qui est 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 (couleur, taille, forme, texte et thème), consultez notre générateur de code. Il peut être utilisé pour comparer rapidement différentes options et générer des extraits HTML à utiliser sur votre site.

Se connecter depuis n'importe quelle page avec One Tap

One Tap est une nouvelle méthode simple permettant aux utilisateurs de s'inscrire ou de se connecter à votre site. Il vous permet d'activer la connexion des utilisateurs directement depuis n'importe quelle page de votre site et élimine la nécessité pour les utilisateurs d'accéder à une page de connexion dédiée. En d'autres termes, cela réduit les frictions liées à l'inscription et à la connexion en permettant aux utilisateurs de s'inscrire et de se connecter à partir de 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 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 de compte utilisateur. Offrez aux utilisateurs le choix de s'inscrire ou de se connecter en affichant le bouton à côté d'autres boutons de fournisseur d'identité fédéré, ainsi que des champs de saisie du nom d'utilisateur et du 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 JWT (JSON Web Token) est utilisé pour partager l'état de connexion et le profil utilisateur. Pour simplifier encore davantage le processus, vous n'avez plus besoin d'utiliser des méthodes d'accès de type "getter" pour travailler avec les données de profil utilisateur.

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

  • au gestionnaire de rappel JavaScript basé sur le navigateur de l'utilisateur en mode pop-up ;
  • à 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(),
  • les références à BasicProfile et les appels associés aux méthodes getId(), getName(), getGivenName(), getFamilyName(), getImageUrl() et getEmail() ;
  • l'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 du profil utilisateur.

De plus, et uniquement pour le mode Redirection, veillez à prévenir la falsification des requêtes intersites (CSRF) et à valider le jeton d'identité 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é.

Lorsqu'un utilisateur se connecte pour la première fois à votre site Web, Google lui demande l'autorisation de partager le profil de son compte avec votre application. Le profil de l'utilisateur n'est partagé avec votre application que s'il donne son autorisation, dans une charge utile d'identifiant. Révoquer l'accès à ce profil équivaut à révoquer un jeton d'accès dans l'ancienne bibliothèque de connexion.

Les utilisateurs peuvent révoquer les 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 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 par utilisateur et l'état de connexion.

É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 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 sont indépendants l'un de l'autre, sauf au moment de la connexion elle-même, lorsque vous savez que l'utilisateur s'est authentifié avec succès et est connecté à son compte Google.

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

  • donner leur consentement pour partager leur profil utilisateur lorsqu'ils s'inscrivent ou se connectent à votre site pour la première fois ;
  • et plus tard pour la connexion lors des 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 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 d'un compte Google. Les écouteurs ne sont plus pris en charge.

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

Cookies

Se connecter avec Google utilise les 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 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 à 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 votre URI de connexion peut être définie de manière explicite ou être 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 en un clic 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 une fois la migration terminée.

Si vous gérez plusieurs domaines ou sous-domaines, consultez Afficher l'authentification One Tap sur les sous-domaines pour obtenir d'autres instructions sur l'utilisation du cookie g_state.

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

Ancienne version Nouveau Remarques
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 JS et HTML data-callback Remplacez l'ancien par le nouveau.
GoogleAuth.currentUser.get() CredentialResponse Utilisez CredentialResponse à la place, ce 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 les moments de consentement et de connexion. Le champ select_by de CredentialResponse peut être utilisé pour déterminer le résultat du consentement 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 également avoir lieu sur https://myaccount.google.com/permissions.
GoogleAuth.grantOfflineAccess() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès 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 les moments de consentement et de connexion.
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 les moments de consentement et de connexion.
GoogleAuth.signIn() Supprimer. Le chargement du DOM HTML de l'élément g_id_signin ou l'appel JS à google.accounts.id.renderButton déclenchent la connexion de l'utilisateur à un compte Google.
GoogleAuth.signOut() Supprimer. L'état de connexion de l'utilisateur à votre application et à un compte Google sont indépendants. Google ne gère pas l'état de la 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 également avoir lieu sur https://myaccount.google.com/permissions.
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() CredentialResponse Utilisez directement credential et les sous-champs au lieu des méthodes BasicProfile.
GoogleUser.getGrantedScopes() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
GoogleUser.getHostedDomain() CredentialResponse Utilisez plutôt directement credential.hd.
GoogleUser.getId() CredentialResponse Utilisez plutôt directement credential.sub.
GoogleUser.grantOfflineAccess() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
GoogleUser.grant() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
GoogleUser.hasGrantedScopes() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès 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 les moments de consentement et de connexion.
GoogleUser.reloadAuthResponse() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
Objet gapi.auth2 et méthodes associées :
Objet gapi.auth2.AuthorizeConfig Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
Objet gapi.auth2.AuthorizeResponse Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
Objet gapi.auth2.AuthResponse Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
gapi.auth2.authorize() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
gapi.auth2.ClientConfig() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
gapi.auth2.getAuthInstance() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
gapi.auth2.init() Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
Objet gapi.auth2.OfflineAccessOptions Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès OAuth 2.0.
Objet gapi.auth2.SignInOptions Supprimer. Un jeton d'identité a remplacé les jetons d'accès et les niveaux d'accès 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 l'appel JS à google.accounts.id.renderButton déclenchent la connexion de l'utilisateur à un compte Google.