Le présent document de référence décrit les méthodes et les attributs du client JavaScript que vous utiliserez pour implémenter Google Sign-In dans vos applications Web.
Si vous rencontrez des problèmes avec la bibliothèque, veuillez le signaler à 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-laauth2
bibliothèque:
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init(params)
Initialisation de 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 les options supplémentaires que vous souhaitez spécifier. Si l'utilisateur s'est déjà connecté, l'objet GoogleAuth
restaure l'état de connexion de l'utilisateur à partir de la session précédente.
Arguments | |
---|---|
params |
Objet contenant des paires clé/valeur de données de configuration client. Pour les différentes propriétés configurables, consultez la section gapi.auth2.ClientConfig . 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)
Il 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 sera appelée.
Arguments | |
---|---|
onInit |
La fonction appelée avec l'objet GoogleAuth lorsqu'elle est entièrement initialisé
|
onError |
La fonction appelée avec un objet contenant une propriété error si l'initialisation de GoogleAuth échoue.
|
Renvoie | |
---|---|
Promesse | Promise qui est exécuté lorsque la fonction onInit est terminée, ou refusée en cas d'erreur d'initialisation. Il résout 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. ID client de l'application, trouvé et créé dans Google Developers 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 un espace. 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. Vrai si non spécifié. |
hosted_domain |
string |
Domaine G Suite auquel les utilisateurs doivent appartenir pour se connecter. Étant donné qu'il est susceptible d'être modifié par les clients, veillez à valider la propriété du domaine hébergé pour 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 correspond à vos attentes.
|
ux_mode |
string |
Mode d'expérience utilisateur à utiliser pour le processus 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 d'ignorer la valeur redirect_uri par défaut qui sera utilisée à la fin du flux de consentement. L'élément redirect_uri par défaut est l'URL actuelle supprimée des paramètres de requête et du fragment de hachage.
|
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 ID client nouvellement créés ne peuvent plus utiliser la bibliothèque de plates-formes et doivent donc utiliser la bibliothèque de services Google Identity plus récente. Vous pouvez choisir n'importe quelle valeur. Un nom descriptif tel qu'un nom de produit ou de plug-in est recommandé pour faciliter 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 l'état de connexion actuel de l'utilisateur, d'obtenir des données spécifiques de son profil Google, de demander des niveaux d'accès supplémentaires et de se déconnecter de la votre 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.isSignIn.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(écouteur)
Détecter 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 lorsque l'utilisateur se déconnecte.
|
GoogleAuth.signIn().
Connecte l'utilisateur avec les options spécifiées à gapi.auth2.init()
.
Renvoie | |
---|---|
Promesse | un Promise rempli avec l'instance GoogleUser lorsque l'utilisateur s'authentifie et accorde les champs d'application demandés, ou est rejeté avec un objet contenant une propriété error en cas d'erreur (voir ci-dessous pour les codes d'erreur). |
Codes d'erreur
Consultez la GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Permet à l'utilisateur de se connecter à l'aide des options spécifiées.
Arguments | |
---|---|
options |
Au choix :
|
Renvoie | |
---|---|
Promesse | un Promise rempli avec l'instance GoogleUser lorsque l'utilisateur s'authentifie et accorde les champs d'application demandés, ou est rejeté 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é le pop-up avant de finaliser la procédure de connexion.
access_denied
- L'utilisateur a refusé l'autorisation aux champs d'application requis.
immediate_failed
- Aucun utilisateur ne peut être sélectionné automatiquement sans que le flux de consentement soit demandé. Erreur lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
. Cette option ne doit pas être nécessaire, cargapi.auth2.init
connectera automatiquement l'utilisateur s'il s'était connecté au cours 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 |
Forcer un mode spécifique pour le flux de consentement. Facultatif. Les valeurs possibles sont les suivantes :
|
scope |
string |
Champs d'application à demander, en tant que chaîne délimitée par un espace, 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 processus 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 d'ignorer la redirect_uri par défaut qui sera utilisée à la fin du flux de consentement. L'élément redirect_uri par défaut est l'URL actuelle supprimée des paramètres de requête et du fragment de hachage.
|
GoogleAuth.signOut().
Déconnexion du compte actuel de l'application.
Renvoie | |
---|---|
Promesse | Promise traité lorsque l'utilisateur a été déconnecté. |
GoogleAuth.disconnect().
Révoque tous les champs d'application accordés par l'utilisateur.
GoogleAuth.grantOfflineAccess(options)
Obtenir l'autorisation hors connexion de l'utilisateur pour accéder aux habilitations spécifiées.
Arguments | |
---|---|
options |
Un objet gapi.auth2.OfflineAccessOptions contenant des paires clé/valeur. Par exemple : { scope: 'profile email' } |
Renvoie | |
---|---|
Promesse | Un Promise qui est traité lorsque l'utilisateur accorde les champs d'application demandés, en transmettant un objet contenant le code d'autorisation au gestionnaire de traitement 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 finaliser le flux de consentement.
access_denied
- L'utilisateur a refusé l'autorisation aux champs d'application requis.
immediate_failed
- Aucun utilisateur ne peut être sélectionné automatiquement sans que le flux de consentement soit demandé. Erreur lors de l'utilisation de
signIn
avec l'optionprompt: 'none'
. Cette option ne doit pas être nécessaire, cargapi.auth2.init
connectera automatiquement l'utilisateur s'il s'était connecté au cours d'une session précédente.
gapi.auth2.OfflineAccessOptions (en anglais)
Interface qui représente les différents paramètres de configuration de la méthode GoogleAuth.grantOfflineAccess(options)
.
Paramètres | ||
---|---|---|
prompt |
string |
Forcer un mode spécifique pour le flux de consentement. Facultatif. Les valeurs possibles sont les suivantes :
|
scope |
string |
Champs d'application à demander, en tant que chaîne délimitée par un espace, 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)
Rattache le flux de connexion au gestionnaire de clics du conteneur spécifié.
Arguments | |
---|---|
container | ID de l'élément div auquel associer le gestionnaire de clics ou d'une référence à cet élément. |
options | Objet contenant des paires clé/valeur. Voir GoogleAuth.signIn(). |
onsuccess | Fonction à appeler après la connexion. |
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
récemment 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)
Écoutez les modifications apportées dans "userUser".
Arguments | |
---|---|
listener |
Une fonction qui utilise un paramètre GoogleUser .
listen transmet cette fonction à une instance GoogleUser à chaque modification qui modifie currentUser .
|
GoogleUser.getId()
Récupérez la chaîne d'ID unique de l'utilisateur.
Renvoie | |
---|---|
Chaîne | ID unique de l'utilisateur |
GoogleUser.isSignedIn()
Renvoie la valeur "true" si l'utilisateur est connecté.
Renvoie | |
---|---|
Booléen | Vrai 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 champs d'application autorisés par l'utilisateur sous forme de chaîne délimitée par un espace.
Renvoie | |
---|---|
Chaîne | Champs d'application autorisés par l'utilisateur |
GoogleUser.getBasicProfile()
Obtenez les informations 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)
Récupérez l'objet de réponse à partir de la session d'authentification de l'utilisateur.
Arguments | |
---|---|
includeAuthorizationData | Facultatif:Valeur booléenne indiquant 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 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 la gapi.auth2.AuthResponse rechargée lors de l'actualisation du jeton OAuth est terminé.
|
gapi.auth2.AuthResponse
Réponse renvoyée lors de l'appel de méthodes GoogleUser.getAuthResponse(includeAuthorizationData)
ou GoogleUser.reloadAuthResponse()
.
Properties | ||
---|---|---|
access_token |
string |
Jeton d'accès accordé. |
id_token |
string |
Jeton d'ID accordé. |
scope |
string |
Champs d'application autorisés dans le jeton d'accès. |
expires_in |
number |
Nombre de secondes jusqu'à l'expiration du jeton d'accès. |
first_issued_at |
number |
Horodatage auquel l'utilisateur a accordé les premiers champs d'application demandés. |
expires_at |
number |
Horodatage de la fin du jeton d'accès. |
GoogleUser.hasGrantedScopes(scopes)
Affiche 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 des espaces. |
Renvoie | |
---|---|
Booléen | Vrai si les champs d'application ont été autorisé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)
Obtenir l'autorisation hors connexion de l'utilisateur pour accéder aux habilitations spécifiées.
Arguments | |
---|---|
options |
Un objet gapi.auth2.OfflineAccessOptions contenant des paires clé/valeur. Par exemple : { scope: 'profile email' } |
GoogleUser.disconnect()
Révoque tous les champs d'application autorisés par l'utilisateur pour l'application.
Éléments de l'interface utilisateur
gapi.signin2.render(id, options)
Il affiche un bouton de connexion dans l'élément avec l'ID indiqué, en utilisant les paramètres spécifiés par l'objet options.
Arguments | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | ID de l'élément dans lequel vous souhaitez 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 une seule fois. Selon les paramètres utilisés, une fenêtre pop-up s'ouvre ou essaie de charger la réponse demandée de manière silencieuse, sans intervention de l'utilisateur.
Cette méthode peut être utile dans les cas suivants:
- Votre application n'a besoin de demander qu'un seul point de terminaison de l'API Google, 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 session et ne requiert le 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 découvrir 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 ou sans é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 finaliser la procédure de connexion.
access_denied
- L'utilisateur a refusé l'autorisation aux champs d'application requis.
immediate_failed
- Aucun utilisateur ne peut être sélectionné automatiquement sans que le flux de consentement soit demandé. Erreur 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
.
Properties | ||
---|---|---|
client_id |
string |
Required. ID client de l'application, trouvé et créé dans Google Developers Console |
scope |
string |
Required. Champs d'application à demander, sous forme de chaîne délimitée par un espace. |
response_type |
string |
Liste de types de réponse délimités par un espace. La valeur par défaut est 'permission' . Les valeurs possibles sont les suivantes :
|
prompt |
string |
Forcer 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. Étant donné qu'il peut être modifié par les clients, veillez à valider la propriété du domaine hébergé pour l'utilisateur renvoyé. |
login_hint |
string |
Adresse e-mail (ou ID utilisateur) d'un utilisateur à présélectionner dans le flux de connexion. L'utilisateur est susceptible de le modifier, sauf s'il utilise prompt: "none" .
|
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 .
|
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 plates-formes et doivent utiliser la bibliothèque de services Google Identity Services, la plus récente. Vous pouvez choisir n'importe quelle valeur. Un nom descriptif tel qu'un nom de produit ou de plug-in est recommandé pour faciliter l'identification.
Exemple : plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse
Réponse au rappel de la méthode gapi.auth2.authorize
.
Properties | ||
---|---|---|
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é. Disponible uniquement si id_token a été spécifié dans response_type .
|
code |
string |
Code d'autorisation accordé. Disponible uniquement si code a été spécifié dans response_type .
|
scope |
string |
Champs d'application autorisés dans le jeton d'accès. Disponible uniquement si permission ou token a été spécifié dans response_type .
|
expires_in |
number |
Nombre de secondes jusqu'à l'expiration du jeton d'accès. Disponible uniquement si permission ou token a été spécifié dans response_type .
|
first_issued_at |
number |
Horodatage auquel l'utilisateur a accordé les premiers champs d'application demandés. Disponible uniquement si permission ou token a été spécifié dans response_type .
|
expires_at |
number |
Horodatage de la fin du jeton d'accès. Disponible uniquement si permission ou token a été spécifié dans response_type .
|
error |
string |
Lorsque la requête échoue, il s'agit du code d'erreur. |
error_subtype |
string |
Si la requête a échoué, cela peut contenir des informations supplémentaires au code d'erreur. |