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

Cette page de référence décrit l'API JavaScript Sign-In. Vous pouvez utiliser cette API pour afficher l'invite One Tap ou le bouton "Se connecter avec Google" sur vos pages Web.

Méthode : google.accounts.id.initialize

La méthode google.accounts.id.initialize initialise le client S'identifier avec Google en fonction de l'objet de configuration. Consultez l'exemple de code suivant de la méthode :

google.accounts.id.initialize(IdConfiguration)

L'exemple de code suivant implémente la méthode google.accounts.id.initialize avec une fonction onload :

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

La méthode google.accounts.id.initialize crée une instance client Se connecter avec Google qui peut être utilisée de manière implicite par tous les modules de la même page Web.

• Vous n'avez besoin d'appeler la méthode google.accounts.id.initialize qu'une seule fois, même si vous utilisez plusieurs modules (comme One Tap, le bouton personnalisé, la révocation, etc.) sur la même page Web.
• Si vous appelez la méthode google.accounts.id.initialize plusieurs fois, seules les configurations du dernier appel seront mémorisées et utilisées.

En fait, vous réinitialisez les configurations chaque fois que vous appelez la méthode google.accounts.id.initialize, et toutes les méthodes suivantes sur la même page Web utilisent immédiatement les nouvelles configurations.

Type de données : IdConfiguration

Le tableau suivant liste les champs et les descriptions du type de données IdConfiguration :

client_id

Ce champ correspond à l'ID client de votre application, que vous trouverez et créerez dans la console Google Cloud. Pour en savoir plus, consultez le tableau ci-dessous :

auto_select

Ce champ détermine si un jeton d'identité est renvoyé automatiquement sans aucune interaction de l'utilisateur lorsqu'il n'y a qu'une seule session Google qui a déjà approuvé votre application. La valeur par défaut est false. Pour en savoir plus, consultez le tableau ci-dessous :

callback

Ce champ correspond à la fonction JavaScript qui gère le jeton d'identité renvoyé par l'invite One Tap ou la fenêtre pop-up. Cet attribut est obligatoire si le mode UX popup de Google One Tap ou du bouton "Se connecter avec Google" est utilisé. Pour en savoir plus, consultez le tableau ci-dessous :

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 Google Cloud 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 les identifiants sont publiés sur cette page par défaut.

La réponse d'identifiant du jeton d'identité est envoyée à votre point de terminaison de connexion lorsqu'un utilisateur clique sur le bouton "Se connecter avec Google" et que le mode UX de redirection est utilisé.

Pour en savoir plus, consultez le tableau ci-dessous :

Votre point de terminaison de connexion doit gérer les requêtes POST contenant un paramètre credential avec une valeur de jeton d'identité dans le corps.

native_callback

Ce champ correspond au nom de la fonction JavaScript qui gère les identifiants de mot de passe renvoyés par le gestionnaire d'identifiants intégré du navigateur. Pour en savoir plus, consultez le tableau ci-dessous :

cancel_on_tap_outside

Ce champ permet de définir si la requête One Tap doit être annulée ou non si un utilisateur clique en dehors de l'invite. La valeur par défaut est true. Vous pouvez le désactiver en définissant la valeur sur false. Pour en savoir plus, consultez le tableau ci-dessous :

prompt_parent_id

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

nonce

Ce champ est une chaîne aléatoire utilisée par le jeton d'identité pour empêcher les attaques par rejeu. Pour en savoir plus, consultez le tableau ci-dessous :

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

context

Ce champ modifie le texte du titre et des messages affichés dans l'invite S'identifier en un clic. Il n'a aucun effet sur les navigateurs ITP. La valeur par défaut est signin.

Pour en savoir plus, consultez le tableau ci-dessous :

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

state_cookie_domain

Si vous devez afficher la connexion en un clic dans le domaine parent et ses sous-domaines, transmettez le domaine parent à ce champ afin qu'un seul cookie à état partagé soit utilisé. Pour en savoir plus, consultez le tableau ci-dessous :

