Ce guide vous aide à comprendre les modifications et étapes nécessaires à la migration réussie des bibliothèques JavaScript depuis l'ancienne bibliothèque de la plate-forme Google Sign-In vers la bibliothèque des services Google Identity pour l'authentification.
Si votre client utilise la bibliothèque cliente des API Google pour JavaScript ou d'autres bibliothèques plus anciennes pour l'autorisation, consultez la page Migrer vers les services Google Identity pour en savoir plus.
Authentification et autorisation
L'authentification, qui est généralement appelée inscription ou connexion utilisateur, permet de déterminer qui est l'utilisateur. L'autorisation est le processus permettant d'accorder ou de refuser l'accès aux données ou aux ressources. Par exemple, votre application demande le consentement de l'utilisateur pour accéder à Google Drive.
Comme l'ancienne bibliothèque de la plate-forme Google Sign-In, la nouvelle bibliothèque Google Identity Services est conçue pour être compatible avec les processus d'authentification et d'autorisation.
Cependant, la nouvelle bibliothèque sépare les deux processus afin de réduire la complexité pour que les développeurs puissent intégrer des comptes Google à votre application.
Si votre cas d'utilisation ne concerne que l'authentification, veuillez lire cette page.
Si votre cas d'utilisation inclut une autorisation, consultez les sections Fonctionnement de l'autorisation des utilisateurs et Migrer vers les services Google Identity 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 de facilité d'utilisation. Points forts:
- de nouveaux processus de connexion en un seul geste et de connexion automatique avec moins d'étapes individuelles,
- un bouton de connexion actualisé avec une personnalisation utilisateur,
- une marque cohérente et un comportement de connexion uniforme sur le Web améliorent la compréhension et la confiance,
- d'accéder rapidement et facilement au contenu. Les utilisateurs peuvent s'inscrire et se connecter facilement et facilement depuis n'importe quel site de votre site, sans avoir à consulter une page de connexion ou de compte.
Notre objectif a été de réduire la complexité, d'améliorer la sécurité et de rendre l'intégration aussi rapide et facile que possible. Voici quelques-unes de ces améliorations:
- L'option permettant d'ajouter une connexion utilisateur au contenu statique de votre site en HTML uniquement
- la séparation de l'authentification de connexion de l'autorisation et du partage des données utilisateur, la complexité d'une intégration OAuth2 n'est plus nécessaire simplement pour connecter les utilisateurs à votre site,
- Les modes pop-up et de redirection restent compatibles, mais l'infrastructure OAuth2 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 de Google Identity et des API Google en une seule nouvelle bibliothèque,
- Pour les réponses de connexion, vous devez maintenant décider d'utiliser ou non une promesse. 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 à partir du bouton Google Sign-In existant et que vous ne souhaitez connecter que des utilisateurs à votre site, la modification la plus simple consiste simplement à passer au nouveau bouton personnalisé. Pour ce faire, changez de bibliothèque JavaScript et mettez à jour votre codebase pour utiliser un nouvel objet de connexion.
Bibliothèques et configuration
L'ancienne bibliothèque de la 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 requises pour l'authentification et l'autorisation des utilisateurs :
Elles ont été remplacées par une nouvelle bibliothèque JavaScript Google Identity Services: accounts.google.com/gsi/client
.
Les trois anciens modules JavaScript api
, client
et platform
utilisés pour la connexion sont tous chargés à partir de apis.google.com
. Pour vous aider à identifier les emplacements dans lesquels l'ancienne bibliothèque pourrait être incluse dans votre site:
- 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
chargeapis.google.com/js/api.js
.
Dans la plupart des cas, vous pouvez continuer à utiliser les identifiants d'ID client de votre application Web existante. Dans le cadre de votre migration, nous vous recommandons de consulter nos règles OAuth 2.0 et d'utiliser la console d'API Google 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 ont 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 et les tests concernés
Un cookie de débogage peut vous aider à localiser le code concerné et à tester le comportement post-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 l'utilisation de la fonctionnalité bientôt obsolète sur la console, définissez la valeur du cookie G_AUTH2_MIGRATION
sur informational
. Vous pouvez également ajouter deux-points suivis d'une valeur de clé pour vous connecter également au stockage de sessions.
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 de cookie G_AUTH2_MIGRATION
possibles:
enforced
Ne chargez pas le modulegapi.auth2
.informational
Consignez l'utilisation de la fonctionnalité obsolète dans la console JS. Consignez également dans le stockage de sessions lorsqu'un nom de clé facultatif est défini :informational:key-name
.
Pour minimiser l'impact sur les utilisateurs, nous vous recommandons de commencer par définir ce cookie localement lors du développement et des tests, avant de l'utiliser dans des environnements de production.
HTML et JavaScript
Dans ce scénario de connexion par authentification uniquement, des exemples de code et de rendus du bouton Google Sign-In existant sont présentés. Sélectionnez le mode pop-up ou de redirection afin d'afficher les différences de traitement de la réponse d'authentification, soit par un rappel JavaScript, soit par une redirection sécurisée vers le point de terminaison de votre serveur backend.
L'ancienne méthode
Mode pop-up
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 de redirection
Affichez le bouton Google Sign-In, qui se termine par un appel AJAX depuis le navigateur de l'utilisateur vers votre point de terminaison de connexion au serveur interne.
<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 l'ancienne méthode de création d'un bouton personnalisé. Ils éliminent les appels à gapi.signin2.render()
, et vous évitent d'avoir à héberger et à gérer des images et des éléments visuels sur votre site.
Texte du bouton de mise à jour de l'état de connexion de l'utilisateur.
Une nouvelle façon
Pour utiliser la nouvelle bibliothèque dans un scénario de connexion par authentification simple, sélectionnez le mode pop-up ou redirection et utilisez l'exemple de code pour remplacer votre mise en œuvre existante sur votre page de connexion.
Mode pop-up
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 de 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 dans 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 attributs visuels 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.
L'état de connexion de l'utilisateur ne met pas à jour le texte du bouton "Connexion" à "Connecté". Une fois que vous avez donné votre consentement ou lors de vos visites répétées, le bouton personnalisé inclut le nom, l'adresse e-mail et la photo de profil de l'utilisateur.
Dans cet exemple simple d'authentification, la nouvelle bibliothèque accounts.google.com/gsi/client
, la nouvelle classe g_id_signin
et l'objet g_id_onload
remplacent l'ancien objet apis.google.com/js/platform.js
et l'ancien objet g-signin2
.
En plus d'afficher le nouveau bouton personnalisé, l'exemple de code affiche le nouveau pop-up One Tap. Chaque fois que vous affichez le bouton personnalisé, nous vous recommandons vivement d'afficher également le pop-up One Tap afin de limiter les risques de friction lors de l'inscription et de la connexion.
Bien que cela ne soit pas recommandé en raison d'une friction de connexion accrue, le nouveau bouton personnalisé peut s'afficher seul, sans afficher la boîte de dialogue One Tap simultanément. Pour ce faire, définissez l'attribut data-auto_prompt
sur false
.
API HTML et JavaScript
L'exemple ci-dessus montre comment utiliser la nouvelle API HTML pour ajouter une 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 une nouvelle méthode simple qui permet aux utilisateurs de s'inscrire ou de se connecter à votre site. Cela vous permet de permettre aux utilisateurs de se connecter directement à partir de n'importe quelle page de votre site, et évite aux utilisateurs d'avoir à accéder à une page de connexion dédiée. En d'autres termes, cela réduit la friction d'inscription et de connexion en offrant aux utilisateurs la flexibilité 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 les pages de connexion ou de gestion des comptes utilisateur. Donnez aux utilisateurs le choix de s'inscrire ou de se connecter en affichant le bouton à côté d'autres boutons de fournisseurs d'identité fédérés, ainsi que les champs de saisie du nom d'utilisateur et du mot de passe.
Réponse du jeton
La connexion des utilisateurs ne nécessite plus que vous compreniez les codes d'autorisation, les jetons d'accès ou les jetons d'actualisation OAuth2. À la place, un jeton d'ID de jeton Web JSON (JWT) est utilisé pour partager l'état de connexion et le profil utilisateur. Pour simplifier, vous n'êtes plus obligé d'utiliser des méthodes d'accesseur de type "getter" pour travailler avec les données de profil utilisateur.
Un identifiant de jeton JWT sécurisé signé par Google est renvoyé:
- au gestionnaire de rappel JavaScript basé sur le navigateur de l'utilisateur en mode pop-up ; ou
- à 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 surredirect
.
Dans les deux cas, mettez à jour vos gestionnaires de rappel existants en supprimant:
- appels à
googleUser.getBasicProfile()
, - les références à
BasicProfile
, ainsi que les appels associés aux méthodesgetId()
,getName()
,getGivenName()
,getFamilyName()
,getImageUrl()
etgetEmail()
; - 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 utiliser les données de profil utilisateur.
De plus, pour le mode de redirection uniquement, assurez-vous d'empêcher la falsification des requêtes intersites (CSRF) et de 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 CredentialResponse afin de déterminer le résultat du consentement de l'utilisateur et le parcours de connexion spécifique.
Consentement de l'utilisateur et révocation de l'autorisation
Lorsqu'un utilisateur se connecte pour la première fois à votre site Web, Google l'invite à autoriser le partage du profil de son compte avec votre application. Ce n'est qu'après avoir obtenu le consentement que le profil de l'utilisateur est partagé avec votre application dans une charge utile de jeton d'ID. Révoquer l'accès à ce profil revient à révoquer un jeton d'accès dans l'ancienne bibliothèque de connexion.
Les utilisateurs peuvent révoquer les autorisations et déconnecter 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 plus récente 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 servir à 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 utilisateur et l'état de connexion.
État de la session et écouteurs
La nouvelle bibliothèque ne conserve pas l'état de la connexion ou de la 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.
L'état de la connexion de l'utilisateur à son compte Google et à votre application est indépendant les uns des autres, sauf pendant le moment de la connexion lui-même lorsque vous savez que l'utilisateur a été authentifié et qu'il est connecté à son compte Google.
Lorsque la fonctionnalité Se connecter avec Google, One Tap ou automatique est incluse sur votre site, les utilisateurs doivent d'abord se connecter à leur compte Google pour:
- autoriser le partage de leur profil utilisateur lors de la première inscription ou de la première connexion à votre site ;
- et plus tard pour la connexion lors des visites répétées.
Les utilisateurs peuvent rester connectés, se déconnecter ou changer de 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 permettaient de partager les changements d'état de connexion du compte Google d'un utilisateur. Les écouteurs ne sont plus compatibles.
Supprimez toutes les références à listen()
, auth2.currentUser
et auth2.isSignedIn
.
Cookies
La fonctionnalité Se connecter avec Google utilise de façon limitée les cookies. Vous en trouverez la description. Pour en savoir plus sur les autres types de cookies que Google utilise, consultez Comment Google utilise les cookies.
Le cookie G_ENABLED_IDPS
défini par l'ancienne bibliothèque de la plate-forme Google Sign-in n'est plus utilisé.
La nouvelle bibliothèque des services Google Identity 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. Il est défini lorsque vous utilisez le pop-up One Tap ou la connexion automatique.g_csrf_token
est un cookie à double envoi utilisé pour empêcher les attaques CSRF. Il est défini lors de l'appel de votre point de terminaison de connexion. 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 lorsquedata-login_uri
est défini, ouAPI JavaScript avec
ux_mode=redirect
, et oùgoogle.accounts.id.prompt()
n'est pas utilisé pour afficher la fonctionnalité One Tap ni la connexion automatique.
Si un service 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 la section Afficher le paiement sans contact 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 utilisateur
Anciennes offres | Nouveautés | Remarques |
---|---|---|
Bibliothèques JavaScript | ||
apis.google.com/js/platform.js | accounts.google.com/gsi/client | Remplacer l'ancien par le nouveau. |
apis.google.com/js/api.js | accounts.google.com/gsi/client | Remplacer l'ancien par le nouveau. |
Objet GoogleAuth et méthodes associées: | ||
GoogleAuth.attachClickHandler() | IdConfiguration.callback pour data-callback JS et HTML | Remplacer l'ancien par le nouveau. |
GoogleAuth.currentUser.get() | CredentialResponse | Utilisez CredentialResponse à la place, ce 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 obtenir le consentement et les moments de connexion. 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. | Remplacer l'ancien par le nouveau. La révocation peut également être effectuée sur https://myaccount.google.com/permissions |
GoogleAuth.grantOfflineAccess() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
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 obtenir le consentement et les moments 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 obtenir le consentement et les moments de connexion. | |
GoogleAuth.signIn(). | Supprimer. Le chargement DOM HTML de l'élément g_id_signin ou l'appel JS vers 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 de votre application. | |
GoogleAuth.then() | Supprimer. GoogleAuth est obsolète. | |
Objet GoogleUser et méthodes associées: | ||
GoogleUser.disconnect() | google.accounts.id.revoke. | Remplacer l'ancien par le nouveau. La révocation peut également être effectuée sur https://myaccount.google.com/permissions |
GoogleUser.getAuthResponse() | ||
GoogleUser.getBasicProfile() | CredentialResponse | Utilisez directement les méthodes credential et les sous-champs au lieu des méthodes BasicProfile . |
GoogleUser.getGrantedScopes() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
GoogleUser.getHostedDomain() | CredentialResponse | Utilisez plutôt credential.hd . |
GoogleUser.getId() | CredentialResponse | Utilisez plutôt credential.sub . |
GoogleUser.grantOfflineAccess() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
GoogleUser.grant() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
GoogleUser.hasGrantedScopes() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
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 obtenir le consentement et les moments de connexion. | |
GoogleUser.reloadAuthResponse() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
Objet gapi.auth2 et méthodes associées: | ||
Objet gapi.auth2.AuthorizeConfig | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
Objet gapi.auth2.AuthorizeResponse | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
Objet gapi.auth2.AuthResponse | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
gapi.auth2.authorize() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
gapi.auth2.ClientConfig() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
gapi.auth2.getAuthInstance() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
gapi.auth2.init() | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
Objet gapi.auth2.OfflineAccessOptions | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
Objet gapi.auth2.SignInOptions | Supprimer. Un jeton d'identification a remplacé les champs d'application et les jetons d'accès OAuth2. | |
Objet gapi.signin2 et méthodes associées: | ||
gapi.signin2.render() | Supprimer. Le chargement DOM HTML de l'élément g_id_signin ou l'appel JS vers google.accounts.id.renderButton déclenche la connexion de l'utilisateur à un compte Google. |