Documentation de référence de l'API HTML Se connecter avec Google

Cette page de référence décrit l'API d'attributs de données HTML Se connecter avec Google. Vous pouvez utiliser l'API pour afficher l'invite "Un appui" ou le bouton "Se connecter avec Google" sur vos pages Web.

Élément avec l'ID "g_id_onload"

Vous pouvez placer des attributs de données Se connecter avec Google dans n'importe quel élément visible ou invisible, comme <div> et <span>. La seule exigence est que l'ID de l'élément soit défini sur g_id_onload. N'attribuez pas cet ID à plusieurs éléments.

Attributs de données

Le tableau suivant répertorie les attributs de données et leurs descriptions:

Types d'attributs

Les sections suivantes contiennent des informations sur le type de chaque attribut et un exemple.

data-client_id

Cet attribut correspond à l'ID client de votre application, qui se trouve et est créé dans la console Google Cloud. Pour en savoir plus, consultez le tableau suivant:

data-auto_prompt

Cet attribut détermine si l'option "Un appui" doit être affichée ou non. La valeur par défaut est true. Le paiement sans contact Google One ne s'affiche pas lorsque cette valeur est false. Pour en savoir plus, consultez le tableau suivant:

data-auto_select

Cet attribut détermine si un jeton d'ID doit être renvoyé automatiquement, sans interaction de l'utilisateur, si une seule session Google a approuvé votre application. La valeur par défaut est false. Pour en savoir plus, consultez le tableau suivant:

data-login_uri

Cet attribut correspond à l'URI de votre point de terminaison de connexion.

La valeur doit correspondre exactement à l'un des URI de redirection autorisés pour le client OAuth 2.0 que vous avez configuré dans la console API et doit respecter nos Règles de validation des URI de redirection.

Cet attribut peut être omis si la page actuelle est votre page de connexion, auquel cas l'identifiant est publié sur cette page par défaut.

La réponse des identifiants du jeton d'identité est publiée sur votre point de terminaison de connexion lorsqu'aucune fonction de rappel n'est définie et qu'un utilisateur clique sur les boutons "Se connecter avec Google" ou "One Tap", ou qu'une connexion automatique a lieu.

Pour en savoir plus, consultez le tableau suivant:

Votre point de terminaison de connexion doit gérer les requêtes POST contenant une clé credential avec une valeur de jeton d'ID dans le corps.

Voici un exemple de requête envoyée à votre point de terminaison de connexion:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

Il s'agit du nom de la fonction JavaScript qui gère le jeton d'ID renvoyé. Pour en savoir plus, consultez le tableau suivant:

L'un des attributs data-login_uri et data-callback peut être utilisé. Elle dépend des configurations de composants et de mode UX suivantes:

• L'attribut data-login_uri est obligatoire pour le mode d'expérience utilisateur redirect du bouton Se connecter avec Google, qui ignore l'attribut data-callback.

• L'un de ces deux attributs doit être défini pour le mode UX popup de Google One Tap et du bouton de connexion Google. Si les deux sont définis, l'attribut data-callback a une priorité plus élevée.

Les fonctions JavaScript dans un espace de noms ne sont pas compatibles avec l'API HTML. Utilisez plutôt une fonction JavaScript globale sans espace de noms. Par exemple, utilisez mylibCallback au lieu de mylib.callback.

data-native_login_uri

Cet attribut correspond à l'URL du point de terminaison de votre gestionnaire d'identifiants de mot de passe. Si vous définissez l'attribut data-native_login_uri ou l'attribut data-native_callback, la bibliothèque JavaScript utilise le gestionnaire d'identifiants natif en cas d'absence de session Google. Vous n'êtes pas autorisé à définir à la fois les attributs data-native_callback et data-native_login_uri. Pour en savoir plus, consultez le tableau suivant:

data-native_callback

Cet attribut correspond au nom de la fonction JavaScript qui gère les identifiants de mot de passe renvoyés par le gestionnaire d'identifiants natif du navigateur. Si vous définissez l'attribut data-native_login_uri ou l'attribut data-native_callback, la bibliothèque JavaScript utilise le Gestionnaire d'identifiants natif en l'absence de session Google. Vous n'êtes pas autorisé à définir à la fois data-native_callback et data-native_login_uri. Pour en savoir plus, consultez le tableau suivant:

Les fonctions JavaScript dans un espace de noms ne sont pas compatibles avec l'API HTML. Utilisez plutôt une fonction JavaScript globale sans espace de noms. Par exemple, utilisez mylibCallback au lieu de mylib.callback.

data-native_id_param

