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

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Le présent document de référence décrit l'API Bibliothèque JavaScript d'autorisation tierce 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 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 pouvez trouver cette valeur dans la console API.
scope Obligatoire. Liste de champs d'application, séparés par des espaces, qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs indiquent à l'écran d'autorisation que Google affiche à l'utilisateur.
include_granted_scopes Facultatif. La valeur par défaut est 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 pour lesquels le scope 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 que celui-ci a terminé le flux d'autorisation. La 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 d'API, et doit 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 au code renvoyé. La propriété sera ignorée par l'expérience utilisateur de redirection.
state Facultatif. Recommandé pour l'expérience utilisateur de redirection. Spécifie une valeur de chaîne que votre application utilise pour conserver l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation.
enable_serial_consent Facultatif. La valeur par défaut est true. 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 nouveaux ID client OAuth, car des autorisations plus précises sont toujours activées pour eux.
hint Facultatif. Si votre application sait quel utilisateur doit autoriser la requête, elle peut utiliser cette propriété pour fournir des indications à Google. Adresse e-mail de l'utilisateur cible. Pour en savoir plus, consultez le champ login_hint dans la documentation OpenID Connect.
hosted_domain Facultatif. Si votre application connaît le domaine Workspace auquel l'utilisateur appartient, utilisez-la pour fournir un indice à Google. 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. La valeur par défaut est 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'échec de l'ouverture de la fenêtre pop-up ou de la fermeture avant la réponse OAuth.

Le champ "type" du paramètre d'entrée indique le motif détaillé.
  • popup_failed_to_open : échec de l'ouverture de la fenêtre pop-up.
  • popup_closed : la fenêtre pop-up est fermée avant qu'une réponse OAuth soit renvoyée.
  • unknown : espace réservé pour d'autres erreurs.

Type de données: CodeClient

La classe ne comporte qu'une seule méthode public requestCode, qui démarre le parcours d'expérience utilisateur OAuth 2.0 Code.

interface CodeClient {
  requestCode(): void;
}

Type de données: CodeResponse

Un objet JavaScript CodeResponse sera transmis à votre méthode callback dans l'expérience utilisateur pop-up. Dans l'expérience 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ée par des espaces et approuvée 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 Code d'erreur ASCII unique.
error_description Texte ASCII lisible fournissant des informations supplémentaires, qui permet au développeur du client de comprendre l'erreur qui s'est produite.
error_uri URI qui identifie une page Web lisible avec des informations sur l'erreur, utilisée pour fournir au développeur du 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 pouvez trouver 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, séparés par des espaces, qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs indiquent à l'écran d'autorisation que Google affiche à l'utilisateur.
include_granted_scopes Facultatif. La valeur par défaut est 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 pour lesquels le scope demandé dans ce TokenClientConfig.
prompt Facultatif. La valeur par défaut est select_account. Liste d'invites séparées par des espaces et sensibles à la casse, présentées à l'utilisateur. Les valeurs possibles sont les suivantes :
  • chaîne vide : l'utilisateur ne sera invité que la première fois que votre application demandera l'accès. Ne peut pas être spécifié avec d'autres valeurs.
  • none : n'affiche aucun écran d'authentification ou d'autorisation. Ne doit pas être spécifié avec d'autres valeurs.
  • consent : invite l'utilisateur à donner son consentement.
  • 'select_account' : invitez l'utilisateur à sélectionner un compte.
enable_serial_consent Facultatif. La valeur par défaut est true. 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 nouveaux ID client OAuth, car des autorisations plus précises sont toujours activées pour eux.
hint Facultatif. Si votre application sait quel utilisateur doit autoriser la requête, elle peut utiliser cette propriété pour fournir des indications à Google. Adresse e-mail de l'utilisateur cible. Pour en savoir plus, consultez le champ login_hint dans la documentation OpenID Connect.
hosted_domain Facultatif. Si votre application connaît le domaine Workspace auquel l'utilisateur appartient, utilisez-la pour fournir un indice à Google. Pour en savoir plus, consultez le champ hd dans la documentation OpenID Connect.
state Facultatif. Utilisation déconseillée Spécifie une valeur de chaîne que votre application utilise 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'échec de l'ouverture de la fenêtre pop-up ou de la fermeture avant la réponse OAuth.

Le champ "type" du paramètre d'entrée indique le motif détaillé.
  • popup_failed_to_open : échec de l'ouverture de la fenêtre pop-up.
  • popup_closed : la fenêtre pop-up est fermée avant qu'une réponse OAuth soit renvoyée.
  • unknown : espace réservé pour d'autres erreurs.

Type de données: TokenClient

La classe ne comporte qu'une seule méthode publique requestAccessToken, qui démarre le parcours d'expérience utilisateur du jeton OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Arguments
overrideConfig Remplacement de clientClientConfig 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, séparés par des espaces, qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs indiquent à l'écran d'autorisation que Google affiche à l'utilisateur.
include_granted_scopes Facultatif. La valeur par défaut est 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 pour lesquels le scope demandé dans ce OverridableTokenClientConfig.
prompt Facultatif. Liste d'invites séparées par des espaces et sensibles à la casse, présentées à l'utilisateur.
enable_serial_consent Facultatif. La valeur par défaut est true. 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 nouveaux ID client OAuth, car des autorisations plus précises sont toujours activées pour eux.
hint Facultatif. Si votre application sait quel utilisateur doit autoriser la requête, elle peut utiliser cette propriété pour fournir des indications à Google. Adresse e-mail de 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 une valeur de chaîne que votre application utilise 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 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 en secondes du jeton d'accès.
hd Domaine hébergé auquel l'utilisateur connecté appartient.
prompt Valeur d'invite utilisée à partir de la liste des valeurs possibles de TokenClientConfig ou OverridableTokenClientConfig.
token_type Type de jeton émis.
scope Liste de champs d'application délimitée par des espaces et approuvée 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 Code d'erreur ASCII unique.
error_description Texte ASCII lisible fournissant des informations supplémentaires, qui permet au développeur du client de comprendre l'erreur qui s'est produite.
error_uri URI qui identifie une page Web lisible avec des informations sur l'erreur, utilisée pour fournir au développeur du 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
booléen Vraie si tous les champs d'application sont accordé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
booléen True si l'un des champs d'application est accordé.

Méthode: google.accounts.oauth2.revoke

La méthode revoke révoque tous les champs d'application que l'utilisateur a accordé à 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. Jeton d'accès valide.
done fonction Facultatif. Fonction de rappel une fois l'action de révocation terminée.