ux_mode

Utilisez ce champ pour définir 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 One Tap. Pour en savoir plus, consultez le tableau ci-dessous :

Le tableau suivant répertorie les modes UX disponibles et leur description.

allowed_parent_origin

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

Le tableau suivant répertorie les types de valeurs acceptés et leur description.

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). Voici quelques points à retenir lorsque vous utilisez des caractères génériques :

• Les chaînes de format 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, car "https://.example.com" correspond à example.com et à tous ses sous-domaines. Utilisez une liste séparée par des virgules pour représenter deux domaines différents. Par exemple, "https://example1.com,https://.example2.com" correspond aux domaines example1.com et example2.com, ainsi qu'aux sous-domaines de example2.com.
• Les domaines génériques doivent commencer par un schéma https:// sécurisé. Par conséquent, "*.example.com" est considéré comme non valide.

Si la valeur du champ allowed_parent_origin n'est pas valide, l'initialisation One Tap du mode iframe intermédiaire échouera et s'arrêtera.

intermediate_iframe_close_callback

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

Le champ intermediate_iframe_close_callback ne prend effet qu'en mode iframe intermédiaire. Il n'a d'impact que sur l'iFrame intermédiaire, et non sur l'iFrame One Tap. L'UI One Tap est supprimée avant l'appel du rappel.

itp_support

Ce champ détermine si l' expérience utilisateur One Tap améliorée doit être activée sur les navigateurs compatibles avec la fonctionnalité Intelligent Tracking Prevention (ITP). La valeur par défaut est false. Pour en savoir plus, consultez le tableau ci-dessous :

login_hint

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

Pour en savoir plus, consultez le champ login_hint dans la documentation OpenID Connect.

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 du compte sont limités au domaine fourni. Une valeur générique : * ne propose que des comptes Workspace à l'utilisateur et exclut les comptes personnels ([email protected]) lors de la sélection du compte.

Pour en savoir plus, consultez le champ hd dans la documentation OpenID Connect.

use_fedcm_for_prompt

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

use_fedcm_for_button

Ce champ détermine si l'interface utilisateur du bouton FedCM doit être utilisée sur Chrome (version M125+ pour ordinateur et M128+ pour Android). La valeur par défaut est false. Pour en savoir plus, consultez le tableau ci-dessous :

button_auto_select

Ce champ détermine s'il faut activer l'option Sélection automatique pour le flux du bouton FedCM. Si cette option est activée, les utilisateurs connus disposant d'une session Google active seront automatiquement connectés, sans passer par l'invite du sélecteur de compte. La valeur par défaut est false. Vous devez activer explicitement la connexion automatique par bouton lors du lancement de l'activation. Pour en savoir plus, consultez le tableau ci-dessous :

Méthode : google.accounts.id.prompt

La méthode google.accounts.id.prompt affiche l'invite S'identifier en un clic ou le gestionnaire d'identifiants intégré au navigateur après l'appel de la méthode initialize(). Consultez l'exemple de code suivant de la méthode :

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

Normalement, la méthode prompt() est appelée lors du chargement de la page. En raison de l'état de la session et des paramètres utilisateur côté Google, il est possible que l'UI de l'invite One Tap ne s'affiche pas. Pour recevoir des notifications sur l'état de l'UI à différents moments, transmettez une fonction pour recevoir des notifications sur l'état de l'UI.

Les notifications sont déclenchées aux moments suivants :

• Moment d'affichage : se produit après l'appel de la méthode prompt(). La notification contient une valeur booléenne indiquant si l'UI est affichée ou non.

• Moment ignoré : cela se produit lorsque l'invite One Tap est fermée par une annulation automatique ou manuelle, ou lorsque Google ne parvient pas à émettre un identifiant, par exemple lorsque la session sélectionnée est déconnectée de Google.

  Dans ce cas, nous vous recommandons de passer aux fournisseurs d'identité suivants, le cas échéant.

• Moment de fermeture : se produit lorsque Google récupère un identifiant ou qu'un utilisateur souhaite arrêter le flux de récupération d'identifiants. Par exemple, lorsque l'utilisateur commence à saisir son nom d'utilisateur et son mot de passe dans votre boîte de dialogue de connexion, vous pouvez appeler la méthode google.accounts.id.cancel() pour fermer l'invite S'identifier en un clic et déclencher un moment de fermeture.

L'exemple de code suivant implémente le moment ignoré :

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

Type de données : PromptMomentNotification

Le tableau suivant liste les méthodes et les descriptions du type de données PromptMomentNotification :

Type de données : CredentialResponse

Lorsque votre fonction callback est appelée, un objet CredentialResponse est transmis en tant que paramètre. Le tableau suivant liste les champs contenus dans l'objet de réponse des identifiants :

identifiant

Ce champ correspond au jeton d'identification sous forme de chaîne JSON Web Token (JWT) encodée en base64.

Une fois décodé, le jeton JWT ressemble à l'exemple suivant :

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": "[email protected]", // 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": "Elisa",
  "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 parmi tous les comptes Google et n'est jamais réutilisé.

Les champs email, email_verified et hd vous permettent de déterminer si Google héberge une adresse e-mail et fait autorité pour celle-ci. Dans les cas où Google fait autorité, il est confirmé que l'utilisateur est le propriétaire légitime du compte.

Cas où Google fait autorité :

• Si l'adresse e-mail se termine par @gmail.com, il s'agit d'un compte Gmail.email
• Si email_verified est défini sur "true" et que hd est défini, il s'agit d'un compte Google Workspace.

Les utilisateurs peuvent s'inscrire à des comptes Google sans utiliser Gmail ni Google Workspace. Lorsque email ne contient pas de suffixe @gmail.com et que hd est absent, Google n'est pas une source faisant autorité. Il est recommandé d'utiliser un mot de passe ou d'autres méthodes de validation pour vérifier l'identité de l'utilisateur. email_verfied peut également être défini sur "true", 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 le délai dont vous disposez pour valider le jeton côté serveur. Il est d'une heure pour le jeton d'ID obtenu à partir de Se connecter avec Google. Vous devez valider le jeton avant son expiration. N'utilisez pas exp pour la gestion des sessions. Un jeton d'identité 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 répertorie les valeurs possibles pour le champ select_by. Le type de bouton utilisé, ainsi que l'état de la session et du consentement, permettent 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é trouvée ou l'utilisateur a sélectionné un compte Google et s'y 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 de ces types.

state

Ce champ n'est défini que lorsque l'utilisateur clique sur un bouton "Se connecter avec Google" pour se connecter et que l'attribut state du bouton sur lequel il a cliqué est spécifié. La valeur de ce champ est identique à celle que vous avez spécifiée dans l'attribut 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 à chacun d'eux. Vous pouvez donc utiliser ce champ state pour identifier le bouton sur lequel l'utilisateur a cliqué pour se connecter.

Méthode : google.accounts.id.renderButton

La méthode google.accounts.id.renderButton affiche un bouton "Se connecter avec Google" sur vos pages Web.

Consultez l'exemple de code suivant de la méthode :

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

Type de données : GsiButtonConfiguration

Le tableau suivant liste les champs et les descriptions du type de données GsiButtonConfiguration :

Types d'attributs

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

type

Type de bouton. La valeur par défaut est standard.

Pour en savoir plus, consultez le tableau ci-dessous :

Le tableau suivant répertorie les types de boutons disponibles et leur description :

Type
standard
icon

thème

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

Le tableau suivant répertorie les thèmes disponibles et leur description :

Thème
outline
filled_blue
filled_black

taille

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

Le tableau suivant répertorie les tailles de bouton disponibles et leur description :

Taille
large
medium
small

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 qui ont des attributs text différents. La seule exception concerne la lecture du texte pour l'accessibilité de l'écran.

Pour en savoir plus, consultez le tableau ci-dessous :

Le tableau suivant répertorie tous les textes de bouton disponibles et leur description :