Lorsque vous envoyez les identifiants de mot de passe au point de terminaison du gestionnaire d'identifiants de mot de passe, vous pouvez spécifier le nom du paramètre pour le champ credential.id. Le nom par défaut est email. Pour en savoir plus, consultez le tableau suivant:

data-native_password_param

Lorsque vous envoyez les identifiants de mot de passe au point de terminaison du gestionnaire d'identifiants de mot de passe, vous pouvez spécifier le nom du paramètre pour la valeur credential.password. Le nom par défaut est password. Pour en savoir plus, consultez le tableau suivant:

data-cancel_on_tap_outside

Cet attribut indique si la demande de paiement sans contact doit être annulée ou non si l'utilisateur clique en dehors de l'invite. La valeur par défaut est true. Pour le désactiver, définissez la valeur sur false. Pour en savoir plus, consultez le tableau suivant:

data-prompt_parent_id

Cet attribut définit l'ID DOM de l'élément conteneur. Si elle n'est pas définie, l'invite One Tap s'affiche en haut à droite de la fenêtre. Pour en savoir plus, consultez le tableau suivant:

data-skip_prompt_cookie

Cet attribut ignore le service One Tap si la valeur du cookie spécifié n'est pas vide. Pour en savoir plus, consultez le tableau suivant:

data-nonce

Cet attribut est une chaîne aléatoire utilisée par le jeton d'ID pour empêcher les attaques par rejeu. Pour en savoir plus, consultez le tableau suivant:

La longueur de la nonce est limitée à la taille maximale de JWT prise en charge par votre environnement, ainsi qu'aux contraintes de taille HTTP du navigateur et du serveur individuels.

data-context

Cet attribut modifie le texte du titre et des messages affichés dans l'invite One Tap. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie tous les contextes disponibles et leur description:

rappel_moment_données

Cet attribut est le nom de fonction de l'écouteur des notifications d'état de l'interface utilisateur de l'invite. Pour en savoir plus, consultez le type de données PromptMomentNotification.

Pour en savoir plus, consultez le tableau suivant:

Les fonctions JavaScript dans un espace de noms ne sont pas compatibles avec l'API HTML. Utilisez plutôt une fonction JavaScript globale sans espace de noms. Par exemple, utilisez mylibCallback au lieu de mylib.callback.

data-state_cookie_domain

Si vous devez afficher One Tap dans un domaine parent et ses sous-domaines, transmettez le domaine parent à cet attribut afin qu'un seul cookie d'état partagé soit utilisé. Pour en savoir plus, consultez le tableau suivant:

data-ux_mode

Cet attribut définit le flux d'expérience utilisateur utilisé par le bouton "Se connecter avec Google". La valeur par défaut est popup. Cet attribut n'a aucun impact sur l'expérience utilisateur du paiement sans contact. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie les modes d'expérience utilisateur disponibles et leurs descriptions.

data-allowed_parent_origin

Origines autorisées à intégrer l'iFrame intermédiaire. One Tap s'exécute en mode iFrame intermédiaire si cet attribut est présent. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie les types de valeurs acceptés et leurs descriptions.

Si la valeur de l'attribut data-allowed_parent_origin n'est pas valide, l'initialisation One Tap du mode iFrame intermédiaire échouera et s'arrêtera.

Les préfixes génériques sont également acceptés. Par exemple, "https://*.example.com" correspond à example.com et à ses sous-domaines à tous les niveaux (par exemple, news.example.com, login.news.example.com). À retenir lorsque vous utilisez des caractères génériques:

• Les chaînes de modèle ne peuvent pas être composées uniquement d'un caractère générique et d'un domaine de premier niveau. Par exemple, https://*.com et https://*.co.uk ne sont pas valides. Comme indiqué ci-dessus, "https://*.example.com" correspond à example.com et à ses sous-domaines. Vous pouvez également utiliser une liste d'éléments séparés par une virgule pour représenter deux domaines différents. Par exemple, "https://example1.com,https://*.example2.com" correspond aux domaines example1.com, example2.com et aux sous-domaines de example2.com.
• Les domaines avec des caractères génériques doivent commencer par un schéma https:// sécurisé. "*.example.com" est donc considéré comme non valide.

data-intermediate_iframe_close_callback

Force le comportement par défaut de l'iframe intermédiaire lorsque les utilisateurs ferment manuellement One Tap en appuyant sur le bouton "X" dans l'interface utilisateur de One Tap. Le comportement par défaut consiste à supprimer immédiatement l'iFrame intermédiaire du DOM.

Le champ data-intermediate_iframe_close_callback ne prend effet que dans le mode iframe intermédiaire. Et cela n'a d'impact que sur l'iframe intermédiaire, et non sur l'iframe One Tap. L'interface utilisateur One Tap est supprimée avant l'appel du rappel.

