Bibliothèque JavaScript d'autorisation Google tierce pour les sites Web – Documentation de référence de l'API

Ce document de référence décrit l'API 3P Authorization JavaScript Library de Google, que vous pouvez utiliser pour charger des codes d'autorisation ou des jetons d'accès à partir de Google.

Méthode: google.accounts.oauth2.initCodeClient

La méthode initCodeClient initialise et renvoie un client de code, avec les configurations définies dans les paramètres.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

Type de données: CodeClientConfig

Le tableau suivant répertorie les propriétés du type de données CodeClientConfig.

Propriétés
client_id	Obligatoire. ID client de votre application. Vous trouverez cette valeur dans la console API.
scope	Obligatoire. Liste de champs d'application délimités par des espaces qui identifient les ressources auxquelles votre application pourrait accéder pour le compte de l'utilisateur. Ces valeurs déterminent l'écran de consentement que Google présente à l'utilisateur.
include_granted_scopes	Facultatif. Valeur par défaut : true. Permet aux applications d'utiliser une autorisation incrémentielle pour demander l'accès à des champs d'application supplémentaires en contexte. Si vous définissez la valeur de ce paramètre sur false et que la demande d'autorisation est accordée, le nouveau jeton d'accès ne couvrira que les champs d'application auxquels scope a été demandé dans ce CodeClientConfig.
redirect_uri	Obligatoire pour l'expérience utilisateur de redirection. Détermine où le serveur d'API redirige l'utilisateur une fois que celui-ci a terminé le flux d'autorisation. Cette 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 conforme à nos règles de validation des URI de redirection. La propriété sera ignorée par l'expérience utilisateur pop-up.
callback	Obligatoire pour l'expérience utilisateur dans les fenêtres pop-up. Fonction JavaScript qui gère la réponse de code renvoyée. La propriété sera ignorée par l'expérience utilisateur de redirection.
state	Facultatif. Recommandé pour la redirection de l'expérience utilisateur. Spécifie toute valeur de chaîne utilisée par votre application pour maintenir l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation.
enable_granular_consent	Facultatif. Valeur par défaut : true. Si ce paramètre est défini sur false, des autorisations plus précises sur le compte Google seront désactivées pour les ID client OAuth créés avant 2019. Si enable_granular_consent et enable_serial_consent sont tous les deux définis, seule la valeur enable_granular_consent sera prise en compte, et la valeur enable_serial_consent sera ignorée. Aucun effet pour les ID client OAuth les plus récents, car des autorisations plus précises sont toujours activées pour ces ID.
enable_serial_consent	Obsolète. Utilisez plutôt enable_granular_consent. Cela a le même effet que enable_granular_consent. Les applications existantes qui utilisent enable_serial_consent peuvent continuer à le faire, mais nous vous encourageons à mettre à jour votre code afin qu'il utilise enable_granular_consent lors de la prochaine mise à jour de votre application.
login_hint	Facultatif. Si votre application sait quel utilisateur doit autoriser la requête, elle peut utiliser cette propriété pour fournir à Google un indice de connexion. Si l'opération réussit, la sélection du compte est ignorée. Valeur du champ sub de l'adresse e-mail ou du jeton d'ID pour l'utilisateur cible. Pour en savoir plus, consultez la section concernant le champ login_hint dans la documentation OpenID Connect.
hd	Facultatif. Si votre application connaît le domaine Workspace auquel appartient l'utilisateur, utilisez ce champ pour fournir un indice à Google. Lorsque la requête aboutit, les comptes utilisateur sont limités ou présélectionnés pour le domaine fourni. Pour en savoir plus, consultez la section concernant le champ hd dans la documentation OpenID Connect.
ux_mode	Facultatif. Mode d'expérience utilisateur à utiliser pour le flux d'autorisation. Par défaut, le flux de consentement s'ouvre dans un pop-up. Les valeurs valides sont popup et redirect.
select_account	Facultatif : la valeur par défaut est 'false'. Valeur booléenne invitant l'utilisateur à sélectionner un compte.
error_callback	Facultatif. Fonction JavaScript qui gère certaines erreurs non OAuth, telles que l'échec de l'ouverture de la fenêtre pop-up ou l'ouverture d'une fenêtre pop-up, ou la fermeture avant qu'une réponse OAuth ne soit renvoyée. Le champ "type" du paramètre d'entrée indique le motif détaillé. popup_failed_to_open : la fenêtre pop-up ne s'ouvre pas. popup_closed la fenêtre pop-up est fermée avant le retour d'une réponse OAuth. unknown : espace réservé pour les autres erreurs.