Texte
signin_with
signup_with
continue_with
signin

shape

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

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

Forme
rectangular
pill
circle
square

logo_alignment

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 ci-dessous :

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

logo_alignment
left
center

largeur

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

Pour en savoir plus, consultez le tableau ci-dessous :

locale

Facultatif. Affichez le texte du bouton à l'aide des paramètres régionaux spécifiés, sinon utilisez par défaut les paramètres du compte Google ou du navigateur de l'utilisateur. Ajoutez le paramètre hl et le code de langue à la directive src lors du chargement de la bibliothèque, par exemple : gsi/client?hl=<iso-639-code>.

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

Pour en savoir plus, consultez le tableau ci-dessous :

click_listener

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

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }
  

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

state

Facultatif : é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. La même chaîne est renvoyée avec le jeton d'identité. Vous pouvez ainsi identifier le bouton sur lequel l'utilisateur a cliqué pour se connecter.

Pour en savoir plus, consultez le tableau ci-dessous :

Type de données : identifiant

Lorsque votre fonction native_callback est appelée, un objet Credential est transmis en tant que paramètre. Le tableau suivant liste les champs contenus dans l'objet :

Méthode : google.accounts.id.disableAutoSelect

Lorsque l'utilisateur se déconnecte de votre site Web, vous devez appeler la méthode google.accounts.id.disableAutoSelect pour enregistrer l'état dans les cookies. Cela évite une boucle morte de l'UX. Consultez l'extrait de code suivant de la méthode :

google.accounts.id.disableAutoSelect()

L'exemple de code suivant implémente la méthode google.accounts.id.disableAutoSelect avec une fonction onSignout() :

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

Méthode : google.accounts.id.storeCredential

Cette méthode est un wrapper pour la méthode store() de l'API Credential Manager intégrée au navigateur. Par conséquent, il ne peut être utilisé que pour stocker un identifiant de mot de passe. Consultez l'exemple de code suivant de la méthode :

google.accounts.id.storeCredential(Credential, callback)

L'exemple de code suivant implémente la méthode google.accounts.id.storeCredential avec une fonction onSignIn() :

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

Méthode : google.accounts.id.cancel

Vous pouvez annuler le flux One Tap si vous supprimez l'invite du DOM de la partie de confiance. L'opération d'annulation est ignorée si des identifiants sont déjà sélectionnés. Consultez l'exemple de code suivant de la méthode :

google.accounts.id.cancel()

L'exemple de code suivant implémente la méthode google.accounts.id.cancel() avec une fonction onNextButtonClicked() :

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

Callback de chargement de la bibliothèque : onGoogleLibraryLoad

Vous pouvez enregistrer un rappel onGoogleLibraryLoad. Elle est notifiée une fois la bibliothèque JavaScript S'identifier avec Google chargée :

window.onGoogleLibraryLoad = () => {
    ...
};

Ce rappel n'est qu'un raccourci pour le rappel window.onload. Il n'y a aucune différence de comportement.

L'exemple de code suivant implémente un rappel onGoogleLibraryLoad :

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

Méthode : google.accounts.id.revoke

La méthode google.accounts.id.revoke révoque l'autorisation OAuth utilisée pour partager le jeton d'identité de l'utilisateur spécifié. Consultez l'extrait de code suivant de la méthode : javascript google.accounts.id.revoke(login_hint, callback)

L'exemple de code suivant montre comment utiliser la méthode revoke avec un ID.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

Type de données : RevocationResponse

Lorsque votre fonction callback est appelée, un objet RevocationResponse est transmis en tant que paramètre. Le tableau suivant liste les champs contenus dans l'objet de réponse de révocation :

réussie

Ce champ est une valeur booléenne définie sur "true" si l'appel de la méthode de révocation a réussi ou sur "false" en cas d'échec.

erreur

Ce champ est une valeur de chaîne et contient un message d'erreur détaillé si l'appel de la méthode revoke a échoué. Il est indéfini en cas de succès.