Ce document de référence décrit les méthodes et attributs client JavaScript que vous utiliserez pour implémenter Google Sign-In dans vos applications Web.
Si vous rencontrez un problème lors de l'utilisation de la bibliothèque, veuillez le signaler sur notre dépôt GitHub.
Configuration de l'authentification
Chargez la bibliothèque de la plate-forme d'API Google pour créer l'objet gapi
:
<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>
Une fois la bibliothèque de la plate-forme chargée, chargez la bibliothèque auth2
:
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init(params)
Initialise l'objet GoogleAuth
. Vous devez appeler cette méthode avant d'appeler les méthodes de gapi.auth2.GoogleAuth
.
Lorsque vous initialisez l'objet GoogleAuth
, vous le configurez avec votre ID client OAuth 2.0 et toute autre option que vous souhaitez spécifier. Ensuite, si l'utilisateur est déjà connecté, l'objet GoogleAuth
restaure l'état de connexion de l'utilisateur de la session précédente.
Arguments | |
---|---|
params |
Objet contenant des paires clé/valeur de données de configuration client. Consultez gapi.auth2.ClientConfig pour connaître les différentes propriétés configurables. Exemple :
{ client_id: 'CLIENT_ID.apps.googleusercontent.com' } |
Renvoie | |
---|---|
gapi.auth2.GoogleAuth |
L'objet gapi.auth2.GoogleAuth Utilisez la méthode then() pour obtenir une promesse résolue à la fin de l'initialisation de l'objet gapi.auth2.GoogleAuth .
|
GoogleAuth.then(onInit, onError)
Elle appelle la fonction onInit lorsque l'objet GoogleAuth
est entièrement initialisé. Si une erreur est générée lors de l'initialisation (cela peut se produire dans d'anciens navigateurs non compatibles), la fonction onError est appelée à la place.
Arguments | |
---|---|
onInit |
La fonction appelée avec l'objet GoogleAuth lorsqu'elle est entièrement initialisée.
|
onError |
La fonction appelée avec un objet contenant une propriété error , en cas d'échec de l'initialisation de GoogleAuth .
|
Renvoie | |
---|---|
Promesse | Promise qui est exécuté lorsque la fonction onInit est terminée, ou rejeté si une erreur d'initialisation a été générée. Elle est résolue avec la valeur renvoyée par la fonction onInit, le cas échéant. |
Codes d'erreur
idpiframe_initialization_failed
-
Échec de l'initialisation d'un iFrame requis à partir de Google (par exemple, en raison d'un environnement non compatible). Une propriété
details
fournit plus d'informations sur l'erreur générée.
gapi.auth2.ClientConfig
Interface qui représente les différents paramètres de configuration de la méthode gapi.auth2.init
.
Paramètres | ||
---|---|---|
client_id |
string |
Obligatoire. L'ID client de l'application, trouvé et créé dans la Google Play Console. |
cookie_policy |
string |
Domaines pour lesquels créer des cookies de connexion. Un URI, single_host_origin ou none . Si aucune valeur n'est spécifiée, la valeur par défaut est single_host_origin . |
scope |
string |
Champs d'application à demander, sous forme de chaîne délimitée par des espaces. Facultatif si fetch_basic_profile n'est pas défini sur "false". |
fetch_basic_profile |
boolean |
Récupérez les informations de profil de base des utilisateurs lorsqu'ils se connectent. Ajoute "profile", "email" et "openid" aux champs d'application demandés. "True" si non spécifié. |
hosted_domain |
string |
Domaine G Suite auquel les utilisateurs doivent appartenir pour se connecter. Cette propriété est susceptible d'être modifiée par les clients. Par conséquent, veillez à valider la propriété de domaine hébergé de l'utilisateur renvoyé. Utilisez GoogleUser.getHostedDomain() sur le client, puis la revendication hd du jeton d'ID sur le serveur pour vérifier que le domaine correspond à vos attentes.
|
ux_mode |
string |
Mode d'expérience utilisateur à utiliser pour le flux de connexion. Par défaut, le flux de consentement s'ouvre dans un pop-up. Les valeurs valides sont popup et redirect . |
redirect_uri |
string |
Si vous utilisez ux_mode='redirect' , ce paramètre vous permet d'ignorer la valeur redirect_uri par défaut qui sera utilisée à la fin du flux de consentement. La valeur par défaut redirect_uri est l'URL actuelle sans les paramètres de requête et le fragment de hachage.
|
enable_granular_consent |
boolean |
Facultatif. Activer ou non des autorisations précises. Si elle est définie sur false , les autorisations de compte Google plus précises seront désactivées pour les ID client OAuth créés avant 2019. Aucun effet pour les ID client OAuth créés pendant ou après 2019, car des autorisations plus précises sont toujours activées.
|
plugin_name |
string |
Facultatif. Si cette valeur est définie, les ID client créés avant le 29 juillet 2022 peuvent utiliser l'ancienne bibliothèque Google Platform.
Par défaut, les nouveaux ID client ne peuvent plus utiliser la bibliothèque de la plate-forme. Ils doivent utiliser la bibliothèque Google Identity Services plus récente. Vous pouvez choisir n'importe quelle valeur. Il est recommandé d'utiliser un nom descriptif, tel qu'un nom de produit ou de plug-in, pour faciliter l'identification.
Exemple : plugin_name: 'YOUR_STRING_HERE'
|
Ratio d'économie d'énergie (EER)
GoogleAuth
est une classe singleton qui fournit des méthodes permettant à l'utilisateur de se connecter avec un compte Google, d'obtenir l'état de connexion actuel de l'utilisateur, d'obtenir des données spécifiques du profil Google de l'utilisateur, de demander des champs d'application supplémentaires et de se déconnecter du compte actuel.
gapi.auth2.getAuthInstance()
Renvoie l'objet GoogleAuth
. Vous devez initialiser l'objet GoogleAuth
avec gapi.auth2.init()
avant d'appeler cette méthode.
Renvoie | |
---|---|
gapi.auth2.GoogleAuth |
L'objet gapi.auth2.GoogleAuth Utilisez cet objet pour appeler les méthodes de gapi.auth2.GoogleAuth .
|
GoogleAuth.isSignedIn.get()
Indique si l'utilisateur actuel est actuellement connecté.
Renvoie | |
---|---|
Booléen |
true si l'utilisateur est connecté, ou false si l'utilisateur est déconnecté ou si l'objet GoogleAuth n'est pas initialisé.
|
GoogleAuth.isSignedIn.listen(listener)
Écoutez les modifications apportées à l'état de connexion de l'utilisateur actuel.
Arguments | |
---|---|
listener |
Fonction qui accepte une valeur booléenne. listen() transmet true à cette fonction lorsque l'utilisateur se connecte et false lorsqu'il se déconnecte.
|
GoogleAuth.signIn()
Connecte l'utilisateur avec les options spécifiées dans gapi.auth2.init()
.
Renvoie | |
---|---|
Promesse | Un Promise exécuté avec l'instance GoogleUser lorsque l'utilisateur s'authentifie et accorde les champs d'application demandés, ou refusé avec un objet contenant une propriété error si une erreur s'est produite (voir les codes d'erreur ci-dessous). |
Codes d'erreur
Consultez les GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Connecte l'utilisateur à l'aide des options spécifiées.
Arguments | |
---|---|
options |
Soit :
|
Renvoie | |
---|---|
Promesse | Un Promise exécuté avec l'instance GoogleUser lorsque l'utilisateur s'authentifie et accorde les champs d'application demandés, ou refusé avec un objet contenant une propriété error si une erreur s'est produite (voir les codes d'erreur ci-dessous). |
Codes d'erreur
popup_closed_by_user
- L'utilisateur a fermé le pop-up avant de terminer le processus de connexion.
access_denied
- L'utilisateur a refusé l'autorisation d'accéder aux champs d'application requis.
immediate_failed
-
Aucun utilisateur n'a pu être sélectionné automatiquement sans afficher le flux de consentement. Une erreur s'est produite lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
. Cette option ne doit pas être obligatoire, cargapi.auth2.init
connectera automatiquement l'utilisateur s'il était connecté lors d'une session précédente.
gapi.auth2.SignInOptions
Interface qui représente les différents paramètres de configuration de la méthode GoogleAuth.signIn(options)
.
Paramètres | ||
---|---|---|
prompt |
string |
Force un mode spécifique pour le flux de consentement. Facultatif. Les valeurs possibles sont les suivantes :
|
scope |
string |
Champs d'application à demander, sous la forme d'une chaîne délimitée par des espaces, en plus de ceux définis dans les paramètres gapi.auth2.init . Facultatif si fetch_basic_profile n'est pas défini sur "false".
|
ux_mode |
string |
Mode d'expérience utilisateur à utiliser pour le flux de connexion. Par défaut, le flux de consentement s'ouvre dans un pop-up. Les valeurs valides sont popup et redirect . |
redirect_uri |
string |
Si vous utilisez ux_mode='redirect' , ce paramètre vous permet d'ignorer la valeur redirect_uri par défaut qui sera utilisée à la fin du flux de consentement. La valeur par défaut redirect_uri est l'URL actuelle sans les paramètres de requête et le fragment de hachage.
|
GoogleAuth.signOut()
Déconnectez le compte actuel de l'application.
Renvoie | |
---|---|
Promesse | Un Promise qui est exécuté lorsque l'utilisateur a été déconnecté. |
GoogleAuth.disconnect()
Révoque tous les niveaux d'accès accordés par l'utilisateur.
GoogleAuth.grantHors connexion(options)
Obtenez l'autorisation de l'utilisateur pour accéder aux champs d'application spécifiés hors connexion.
Arguments | |
---|---|
options |
Un objet gapi.auth2.OfflineAccessOptions contenant des paires clé/valeur de paramètres. Par exemple : { scope: 'profile email' } |
Renvoie | |
---|---|
Promesse | Un Promise qui est exécuté lorsque l'utilisateur accorde les champs d'application demandés, en transmettant un objet contenant le code d'autorisation au gestionnaire de traitement de Promise .
Exemple: auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; }); |
Codes d'erreur
popup_closed_by_user
- L'utilisateur a fermé le pop-up avant de terminer le flux de consentement.
access_denied
- L'utilisateur a refusé l'autorisation d'accéder aux champs d'application requis.
immediate_failed
-
Aucun utilisateur n'a pu être sélectionné automatiquement sans afficher le flux de consentement. Une erreur s'est produite lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
. Cette option ne doit pas être obligatoire, cargapi.auth2.init
connectera automatiquement l'utilisateur s'il était connecté lors d'une session précédente.
gapi.auth2.OfflineAccessOptions
Interface qui représente les différents paramètres de configuration de la méthode GoogleAuth.grantOfflineAccess(options)
.
Paramètres | ||
---|---|---|
prompt |
string |
Force un mode spécifique pour le flux de consentement. Facultatif. Les valeurs possibles sont les suivantes :
|
scope |
string |
Champs d'application à demander, sous la forme d'une chaîne délimitée par des espaces, en plus de ceux définis dans les paramètres gapi.auth2.init . Facultatif si fetch_basic_profile n'est pas défini sur "false".
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Associe le flux de connexion au gestionnaire de clics du conteneur spécifié.
Arguments | |
---|---|
container | ID ou référence de l'élément div auquel le gestionnaire de clics doit être associé. |
options | Objet contenant des paires clé/valeur de paramètres. Consultez GoogleAuth.signIn(). |
onsuccess | Fonction à appeler une fois la connexion terminée. |
onfailure | Fonction à appeler en cas d'échec de la connexion. |
Utilisateurs
Un objet GoogleUser
représente un compte utilisateur.
Les objets GoogleUser
sont généralement obtenus en appelant GoogleAuth.currentUser.get().
GoogleAuth.currentUser.get()
Renvoie un objet GoogleUser
qui représente l'utilisateur actuel. Notez que dans une instance GoogleAuth
nouvellement initialisée, l'utilisateur actuel n'a pas été défini. Utilisez la méthode currentUser.listen()
ou GoogleAuth.then()
pour obtenir une instance GoogleAuth
initialisée.
Renvoie | |
---|---|
GoogleUser |
Utilisateur actuel |
GoogleAuth.currentUser.listen(listener)
Écouter les modifications dans currentUser.
Arguments | |
---|---|
listener |
Une fonction qui accepte un paramètre GoogleUser .
listen transmet à cette fonction une instance GoogleUser lors de chaque modification qui modifie currentUser .
|
GoogleUser.getId()
Récupérez la chaîne d'identifiant unique de l'utilisateur.
Renvoie | |
---|---|
Chaîne | Identifiant unique de l'utilisateur |
GoogleUser.isSignedIn()
Renvoie la valeur "true" si l'utilisateur est connecté.
Renvoie | |
---|---|
Booléen | "True" si l'utilisateur est connecté |
GoogleUser.getHostedDomain()
Obtenez le domaine G Suite de l'utilisateur s'il s'est connecté avec un compte G Suite.
Renvoie | |
---|---|
Chaîne | Domaine G Suite de l'utilisateur |
GoogleUser.getGrantedScopes()
Obtenez les niveaux d'accès accordés par l'utilisateur sous la forme d'une chaîne délimitée par des espaces.
Renvoie | |
---|---|
Chaîne | Champs d'application accordés par l'utilisateur |
GoogleUser.getBasicProfile()
Obtenez les informations de base du profil de l'utilisateur.
Renvoie | |
---|---|
gapi.auth2.BasicProfile |
Vous pouvez récupérer les propriétés de gapi.auth2.BasicProfile à l'aide des méthodes suivantes :
|
GoogleUser.getAuthResponse(includeAuthorizationData)
Obtenez l'objet de réponse de la session d'authentification de l'utilisateur.
Arguments | |
---|---|
includeAuthorizationData | Facultatif:Booléen qui indique s'il faut toujours renvoyer un jeton d'accès et des niveaux d'accès. Par défaut, le jeton d'accès et les champs d'application demandés ne sont pas renvoyés lorsque fetch_basic_profile est défini sur "true" (valeur par défaut) et qu'aucun champ d'application supplémentaire n'est demandé. |
Renvoie | |
---|---|
gapi.auth2.AuthResponse |
Un objet gapi.auth2.AuthResponse |
GoogleUser.reloadAuthResponse()
Force l'actualisation du jeton d'accès, puis renvoie une promesse pour la nouvelle réponse AuthResponse.
Renvoie | |
---|---|
Promise |
Un Promise rempli avec le gapi.auth2.AuthResponse rechargé lors de l'actualisation du jeton OAuth.
|
gapi.auth2.AuthResponse
Réponse renvoyée lors de l'appel des méthodes GoogleUser.getAuthResponse(includeAuthorizationData)
ou GoogleUser.reloadAuthResponse()
.
Propriétés | ||
---|---|---|
access_token |
string |
Jeton d'accès accordé. |
id_token |
string |
Jeton d'ID accordé. |
scope |
string |
Champs d'application accordés dans le jeton d'accès. |
expires_in |
number |
Nombre de secondes avant l'expiration du jeton d'accès. |
first_issued_at |
number |
Code temporel auquel l'utilisateur a accordé pour la première fois les niveaux d'accès demandés. |
expires_at |
number |
Code temporel correspondant à l'expiration du jeton d'accès. |
GoogleUser.hasGrantedScopes(scopes)
Renvoie la valeur "true" si l'utilisateur a accordé les niveaux d'accès spécifiés.
Arguments | |
---|---|
scopes | Chaîne de champs d'application délimitée par un espace. |
Renvoie | |
---|---|
Booléen | "True" si les niveaux d'accès ont été accordés |
GoogleUser.grant(options)
Demandez des niveaux d'accès supplémentaires à l'utilisateur.
Consultez GoogleAuth.signIn()
pour obtenir la liste des paramètres et le code d'erreur.
GoogleUser.grantofflineAccess(options)
Obtenez l'autorisation de l'utilisateur pour accéder aux champs d'application spécifiés hors connexion.
Arguments | |
---|---|
options |
Un objet gapi.auth2.OfflineAccessOptions contenant des paires clé/valeur de paramètres. Par exemple : { scope: 'profile email' } |
GoogleUser.disconnect()
Révoque tous les champs d'application que l'utilisateur a accordés pour l'application.
Éléments d'interface utilisateur
gapi.signin2.render(id, options)
Affiche un bouton de connexion dans l'élément avec l'ID donné, en utilisant les paramètres spécifiés par l'objet options.
Arguments | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | ID de l'élément dans lequel afficher le bouton de connexion. | ||||||||||||||||
options |
Objet contenant les paramètres à utiliser pour afficher le bouton. Par exemple :
{ scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }Vous pouvez spécifier les options suivantes:
|
Avancé
gapi.auth2.authorized(params, callback)
Effectue une autorisation OAuth 2.0 unique. En fonction des paramètres utilisés, un pop-up s'ouvre sur le flux Google Sign-In ou une tentative de chargement de la réponse demandée en mode silencieux, sans intervention de l'utilisateur.
Voici quelques cas d'utilisation dans lesquels cette méthode est utile:
- Votre application n'a besoin de demander un point de terminaison d'API Google qu'une seule fois, par exemple pour charger les vidéos YouTube préférées de l'utilisateur la première fois qu'il se connecte.
- Votre application dispose de sa propre infrastructure de gestion de sessions. Le jeton d'ID n'est requis qu'une seule fois pour identifier l'utilisateur dans le backend.
- Plusieurs ID client sont utilisés sur la même page.
Arguments | |
---|---|
params |
Objet contenant des paires clé/valeur de données de configuration. Consultez gapi.auth2.AuthorizeConfig pour connaître les différentes propriétés configurables. Exemple :
{ client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' } |
callback |
Une fonction appelée avec un objet gapi.auth2.AuthorizeResponse une fois la requête terminée (avec succès ou avec échec).
|
Exemple
gapi.auth2.authorize({
client_id: 'CLIENT_ID.apps.googleusercontent.com',
scope: 'email profile openid',
response_type: 'id_token permission'
}, function(response) {
if (response.error) {
// An error happened!
return;
}
// The user authorized the application for the scopes requested.
var accessToken = response.access_token;
var idToken = response.id_token;
// You can also now use gapi.client to perform authenticated requests.
});
Codes d'erreur
idpiframe_initialization_failed
-
Échec de l'initialisation d'un iFrame requis à partir de Google (par exemple, en raison d'un environnement non compatible). Une propriété
details
fournit plus d'informations sur l'erreur générée. popup_closed_by_user
- L'utilisateur a fermé le pop-up avant de terminer le processus de connexion.
access_denied
- L'utilisateur a refusé l'autorisation d'accéder aux champs d'application requis.
immediate_failed
-
Aucun utilisateur n'a pu être sélectionné automatiquement sans afficher le flux de consentement. Une erreur s'est produite lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
.
gapi.auth2.AuthorizeConfig
Interface qui représente les différents paramètres de configuration de la méthode gapi.auth2.authorize
.
Propriétés | ||
---|---|---|
client_id |
string |
Obligatoire : L'ID client de l'application, trouvé et créé dans la Google Play Console. |
scope |
string |
Obligatoire : Champs d'application à demander, sous forme de chaîne délimitée par des espaces. |
response_type |
string |
Liste de types de réponses délimités par un espace. La valeur par défaut est 'permission' . Les valeurs possibles sont les suivantes :
|
prompt |
string |
Force un mode spécifique pour le flux de consentement. Les valeurs possibles sont les suivantes :
|
cookie_policy |
string |
Domaines pour lesquels créer des cookies de connexion. Un URI, single_host_origin ou none . Si aucune valeur n'est spécifiée, la valeur par défaut est single_host_origin .
|
hosted_domain |
string |
Domaine G Suite auquel les utilisateurs doivent appartenir pour se connecter. Cette propriété est susceptible d'être modifiée par les clients. Par conséquent, veillez à valider la propriété du domaine hébergé de l'utilisateur renvoyé. |
login_hint |
string |
Adresse e-mail, ou ID utilisateur, d'un utilisateur à présélectionner dans le flux de connexion. Ce paramètre est susceptible d'être modifié par l'utilisateur, sauf si prompt: "none" est utilisé.
|
include_granted_scopes |
boolean |
Permet de demander un jeton d'accès qui inclut tous les champs d'application précédemment accordés par l'utilisateur à l'application, ou uniquement les champs d'application demandés dans l'appel en cours. La valeur par défaut est true .
|
enable_granular_consent |
boolean |
Facultatif. Activer ou non des autorisations précises. Si elle est définie sur false , les autorisations de compte Google plus précises seront désactivées pour les ID client OAuth créés avant 2019. Aucun effet pour les ID client OAuth créés pendant ou après 2019, car des autorisations plus précises sont toujours activées.
|
plugin_name |
string |
Facultatif. S'il est défini, les ID client créés avant le 29 juillet 2022 peuvent utiliser la bibliothèque Google Platform. Par défaut, les ID client nouvellement créés ne peuvent pas utiliser la bibliothèque de la plate-forme. Ils doivent utiliser la bibliothèque Google Identity Services plus récente. Vous pouvez choisir n'importe quelle valeur. Il est recommandé d'utiliser un nom descriptif, tel qu'un nom de produit ou de plug-in, pour faciliter l'identification.
Exemple : plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse
La réponse est renvoyée au rappel de la méthode gapi.auth2.authorize
.
Propriétés | ||
---|---|---|
access_token |
string |
Jeton d'accès accordé. Présent uniquement si permission ou token a été spécifié dans response_type .
|
id_token |
string |
Jeton d'ID accordé. Présent uniquement si id_token a été spécifié dans response_type .
|
code |
string |
Code d'autorisation accordé. Présent uniquement si code a été spécifié dans response_type .
|
scope |
string |
Champs d'application accordés dans le jeton d'accès. Présent uniquement si permission ou token a été spécifié dans response_type .
|
expires_in |
number |
Nombre de secondes avant l'expiration du jeton d'accès. Présent uniquement si permission ou token a été spécifié dans response_type .
|
first_issued_at |
number |
Code temporel auquel l'utilisateur a accordé pour la première fois les niveaux d'accès demandés. Présent uniquement si permission ou token a été spécifié dans response_type .
|
expires_at |
number |
Code temporel correspondant à l'expiration du jeton d'accès. Présent uniquement si permission ou token a été spécifié dans response_type .
|
error |
string |
Lorsque la requête a échoué, il contient le code d'erreur. |
error_subtype |
string |
Lorsque la requête a échoué, cet élément peut contenir des informations supplémentaires par rapport au code d'erreur également renvoyé. |