Type de données: CodeClient

La classe ne comporte qu'une seule méthode publique requestCode, qui lance le flux d'expérience utilisateur du code OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

Type de données: CodeResponse

Un objet JavaScript CodeResponse sera transmis à la méthode callback dans l'expérience utilisateur pop-up. Dans l'expérience utilisateur de redirection, CodeResponse est transmis en tant que paramètre d'URL.

Le tableau suivant répertorie les propriétés du type de données CodeResponse.

Propriétés
code	Code d'autorisation d'une réponse de jeton réussie.
scope	Liste de champs d'application approuvés par l'utilisateur, séparés par un espace.
state	Valeur de chaîne utilisée par votre application pour maintenir l'état entre votre requête d'autorisation et la réponse.
error	Un seul code d'erreur ASCII.
error_description	Texte ASCII lisible fournissant des informations supplémentaires, permettant au développeur du client de comprendre l'erreur qui s'est produite.
error_uri	URI identifiant une page Web lisible avec des informations sur l'erreur, permettant de fournir au développeur client des informations supplémentaires sur l'erreur.

Méthode: google.accounts.oauth2.initTokenClient

La méthode initTokenClient initialise et renvoie un client de jeton, avec les configurations définies dans les paramètres.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

Type de données: TokenClientConfig

Le tableau suivant répertorie les propriétés du type de données TokenClientConfig.

Propriétés
client_id	Obligatoire. ID client de votre application. Vous trouverez cette valeur dans la console API.
callback	Obligatoire. Fonction JavaScript qui gère la réponse du jeton renvoyé.
scope	Obligatoire. Liste de champs d'application délimités par des espaces qui identifient les ressources auxquelles votre application pourrait accéder pour le compte de l'utilisateur. Ces valeurs déterminent l'écran de consentement que Google présente à l'utilisateur.
include_granted_scopes	Facultatif. Valeur par défaut : true. Permet aux applications d'utiliser une autorisation incrémentielle pour demander l'accès à des champs d'application supplémentaires en contexte. Si vous définissez la valeur de ce paramètre sur false et que la demande d'autorisation est accordée, le nouveau jeton d'accès ne couvrira que les champs d'application auxquels scope a été demandé dans ce TokenClientConfig.
prompt	(Facultatif) La valeur par défaut est 'select_account'. Liste d'invites à présenter à l'utilisateur, délimitées par des espaces et sensibles à la casse. Les valeurs possibles sont les suivantes : chaîne vide : l'utilisateur ne reçoit une invite que la première fois que votre application demande l'accès. Ne peut pas être spécifié avec d'autres valeurs. 'none' : aucun écran d'authentification ou de consentement n'est affiché. Ne doit pas être spécifié avec d'autres valeurs. 'consent' : invitent l'utilisateur à donner son consentement. 'select_account' : invitez l'utilisateur à sélectionner un compte.
enable_granular_consent	Facultatif. Valeur par défaut : true. Si ce paramètre est défini sur false, des autorisations plus précises sur le compte Google seront désactivées pour les ID client OAuth créés avant 2019. Si enable_granular_consent et enable_serial_consent sont tous les deux définis, seule la valeur enable_granular_consent sera prise en compte, et la valeur enable_serial_consent sera ignorée. Aucun effet pour les ID client OAuth les plus récents, car des autorisations plus précises sont toujours activées pour ces ID.
enable_serial_consent	Obsolète. Utilisez plutôt enable_granular_consent. Cela a le même effet que enable_granular_consent. Les applications existantes qui utilisent enable_serial_consent peuvent continuer à le faire, mais nous vous encourageons à mettre à jour votre code afin qu'il utilise enable_granular_consent lors de la prochaine mise à jour de votre application.
login_hint	Facultatif. Si votre application sait quel utilisateur doit autoriser la requête, elle peut utiliser cette propriété pour fournir à Google un indice de connexion. Si l'opération réussit, la sélection du compte est ignorée. Valeur du champ sub de l'adresse e-mail ou du jeton d'ID pour l'utilisateur cible. Pour en savoir plus, consultez la section concernant le champ login_hint dans la documentation OpenID Connect.
hd	Facultatif. Si votre application connaît le domaine Workspace auquel appartient l'utilisateur, utilisez ce champ pour fournir un indice à Google. Lorsque la requête aboutit, les comptes utilisateur sont limités ou présélectionnés pour le domaine fourni. Pour en savoir plus, consultez la section concernant le champ hd dans la documentation OpenID Connect.
state	Facultatif. Utilisation déconseillée Spécifie toute valeur de chaîne utilisée par votre application pour maintenir l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation.
error_callback	Facultatif. Fonction JavaScript qui gère certaines erreurs non OAuth, telles que l'échec de l'ouverture de la fenêtre pop-up ou l'ouverture d'une fenêtre pop-up, ou la fermeture avant qu'une réponse OAuth ne soit renvoyée. Le champ "type" du paramètre d'entrée indique le motif détaillé. popup_failed_to_open : la fenêtre pop-up ne s'ouvre pas. popup_closed la fenêtre pop-up est fermée avant le retour d'une réponse OAuth. unknown : espace réservé pour les autres erreurs.