Les fonctions JavaScript d'un espace de noms ne sont pas compatibles avec l'API HTML. Utilisez plutôt une fonction JavaScript globale sans espace de noms. Par exemple, utilisez mylibCallback au lieu de mylib.callback.

data-itp_support

Ce champ détermine si l' expérience utilisateur One Tap mise à niveau doit être activée sur les navigateurs compatibles avec la prévention intelligente du suivi (ITP). La valeur par défaut est false. Pour en savoir plus, consultez le tableau suivant:

data-login_hint

Si votre application sait à l'avance quel utilisateur doit être connecté, elle peut fournir un indice de connexion à Google. Lorsque l'opération réussit, la sélection du compte est ignorée. Valeurs acceptées: adresse e-mail ou champ sub de jeton d'ID.

Pour en savoir plus, consultez la documentation OpenID Connect pour login_hint.

data-hd

Lorsqu'un utilisateur possède plusieurs comptes et ne doit se connecter qu'avec son compte Workspace, utilisez cette option pour fournir un indice de nom de domaine à Google. Si l'opération réussit, les comptes utilisateur affichés lors de la sélection des comptes sont limités au domaine fourni. Un caractère générique: * propose uniquement des comptes Workspace à l'utilisateur et exclut les comptes personnels (user@gmail.com) lors de la sélection des comptes.

Pour en savoir plus, consultez la documentation OpenID Connect pour hd.

data-use_fedcm_for_prompt

Autorisez le navigateur à contrôler les invites de connexion des utilisateurs et à gérer le parcours de connexion entre votre site Web et Google. Valeur par défaut : "false". Pour en savoir plus, consultez la page Migrer vers FedCM.

data-enable_redirect_uri_validation

Activez le flux de redirection de bouton conforme aux Règles de validation des URI de redirection.

Élément associé à la classe "g_id_signin"

Si vous ajoutez g_id_signin à l'attribut class d'un élément, l'élément s'affiche sous la forme d'un bouton Se connecter avec Google.

Vous pouvez afficher plusieurs boutons "Se connecter avec Google" sur une même page. Chaque bouton peut avoir ses propres paramètres visuels. Les paramètres sont définis par les attributs de données suivants.

Attributs des données visuelles

Le tableau suivant répertorie les attributs de données visuels et leur description:

Types d'attributs

Les sections suivantes contiennent des informations sur le type de chaque attribut et un exemple.

data-type

Type de bouton. La valeur par défaut est standard. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie tous les types de boutons disponibles et leurs descriptions:

Type
standard
icon

data-theme

Thème du bouton. La valeur par défaut est outline. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie les thèmes disponibles et leurs descriptions:

Thème
outline
filled_blue
filled_black

Taille des données

Taille du bouton. La valeur par défaut est large. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie les tailles de bouton disponibles et leurs descriptions.

Taille
large
medium
small

données-texte

Texte du bouton. La valeur par défaut est signin_with. Il n'existe aucune différence visuelle pour le texte des boutons d'icône ayant des attributs data-text différents. La seule exception concerne la lecture du texte à des fins d'accessibilité.

Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant liste les textes de bouton disponibles et leur description:

Texte
signin_with
signup_with
continue_with
signin

data-shape

Forme du bouton. La valeur par défaut est rectangular. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant présente les formes de boutons disponibles et leur description:

Forme
rectangular
pill
circle
square

data-logo_alignment

L'alignement du logo Google. La valeur par défaut est left. Cet attribut ne s'applique qu'au type de bouton standard. Pour en savoir plus, consultez le tableau suivant:

Le tableau suivant répertorie les alignements disponibles et leur description:

logo_alignment
left
center

data-width

Largeur minimale du bouton, en pixels. La largeur maximale disponible est de 400 pixels.

Pour en savoir plus, consultez le tableau suivant:

data-locale

Facultatif. Affiche le texte du bouton dans la langue spécifiée. Sinon, les paramètres du navigateur ou du compte Google de l'utilisateur sont utilisés par défaut. Ajoutez le paramètre hl et le code de langue à l'instruction src lors du chargement de la bibliothèque, par exemple : gsi/client?hl=<iso-639-code>.

Si ce paramètre n'est pas défini, les paramètres régionaux par défaut du navigateur ou les préférences de l'utilisateur de la session Google sont utilisés. Par conséquent, différents utilisateurs peuvent voir différentes versions des boutons localisés, et éventuellement de différentes tailles.

Pour en savoir plus, consultez le tableau suivant:

écouteur de clics sur les données

Vous pouvez définir une fonction JavaScript à appeler lorsque l'utilisateur clique sur le bouton "Se connecter avec Google" à l'aide de l'attribut data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

