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

Ce document de référence décrit l'API de la bibliothèque JavaScript JavaScript de Google, que vous pouvez utiliser pour charger des codes d'autorisation ou des jetons d'accès depuis Google.

Méthode: google.accounts.oauth2.initCodeClient

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

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 peut accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google affiche à l'utilisateur.
include_granted_scopes Facultatif. Valeur par défaut : true. Permet aux applications d'utiliser l'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 pour lesquels le scope est demandé dans ce CodeClientConfig.
redirect_uri Obligatoire pour l'expérience de redirection. Détermine où le serveur d'API redirige l'utilisateur une fois qu'il 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. Elle doit aussi respecter nos règles de validation de l'URI de redirection. La propriété sera ignorée par l'expérience utilisateur pop-up.
callback Obligatoire pour l'expérience utilisateur pop-up. Fonction JavaScript qui gère la réponse de code renvoyée. La propriété sera ignorée par l'expérience de redirection.
state Facultatif. Recommandé pour l'expérience de redirection. Spécifie toute valeur de chaîne utilisée par votre application pour conserver 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 la valeur est false, les autorisations de compte Google plus précises sont désactivées pour les ID client OAuth créés avant 2019. Si enable_granular_consent et enable_serial_consent sont tous 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 plus récents, car les autorisations sont toujours plus précises.
enable_serial_consent Obsolète. Utilisez enable_granular_consent à la place. Cela a le même effet que enable_granular_consent. Les applications existantes qui utilisent enable_serial_consent peuvent continuer à le faire, mais vous êtes invité à mettre à jour votre code afin d'utiliser enable_granular_consent lors de votre prochaine mise à jour d'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 de comptes est ignorée. Valeur du champ sub pour l'adresse e-mail ou le jeton d'ID pour l'utilisateur cible. Pour en savoir plus, consultez le champ login_hint dans la documentation OpenID Connect.
hd Facultatif. Si votre application connaît le domaine Workspace auquel appartient l'utilisateur, utilisez-la pour fournir des indications à Google. Si l'opération réussit, les comptes utilisateur sont limités ou présélectionnés pour le domaine fourni. Pour en savoir plus, consultez 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 une fenêtre pop-up. Les valeurs valides sont popup et redirect.
select_account Facultatif. Valeur par défaut : false. Valeur booléenne invitant l'utilisateur à sélectionner un compte.
error_callback Facultatif. La fonction JavaScript qui gère certaines erreurs non OAuth, telles que l'ouverture, ou la fermeture de la fenêtre pop-up, avant la réponse OAuth.

Le champ "type" du paramètre d'entrée indique la raison détaillée.
  • popup_failed_to_open : la fenêtre pop-up ne s'est pas ouverte.
  • popup_closed La fenêtre pop-up est fermée avant le renvoi d'une réponse OAuth.
  • unknown l'espace réservé pour d'autres erreurs.

Type de données: CodeClient

La classe ne comporte qu'un seul code public requestCode, qui démarre le parcours d'expérience utilisateur Code 2.0.

interface CodeClient {
  requestCode(): void;
}

Type de données: CodeResponse

Un objet JavaScript CodeResponse est transmis à votre méthode callback dans l'expérience utilisateur pop-up. Dans l'expérience utilisateur de redirection, CodeResponse est transmis en tant que paramètres 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 délimités par des espaces approuvés par l'utilisateur.
state Valeur de chaîne utilisée par votre application pour conserver 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 pour aider le développeur du client à comprendre l'erreur qui s'est produite.
error_uri URI identifiant une page Web lisible avec des informations sur l'erreur, utilisée pour 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 dans le paramètre.

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 de jeton renvoyée.
scope Obligatoire. Liste de champs d'application délimités par des espaces, qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google affiche à l'utilisateur.
include_granted_scopes Facultatif. Valeur par défaut : true. Permet aux applications d'utiliser l'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 pour lesquels le scope est demandé dans ce TokenClientConfig.
prompt Facultatif. Valeur par défaut : 'select_account'. Liste d'invites sensibles à la casse et délimitées par des espaces, pour présenter l'utilisateur. Les valeurs possibles sont les suivantes :
  • chaîne vide : l'utilisateur n'est invité qu'à la première demande d'accès à votre application. Ne peut pas être spécifié avec d'autres valeurs.
  • 'none' : n'affiche aucun écran d'authentification ou de consentement. Ne doit pas être spécifié avec d'autres valeurs.
  • "consent" : demande le consentement de l'utilisateur.
  • 'select_account' : invitez l'utilisateur à sélectionner un compte.
enable_granular_consent Facultatif. Valeur par défaut : true. Si la valeur est false, les autorisations de compte Google plus précises sont désactivées pour les ID client OAuth créés avant 2019. Si enable_granular_consent et enable_serial_consent sont tous 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 plus récents, car les autorisations sont toujours plus précises.
enable_serial_consent Obsolète. Utilisez enable_granular_consent à la place. Cela a le même effet que enable_granular_consent. Les applications existantes qui utilisent enable_serial_consent peuvent continuer à le faire, mais vous êtes invité à mettre à jour votre code afin d'utiliser enable_granular_consent lors de votre prochaine mise à jour d'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 de comptes est ignorée. Valeur du champ sub pour l'adresse e-mail ou le jeton d'ID pour l'utilisateur cible. Pour en savoir plus, consultez le champ login_hint dans la documentation OpenID Connect.
hd Facultatif. Si votre application connaît le domaine Workspace auquel appartient l'utilisateur, utilisez-la pour fournir des indications à Google. Si l'opération réussit, les comptes utilisateur sont limités ou présélectionnés pour le domaine fourni. Pour en savoir plus, consultez 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 conserver l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation.
error_callback Facultatif. La fonction JavaScript qui gère certaines erreurs non OAuth, telles que l'ouverture, ou la fermeture de la fenêtre pop-up, avant la réponse OAuth.

Le champ "type" du paramètre d'entrée indique la raison détaillée.
  • popup_failed_to_open : la fenêtre pop-up ne s'est pas ouverte.
  • popup_closed La fenêtre pop-up est fermée avant le renvoi d'une réponse OAuth.
  • unknown l'espace réservé pour d'autres erreurs.

Type de données: TokenClient

La classe ne comporte qu'une seule méthode publique requestAccessToken, qui lance le parcours d'expérience utilisateur du jeton 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 peut accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google affiche à l'utilisateur.
include_granted_scopes Facultatif. Valeur par défaut : true. Permet aux applications d'utiliser l'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 pour lesquels le scope est demandé dans ce OverridableTokenClientConfig.
prompt Facultatif. Liste d'invites sensibles à la casse et délimitées par des espaces, pour présenter l'utilisateur.
enable_granular_consent Facultatif. Valeur par défaut : true. Si la valeur est false, les autorisations de compte Google plus précises sont désactivées pour les ID client OAuth créés avant 2019.Si enable_granular_consent et enable_serial_consent sont tous deux définis, seule la valeur enable_granular_consent prend effet et la valeur enable_serial_consent est ignorée.

Aucun effet pour les ID client OAuth plus récents, car les autorisations sont toujours plus précises.
enable_serial_consent Obsolète. Utilisez enable_granular_consent à la place. Cela a le même effet que enable_granular_consent. Les applications existantes qui utilisent enable_serial_consent peuvent continuer à le faire, mais vous êtes invité à mettre à jour votre code afin d'utiliser enable_granular_consent lors de votre prochaine mise à jour d'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 de comptes est ignorée. Valeur du champ sub pour l'adresse e-mail ou le jeton d'ID pour l'utilisateur cible. Pour en savoir plus, consultez 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 conserver 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 est 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 en secondes du jeton d'accès.
hd Domaine hébergé auquel l'utilisateur connecté appartient.
prompt Valeur d'invite utilisée dans la liste possible de valeurs spécifiées par TokenClientConfig ou OverridableTokenClientConfig.
token_type Type de jeton émis.
scope Liste de champs d'application délimités par des espaces approuvés par l'utilisateur.
state Valeur de chaîne utilisée par votre application pour conserver 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 pour aider le développeur client à comprendre l'erreur qui s'est produite.
error_uri URI identifiant une page Web lisible avec des informations sur l'erreur, utilisée pour 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é le ou 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 string Obligatoire. Champ d'application à vérifier.
restScopes chaîne[] Facultatif. Autres champs d'application à vérifier.
Renvoie
booléen Critère : 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 string Obligatoire. Champ d'application à vérifier.
restScopes chaîne[] Facultatif. Autres champs d'application à vérifier.
Renvoie
booléen True si des champs d'application sont autorisés.

Méthode: google.accounts.oauth2.revoke

La méthode revoke révoque tous les champs d'application 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 string Obligatoire. Un jeton d'accès valide.
callback function Facultatif. Gestionnaire 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 de réussite, false en cas d'échec.
error Chaîne. Non défini en cas de réussite. 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 révoqué avant l'appel de la méthode revoke. Dans la plupart des cas, vous pouvez considérer que l'autorisation associée à accessToken est révoquée.
  • invalid_request : le jeton n'est pas révocable. Assurez-vous que accessToken est un identifiant Google OAuth 2.0 valide.
error_description Chaîne. Non défini en cas de réussite. Le texte ASCII lisible 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 n'est disponible qu'en anglais. Pour les erreurs courantes listé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.