Type de données: TokenClient

La classe ne comporte qu'une seule méthode publique requestAccessToken, qui lance le flux d'expérience utilisateur des jetons OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}

Arguments
overrideConfig	OverridableTokenClientConfig	Facultatif. Configurations à remplacer dans cette méthode.

Type de données: OverridableTokenClientConfig

Le tableau suivant répertorie les propriétés du type de données OverridableTokenClientConfig.

Propriétés
scope	Facultatif. Liste de champs d'application délimités par des espaces qui identifient les ressources auxquelles votre application pourrait accéder pour le compte de l'utilisateur. Ces valeurs déterminent l'écran de consentement que Google présente à l'utilisateur.
include_granted_scopes	Facultatif. Valeur par défaut : true. Permet aux applications d'utiliser une autorisation incrémentielle pour demander l'accès à des champs d'application supplémentaires en contexte. Si vous définissez la valeur de ce paramètre sur false et que la demande d'autorisation est accordée, le nouveau jeton d'accès ne couvrira que les champs d'application auxquels scope a été demandé dans ce OverridableTokenClientConfig.
prompt	Facultatif. Liste d'invites sensibles à la casse et délimitées par des espaces, devant être présentées à l'utilisateur.
enable_granular_consent	Facultatif. Valeur par défaut : true. Si ce paramètre est défini sur false, des autorisations plus précises sur le compte Google seront désactivées pour les ID client OAuth créés avant 2019.Si enable_granular_consent et enable_serial_consent sont tous les deux définis, seule la valeur enable_granular_consent sera appliquée, et la valeur enable_serial_consent sera ignorée. Aucun effet pour les ID client OAuth les plus récents, car des autorisations plus précises sont toujours activées pour ces ID.
enable_serial_consent	Obsolète. Utilisez plutôt enable_granular_consent. Cela a le même effet que enable_granular_consent. Les applications existantes qui utilisent enable_serial_consent peuvent continuer à le faire, mais nous vous encourageons à mettre à jour votre code afin qu'il utilise enable_granular_consent lors de la prochaine mise à jour de votre application.
login_hint	Facultatif. Si votre application sait quel utilisateur doit autoriser la requête, elle peut utiliser cette propriété pour fournir à Google un indice de connexion. Si l'opération réussit, la sélection du compte est ignorée. Valeur du champ sub de l'adresse e-mail ou du jeton d'ID pour l'utilisateur cible. Pour en savoir plus, consultez la section concernant le champ login_hint dans la documentation OpenID Connect.
state	Facultatif. Utilisation déconseillée Spécifie toute valeur de chaîne utilisée par votre application pour maintenir l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation.