Dans cet exemple, le message Sign in with Google button clicked... (Bouton Se connecter avec Google cliqué…) est consigné dans la console lorsque l'utilisateur clique sur le bouton Se connecter avec Google.

état-des-données

Facultatif : comme plusieurs boutons "Se connecter avec Google" peuvent être affichés sur la même page, vous pouvez attribuer une chaîne unique à chaque bouton. La même chaîne serait renvoyée avec le jeton d'ID, ce qui vous permet d'identifier le bouton sur lequel l'utilisateur a cliqué pour se connecter.

Pour en savoir plus, consultez le tableau suivant:

Intégration côté serveur

Vos points de terminaison côté serveur doivent gérer les requêtes HTTP POST suivantes.

Le point de terminaison du gestionnaire de jetons d'ID

Le point de terminaison du gestionnaire de jetons d'ID traite le jeton d'ID. En fonction de l'état du compte correspondant, vous pouvez connecter l'utilisateur et le rediriger vers une page d'inscription ou vers une page d'association de compte pour obtenir des informations supplémentaires.

La requête HTTP POST contient les informations suivantes:

identifiant

Une fois décodé, le jeton d'ID se présente comme suit:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

Le champ sub est un identifiant unique global pour le compte Google. Utilisez uniquement le champ sub comme identifiant de l'utilisateur, car il est unique pour tous les comptes Google et n'est jamais réutilisé. N'utilisez pas l'adresse e-mail comme identifiant, car un compte Google peut être associé à plusieurs adresses e-mail à différents moments.

Les champs email, email_verified et hd vous permettent de déterminer si Google héberge une adresse e-mail et s'il est l'autorité compétente. Lorsque Google est l'autorité compétente, l'utilisateur est confirmé comme étant le propriétaire légitime du compte.

Cas où Google est l'autorité compétente:

• email comporte un suffixe @gmail.com. Il s'agit d'un compte Gmail.
• email_verified a la valeur "true" et hd est défini. Il s'agit d'un compte Google Workspace.

Les utilisateurs peuvent créer des comptes Google sans utiliser Gmail ni Google Workspace. Lorsque email ne contient pas de suffixe @gmail.com et que hd n'est pas défini, Google n'est pas primaire, et un mot de passe ou d'autres méthodes d'authentification sont recommandés pour valider l'utilisateur. email_verified peut également être vrai, car Google a initialement validé l'utilisateur lors de la création du compte Google. Toutefois, la propriété du compte de messagerie tiers peut avoir changé depuis.

Le champ exp indique l'heure d'expiration pour que vous puissiez valider le jeton côté serveur. Ce délai est d'une heure pour le jeton d'ID obtenu via Se connecter avec Google. Vous devez valider le jeton avant la date d'expiration. N'utilisez pas exp pour la gestion des sessions. Un jeton d'ID expiré ne signifie pas que l'utilisateur est déconnecté. Votre application est responsable de la gestion des sessions de vos utilisateurs.

select_by

Le tableau suivant présente les valeurs possibles pour le champ select_by. Le type de bouton utilisé avec la session et l'état du consentement permet de définir la valeur.

• L'utilisateur a appuyé sur le bouton One Tap ou Se connecter avec Google, ou a utilisé le processus de connexion automatique sans contact.

• Une session existante a été détectée, ou l'utilisateur a sélectionné un compte Google et s'est connecté pour établir une nouvelle session.

• Avant de partager les identifiants du jeton d'identité avec votre application, l'utilisateur doit :

  • a appuyé sur le bouton "Confirmer" pour autoriser le partage des identifiants ; ou
  • avait déjà donné son consentement et utilisé "Sélectionner un compte" pour choisir un compte Google.

La valeur de ce champ est définie sur l'un des types suivants :

state

Ce paramètre n'est défini que lorsque l'utilisateur clique sur un bouton "Se connecter avec Google" pour se connecter, et que l'attribut data-state du bouton cliqué est spécifié. La valeur de ce champ est identique à celle que vous avez spécifiée dans l'attribut data-state du bouton.

Étant donné que plusieurs boutons "Se connecter avec Google" peuvent être affichés sur la même page, vous pouvez attribuer une chaîne unique à chaque bouton. Vous pouvez donc utiliser ce paramètre state pour identifier le bouton sur lequel l'utilisateur a cliqué pour se connecter.

Point de terminaison du gestionnaire d'identifiants de mot de passe

Le point de terminaison du gestionnaire d'identifiants de mot de passe traite les identifiants de mot de passe que le gestionnaire d'identifiants natif récupère.

La requête HTTP POST contient les informations suivantes: