Cette documentation de référence décrit les méthodes et attributs du 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, signalez-le dans 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 s'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 lorsque l'objet gapi.auth2.GoogleAuth a terminé son initialisation.
|
GoogleAuth.then(onInit, onError)
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 les anciens navigateurs non compatibles), la fonction onError est appelée à la place.
Arguments | |
---|---|
onInit |
Fonction appelée avec l'objet GoogleAuth lorsqu'il est entièrement initialisé.
|
onError |
Fonction appelée avec un objet contenant une propriété error , si l'initialisation de GoogleAuth a échoué.
|
Renvoie | |
---|---|
Promise | Promise qui est rempli lorsque la fonction onInit est terminée, ou refusé si une erreur d'initialisation a été générée. Il se résout 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 (en raison d'un environnement non compatible, par exemple). Une propriété
details
fournit plus d'informations sur l'erreur générée.
gapi.auth2.ClientConfig
Interface représentant les différents paramètres de configuration de la méthode gapi.auth2.init
.
Paramètres | ||
---|---|---|
client_id |
string |
Obligatoire. ID client de l'application, trouvé et créé dans la console Google APIs. |
cookie_policy |
string |
Domaines pour lesquels créer des cookies de connexion. URI, single_host_origin ou none Prend la valeur single_host_origin par défaut s'il n'est pas spécifié. |
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érer 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 rien n'est spécifié. |
hosted_domain |
string |
Domaine G Suite auquel les utilisateurs doivent appartenir pour se connecter. Cette valeur peut être modifiée par les clients. Veillez donc à vérifier la propriété de domaine hébergé de l'utilisateur renvoyé. Utilisez GoogleUser.getHostedDomain() sur le client et la revendication hd dans le jeton d'ID sur le serveur pour vérifier que le domaine est celui que vous attendiez.
|
use_fedcm |
boolean |
Facultatif. Valeur par défaut : True . Activez ou désactivez l'utilisation des API FedCM du navigateur lors de la connexion. |
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 de remplacer le redirect_uri par défaut qui sera utilisé à la fin du flux de consentement. La valeur redirect_uri par défaut est l'URL actuelle sans les paramètres de requête ni le fragment de hachage.
|
enable_granular_consent |
boolean |
Facultatif. Activer ou non les autorisations précises. Si la valeur est false , les autorisations de compte Google plus précises seront désactivées pour les ID client OAuth créés avant 2019. Aucun effet sur les ID client OAuth créés en 2019 ou après, car des autorisations plus précises sont toujours activées pour eux.
|
plugin_name |
string |
Facultatif. Si cette valeur est définie, les nouveaux ID client créés avant le 29 juillet 2022 peuvent utiliser l'ancienne bibliothèque Google Platform.
Par défaut, les ID client nouvellement créés ne peuvent plus utiliser la bibliothèque de plate-forme et doivent utiliser la nouvelle bibliothèque Google Identity Services. Vous pouvez choisir n'importe quelle valeur. Un nom descriptif tel que le nom du produit ou du plug-in est recommandé pour l'identification.
Exemple : plugin_name: 'YOUR_STRING_HERE'
|
Authentification
GoogleAuth
est une classe singleton qui fournit des méthodes permettant à l'utilisateur de se connecter avec un compte Google, d'obtenir son état de connexion actuel, d'obtenir des données spécifiques du profil Google de l'utilisateur, de demander des niveaux d'accès 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 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 de 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 | |
---|---|
Promise | Promise rempli 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 en cas d'erreur. Pour en savoir plus sur les codes d'erreur, consultez la section suivante. |
Codes d'erreur
Voir GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Connecte l'utilisateur à l'aide des options spécifiées.
Arguments | |
---|---|
options |
Soit :
|
Renvoie | |
---|---|
Promise | Promise rempli 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 en cas d'erreur (voir ci-dessous pour les codes d'erreur). |
Codes d'erreur
popup_closed_by_user
- L'utilisateur a fermé la fenêtre pop-up avant de terminer le processus de connexion.
access_denied
- L'utilisateur a refusé l'autorisation pour les champs d'application requis.
immediate_failed
-
Aucun utilisateur ne peut être sélectionné automatiquement sans déclencher le flux de consentement. Erreur générée lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
. Cette option ne devrait pas être requise, cargapi.auth2.init
connecte automatiquement l'utilisateur s'il était déjà connecté lors d'une session précédente.
gapi.auth2.SignInOptions
Interface représentant 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 |
Les champs d'application à demander, sous la forme d'une chaîne délimitée par des espaces, en plus des champs d'application 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 une fenêtre pop-up. Les valeurs valides sont popup et redirect . |
redirect_uri |
string |
Si vous utilisez ux_mode='redirect' , ce paramètre vous permet de remplacer le redirect_uri par défaut qui sera utilisé à la fin du flux de consentement. La valeur redirect_uri par défaut est l'URL actuelle sans les paramètres de requête ni le fragment de hachage.
|
GoogleAuth.signOut()
Déconnecte le compte actuel de l'application.
Renvoie | |
---|---|
Promise | Promise exécutée lorsque l'utilisateur a été déconnecté. |
GoogleAuth.disconnect()
Révoque tous les champs d'application accordés par l'utilisateur.
GoogleAuth.grantHorsAccessAccess(options)
Obtenez l'autorisation de l'utilisateur pour accéder aux champs d'application spécifiés hors connexion.
Arguments | |
---|---|
options |
Objet gapi.auth2.OfflineAccessOptions contenant des paires clé-valeur de paramètres. Exemple : { scope: 'profile email' } |
Renvoie | |
---|---|
Promise | Un Promise traité 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 pour les champs d'application requis.
immediate_failed
-
Aucun utilisateur ne peut être sélectionné automatiquement sans déclencher le flux de consentement. Erreur générée lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
. Cette option ne devrait pas être requise, cargapi.auth2.init
connecte automatiquement l'utilisateur s'il était déjà connecté lors d'une session précédente.
gapi.auth2.OfflineAccessOptions
Interface représentant 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 |
Les champs d'application à demander, sous la forme d'une chaîne délimitée par des espaces, en plus des champs d'application 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 à l'élément div auquel associer le gestionnaire de clics. |
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 apportées à currentUser
Arguments | |
---|---|
listener |
Fonction qui utilise un paramètre GoogleUser .
listen transmet à cette fonction une instance GoogleUser à chaque modification qui modifie currentUser .
|
GoogleUser.getId()
Obtenez 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()
Récupérez 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()
Récupérez les champs d'application que l'utilisateur a accordés sous forme de chaîne délimitée par des espaces.
Renvoie | |
---|---|
Chaîne | Niveaux d'accès accordés par l'utilisateur |
GoogleUser.getBasicProfile()
Obtenez les informations de profil de base 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 à partir de la session d'authentification de l'utilisateur.
Arguments | |
---|---|
includeAuthorizationData | Facultatif:valeur booléenne indiquant si un jeton d'accès et des portées doivent toujours être renvoyés. Par défaut, le jeton d'accès et les portées demandées ne sont pas renvoyés lorsque fetch_basic_profile est défini sur "true" (valeur par défaut) et qu'aucune portée supplémentaire n'est demandée. |
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 AuthResponse.
Renvoie | |
---|---|
Promise |
Promise rempli avec le gapi.auth2.AuthResponse actualisé 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 |
Le jeton d'accès a été 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 à partir duquel l'utilisateur a accordé les portées demandées pour la première fois. |
expires_at |
number |
Horodatage de l'expiration du jeton d'accès. |
GoogleUser.hasGrantedScopes(scopes)
Renvoie la valeur "true" si l'utilisateur a accordé les portées spécifiées.
Arguments | |
---|---|
scopes | Chaîne de champs d'application séparés par des espaces. |
Renvoie | |
---|---|
Booléen | "True" si les niveaux d'accès ont été accordés |
UtilisateurGoogle.grant(options)
Demandez des portées 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 |
Objet gapi.auth2.OfflineAccessOptions contenant des paires clé-valeur de paramètres. Exemple : { scope: 'profile email' } |
GoogleUser.disconnect()
Révoque tous les champs d'application que l'utilisateur a accordés à 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é, à l'aide des 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. Exemple :
{ scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }
|
Avancé
gapi.auth2.authorize(params, callback)
Effectue une autorisation OAuth 2.0 unique. Selon les paramètres utilisés, une fenêtre pop-up s'ouvre pour le flux de connexion Google ou tente de charger la réponse demandée de manière silencieuse, sans interaction de l'utilisateur.
Voici quelques cas d'utilisation où cette méthode est utile:
- Votre application ne doit 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 lors de sa première connexion.
- Votre application dispose de sa propre infrastructure de gestion des sessions et n'a besoin du jeton d'ID qu'une seule fois pour identifier l'utilisateur dans votre 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 |
Fonction appelée avec un objet gapi.auth2.AuthorizeResponse une fois la requête terminée (avec succès ou é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 (en raison d'un environnement non compatible, par exemple). Une propriété
details
fournit plus d'informations sur l'erreur générée. popup_closed_by_user
- L'utilisateur a fermé la fenêtre pop-up avant de terminer le processus de connexion.
access_denied
- L'utilisateur a refusé l'autorisation pour les champs d'application requis.
immediate_failed
-
Aucun utilisateur ne peut être sélectionné automatiquement sans déclencher le flux de consentement. Une erreur a été générée lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
.
gapi.auth2.AuthorizeConfig
Interface représentant les différents paramètres de configuration de la méthode gapi.auth2.authorize
.
Propriétés | ||
---|---|---|
client_id |
string |
Obligatoire. ID client de l'application, trouvé et créé dans la console Google APIs. |
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éponse séparé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 . Prend la valeur single_host_origin par défaut s'il n'est pas spécifié.
|
hosted_domain |
string |
Domaine G Suite auquel les utilisateurs doivent appartenir pour se connecter. Cette valeur peut être modifiée par les clients. Veillez donc à vérifier la propriété de domaine hébergé de l'utilisateur renvoyé. |
login_hint |
string |
Adresse e-mail ou ID utilisateur d'un utilisateur à présélectionner lors du processus de connexion. Cette valeur peut être modifiée par l'utilisateur, sauf si prompt: "none" est utilisé.
|
include_granted_scopes |
boolean |
Indique si vous devez demander un jeton d'accès incluant 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 les autorisations précises. Si la valeur est false , les autorisations de compte Google plus précises seront désactivées pour les ID client OAuth créés avant 2019. Aucun effet sur les ID client OAuth créés en 2019 ou après, car des autorisations plus précises sont toujours activées pour eux.
|
plugin_name |
string |
Facultatif. Si cette valeur est définie, 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 plate-forme et doivent utiliser la nouvelle bibliothèque Google Identity Services. Vous pouvez choisir n'importe quelle valeur. Un nom descriptif tel que le nom du produit ou du plug-in est recommandé pour faciliter l'identification.
Exemple : plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse
Réponse renvoyée au rappel de la méthode gapi.auth2.authorize
.
Propriétés | ||
---|---|---|
access_token |
string |
Le jeton d'accès a été accordé. Uniquement présente si permission ou token a été spécifié dans response_type .
|
id_token |
string |
Jeton d'ID accordé. N'est présent que si id_token a été spécifié dans response_type .
|
code |
string |
Code d'autorisation accordé. N'est présent que si code a été spécifié dans response_type .
|
scope |
string |
Champs d'application accordés dans le jeton d'accès. Uniquement présente 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 à partir duquel l'utilisateur a accordé les portées demandées pour la première fois. N'est présent que si permission ou token a été spécifié dans response_type .
|
expires_at |
number |
Horodatage de l'expiration du jeton d'accès. N'est présent que 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é, elle peut contenir des informations supplémentaires sur le code d'erreur également renvoyé. |