Type de données: TokenResponse

Un objet JavaScript TokenResponse sera transmis à votre méthode de rappel dans l'expérience utilisateur pop-up.

Le tableau suivant répertorie les propriétés du type de données TokenResponse.

Propriétés
access_token	Jeton d'accès d'une réponse de jeton réussie.
expires_in	Durée de vie du jeton d'accès, en secondes.
hd	Domaine hébergé auquel appartient l'utilisateur connecté.
prompt	Valeur de l'invite utilisée dans la liste des valeurs possibles spécifiées par TokenClientConfig ou OverridableTokenClientConfig.
token_type	Type de jeton émis.
scope	Liste de champs d'application approuvés par l'utilisateur, séparés par un espace.
state	Valeur de chaîne utilisée par votre application pour maintenir l'état entre votre requête d'autorisation et la réponse.
error	Un seul code d'erreur ASCII.
error_description	Texte ASCII lisible fournissant des informations supplémentaires, permettant au développeur du client de comprendre l'erreur qui s'est produite.
error_uri	URI identifiant une page Web lisible avec des informations sur l'erreur, permettant de fournir au développeur client des informations supplémentaires sur l'erreur.

Méthode: google.accounts.oauth2.hasGrantedAllScopes

Vérifie si l'utilisateur a accordé tous les champs d'application spécifiés.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;

Arguments
tokenResponse	TokenResponse	Obligatoire. Un objet TokenResponse.
firstScope	chaîne	Obligatoire. Champ d'application à vérifier.
restScopes	chaîne[]	Facultatif. Autres champs d'application à vérifier.

Renvoie
boolean	"True" si tous les champs d'application sont autorisés.

Méthode: google.accounts.oauth2.hasGrantedAnyScope

Vérifie si l'utilisateur a accordé l'un des champs d'application spécifiés.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;

Arguments
tokenResponse	TokenResponse	Obligatoire. Un objet TokenResponse.
firstScope	chaîne	Obligatoire. Champ d'application à vérifier.
restScopes	chaîne[]	Facultatif. Autres champs d'application à vérifier.

Renvoie
boolean	"True" si l'un des champs d'application est accordé.

Méthode: google.accounts.oauth2.revoke

La méthode revoke révoque tous les niveaux d'accès que l'utilisateur a accordés à l'application. Un jeton d'accès valide est requis pour révoquer l'autorisation.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;

Arguments
accessToken	chaîne	Obligatoire. Un jeton d'accès valide.
callback	function	Facultatif. RevocationResponse.

Type de données: RevocationResponse

Un objet JavaScript RevocationResponse sera transmis à votre méthode de rappel.

Le tableau suivant répertorie les propriétés du type de données RevocationResponse.

Propriétés
successful	Valeur booléenne. true en cas d'échec, false en cas d'échec.
error	Chaîne. Le succès n'est pas défini. Un seul code d'erreur ASCII. Cela inclut, sans s'y limiter, les codes d'erreur OAuth 2.0 standards. Erreurs courantes pour la méthode revoke : invalid_token : le jeton a déjà expiré ou a été révoqué avant l'appel de la méthode revoke. Dans la plupart des cas, vous pouvez considérer que l'attribution associée à l'accessToken est révoquée. invalid_request : le jeton n'est pas révocable. Vous devez vous assurer que accessToken est un identifiant Google OAuth 2.0 valide.
error_description	Chaîne. Le succès n'est pas défini. Le texte ASCII lisible par l'humain fournit des informations supplémentaires sur la propriété error. Les développeurs peuvent l'utiliser pour mieux comprendre l'erreur qui s'est produite. La chaîne error_description est en anglais uniquement. Pour les erreurs courantes répertoriées dans error, le error_description correspondant : invalid_token : le jeton a expiré ou a été révoqué. invalid_request : le jeton n'est pas révocable.