Google-3P-Autorisierungs-JavaScript-Bibliothek für Websites – API-Referenz

In dieser Referenz wird die Google 3P Authorization JavaScript Library API beschrieben, mit der du Autorisierungscodes oder Zugriffstokens von Google laden kannst.

Methode: google.accounts.oauth2.initCodeClient

Die initCodeClient-Methode initialisiert und gibt einen Code-Client mit den Konfigurationen im Parameter zurück.

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

Datentyp: CodeClientConfig

In der folgenden Tabelle sind die Eigenschaften des Datentyps CodeClientConfig aufgeführt.

Attribute
client_id Erforderlich. Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API Console.
scope Erforderlich. Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte werden auf dem Zustimmungsbildschirm angezeigt, den Google dem Nutzer präsentiert.
include_granted_scopes Optional, Standardwert ist true. Ermöglicht es Anwendungen, mithilfe der schrittweisen Autorisierung den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf false festlegen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken nur die Bereiche ab, für die die scope in dieser CodeClientConfig angefordert wurde.
redirect_uri Erforderlich für die UX der Weiterleitung. Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem er den Autorisierungsvorgang abgeschlossen hat. Der Wert muss genau mit einem der autorisierten Weiterleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie in der API Console konfiguriert haben. Außerdem muss er unseren Gültigkeitsregeln für Weiterleitungs-URIs entsprechen. Das Attribut wird vom Pop-up-UX ignoriert.
callback Erforderlich für die Benutzeroberfläche von Pop-ups. Die JavaScript-Funktion, die die zurückgegebene Codeantwort verarbeitet. Die Property wird von der UX der Weiterleitung ignoriert.
state Optional. Empfohlen für die UX von Weiterleitungen. Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten.
enable_granular_consent Wird nicht mehr unterstützt und hat keine Auswirkungen, wenn sie festgelegt ist. Weitere Informationen zum Einwilligungsverhalten finden Sie unter Detaillierte Berechtigungen.
enable_serial_consent Wird nicht mehr unterstützt und hat keine Auswirkungen, wenn sie festgelegt ist. Weitere Informationen zum Einwilligungsverhalten finden Sie unter Detaillierte Berechtigungen.
login_hint Optional. Wenn Ihre Anwendung weiß, welcher Nutzer die Anfrage autorisieren soll, kann sie Google mithilfe dieser Property einen Anmeldehinweis geben. Bei Erfolg wird die Kontoauswahl übersprungen. Der Wert des Felds „E-Mail-Adresse“ oder „ID-Token“ sub für den Zielnutzer. Weitere Informationen finden Sie in der OpenID Connect-Dokumentation im Abschnitt zum Feld login_hint.
hd Optional. Wenn Ihre Anwendung die Workspace-Domain kennt, zu der der Nutzer gehört, können Sie Google damit einen Hinweis geben. Bei Erfolg werden Nutzerkonten auf die angegebene Domain beschränkt oder für diese Domain vorab ausgewählt. Weitere Informationen finden Sie in der OpenID Connect-Dokumentation im Abschnitt zum Feld hd.
ux_mode Optional. Der UX-Modus, der für den Autorisierungsablauf verwendet werden soll. Standardmäßig wird der Einwilligungsvorgang in einem Pop-up-Fenster geöffnet. Gültige Werte sind popup und redirect.
select_account Optional. Der Standardwert ist false. Boolescher Wert, um den Nutzer zum Auswählen eines Kontos aufzufordern.
error_callback Optional. Die JavaScript-Funktion, die einige nicht OAuth-Fehler verarbeitet, z. B. wenn das Pop-up-Fenster nicht geöffnet werden kann oder geschlossen wird, bevor eine OAuth-Antwort zurückgegeben wird.

Das Feld „type“ des Eingabeparameters enthält den detaillierten Grund.
  • popup_failed_to_open Das Pop-up-Fenster konnte nicht geöffnet werden.
  • popup_closed: Das Pop-up-Fenster wird geschlossen, bevor eine OAuth-Antwort zurückgegeben wird.
  • unknown: Platzhalter für andere Fehler.

Datentyp: CodeClient

Die Klasse hat nur eine öffentliche Methode, requestCode, mit der der OAuth 2.0-Code-UX-Vorgang gestartet wird.

interface CodeClient {
  requestCode(): void;
}

Datentyp: CodeResponse

Ein CodeResponse-JavaScript-Objekt wird in der Pop-up-UX an die callback-Methode übergeben. Bei der Weiterleitung werden die CodeResponse als URL-Parameter übergeben.

In der folgenden Tabelle sind die Eigenschaften des Datentyps CodeResponse aufgeführt.

Attribute
code Der Autorisierungscode einer erfolgreichen Tokenantwort.
scope Eine durch Leerzeichen getrennte Liste von Bereichen, die vom Nutzer genehmigt wurden.
state Der Stringwert, den Ihre Anwendung verwendet, um den Status zwischen der Autorisierungsanfrage und der Antwort beizubehalten.
error Ein einzelner ASCII-Fehlercode.
error_description Für Menschen lesbarer ASCII-Text mit zusätzlichen Informationen, der dem Cliententwickler hilft, den aufgetretenen Fehler zu verstehen.
error_uri Ein URI, der eine für Menschen lesbare Webseite mit Informationen zum Fehler angibt, um dem Cliententwickler zusätzliche Informationen zum Fehler zur Verfügung zu stellen.

Methode: google.accounts.oauth2.initTokenClient

Die Methode initTokenClient initialisiert und gibt einen Token-Client mit den Konfigurationen im Parameter zurück.

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

Datentyp: TokenClientConfig

In der folgenden Tabelle sind die Eigenschaften des Datentyps TokenClientConfig aufgeführt.

Attribute
client_id Erforderlich. Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API Console.
callback Erforderlich. Die JavaScript-Funktion, die die zurückgegebene Tokenantwort verarbeitet.
scope Erforderlich. Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte werden auf dem Zustimmungsbildschirm angezeigt, den Google dem Nutzer präsentiert.
include_granted_scopes Optional, Standardwert ist true. Ermöglicht es Anwendungen, mithilfe der schrittweisen Autorisierung den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf false festlegen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken nur die Bereiche ab, für die die scope in dieser TokenClientConfig angefordert wurde.
prompt Optional; Standardeinstellung: 'select_account'. Eine durch Leerzeichen getrennte Liste von Prompts, die dem Nutzer präsentiert werden sollen. Dabei wird zwischen Groß- und Kleinschreibung unterschieden. Mögliche Werte sind:
  • Leere Zeichenfolge: Der Nutzer wird nur zum ersten Mal aufgefordert, wenn Ihre App den Zugriff anfordert. Kann nicht mit anderen Werten angegeben werden.
  • „none“: Es werden keine Authentifizierungs- oder Einwilligungsbildschirme angezeigt. Darf nicht mit anderen Werten angegeben werden.
  • consent: Der Nutzer wird um seine Einwilligung gebeten.
  • 'select_account': Der Nutzer wird aufgefordert, ein Konto auszuwählen.
enable_granular_consent Wird nicht mehr unterstützt und hat keine Auswirkungen, wenn sie festgelegt ist. Weitere Informationen zum Einwilligungsverhalten finden Sie unter Detaillierte Berechtigungen.
enable_serial_consent Wird nicht mehr unterstützt und hat keine Auswirkungen, wenn sie festgelegt ist. Weitere Informationen zum Einwilligungsverhalten finden Sie unter Detaillierte Berechtigungen.
login_hint Optional. Wenn Ihre Anwendung weiß, welcher Nutzer die Anfrage autorisieren soll, kann sie Google mithilfe dieser Property einen Anmeldehinweis geben. Bei Erfolg wird die Kontoauswahl übersprungen. Der Wert des Felds „E-Mail-Adresse“ oder „ID-Token“ sub für den Zielnutzer. Weitere Informationen finden Sie in der OpenID Connect-Dokumentation im Abschnitt zum Feld login_hint.
hd Optional. Wenn Ihre Anwendung die Workspace-Domain kennt, zu der der Nutzer gehört, geben Sie dies an Google weiter. Bei Erfolg werden Nutzerkonten auf die angegebene Domain beschränkt oder für diese Domain vorab ausgewählt. Weitere Informationen finden Sie in der OpenID Connect-Dokumentation im Abschnitt zum Feld hd.
state Optional. Nicht empfohlen Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten.
error_callback Optional. Die JavaScript-Funktion, die einige nicht OAuth-Fehler verarbeitet, z. B. wenn das Pop-up-Fenster nicht geöffnet werden kann oder geschlossen wird, bevor eine OAuth-Antwort zurückgegeben wird.

Das Feld „type“ des Eingabeparameters gibt den detaillierten Grund an.
  • popup_failed_to_open Das Pop-up-Fenster konnte nicht geöffnet werden.
  • popup_closed: Das Pop-up-Fenster wird geschlossen, bevor eine OAuth-Antwort zurückgegeben wird.
  • unknown: Platzhalter für andere Fehler.

Datentyp: TokenClient

Die Klasse hat nur eine öffentliche Methode requestAccessToken, die den OAuth 2.0-Token-UX-Vorgang startet.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumente
overrideConfig OverridableTokenClientConfig Optional. Die Konfigurationen, die in dieser Methode überschrieben werden sollen.

Datentyp: OverridableTokenClientConfig

In der folgenden Tabelle sind die Eigenschaften des Datentyps OverridableTokenClientConfig aufgeführt.

Attribute
scope Optional. Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen angeben, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte fließen in den Zustimmungsbildschirm ein, der dem Nutzer von Google angezeigt wird.
include_granted_scopes Optional, Standardwert ist true. Ermöglicht es Anwendungen, mithilfe der schrittweisen Autorisierung den Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf false festlegen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken nur die Bereiche ab, für die die scope in dieser OverridableTokenClientConfig angefordert wurde.
prompt Optional. Eine durch Leerzeichen getrennte Liste von Prompts, die dem Nutzer präsentiert werden sollen. Dabei wird zwischen Groß- und Kleinschreibung unterschieden.
enable_granular_consent Wird nicht mehr unterstützt und hat keine Auswirkungen, wenn sie festgelegt ist. Weitere Informationen zum Einwilligungsverhalten finden Sie unter Detaillierte Berechtigungen.
enable_serial_consent Wird nicht mehr unterstützt und hat keine Auswirkungen, wenn sie festgelegt ist. Weitere Informationen zum Einwilligungsverhalten finden Sie unter Detaillierte Berechtigungen.
login_hint Optional. Wenn Ihre Anwendung weiß, welcher Nutzer die Anfrage autorisieren soll, kann sie Google mithilfe dieser Property einen Anmeldehinweis geben. Bei Erfolg wird die Kontoauswahl übersprungen. Der Wert des Felds „E-Mail-Adresse“ oder „ID-Token“ sub für den Zielnutzer. Weitere Informationen finden Sie in der OpenID Connect-Dokumentation im Abschnitt zum Feld login_hint.
state Optional. Nicht empfohlen Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten.

Datentyp: TokenResponse

Ein TokenResponse-JavaScript-Objekt wird in der Pop-up-UX an Ihre Callback-Methode übergeben.

In der folgenden Tabelle sind die Eigenschaften des Datentyps TokenResponse aufgeführt.

Attribute
access_token Das Zugriffstoken einer erfolgreichen Tokenantwort.
expires_in Die Lebensdauer des Zugriffstokens in Sekunden.
hd Die gehostete Domain, zu der der angemeldete Nutzer gehört.
prompt Der Prompt-Wert, der aus der Liste der möglichen Werte ausgewählt wurde, die in TokenClientConfig oder OverridableTokenClientConfig angegeben sind.
token_type Der Typ des ausgestellten Tokens.
scope Eine durch Leerzeichen getrennte Liste von Bereichen, die vom Nutzer genehmigt wurden.
state Der Stringwert, den Ihre Anwendung verwendet, um den Status zwischen der Autorisierungsanfrage und der Antwort beizubehalten.
error Ein einzelner ASCII-Fehlercode.
error_description Für Menschen lesbarer ASCII-Text mit zusätzlichen Informationen, der dem Cliententwickler hilft, den aufgetretenen Fehler zu verstehen.
error_uri Ein URI, der eine für Menschen lesbare Webseite mit Informationen zum Fehler angibt, um dem Cliententwickler zusätzliche Informationen zum Fehler zur Verfügung zu stellen.

Methode: google.accounts.oauth2.hasGrantedAllScopes

Prüft, ob der Nutzer alle angegebenen Bereiche gewährt hat.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Argumente
tokenResponse TokenResponse Erforderlich. Ein TokenResponse-Objekt.
firstScope String Erforderlich. Der zu prüfende Bereich.
restScopes String[] Optional. Andere Bereiche, die geprüft werden sollen.
Ausgabe
boolean „Wahr“, wenn alle Bereiche gewährt sind.

Methode: google.accounts.oauth2.hasGrantedAnyScope

Prüft, ob der Nutzer einen oder mehrere der angegebenen Bereiche gewährt hat.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Argumente
tokenResponse TokenResponse Erforderlich. Ein TokenResponse-Objekt.
firstScope String Erforderlich. Der zu prüfende Bereich.
restScopes String[] Optional. Andere Bereiche, die geprüft werden sollen.
Ausgabe
boolean „Wahr“, wenn einer der Bereiche gewährt wurde.

Methode: google.accounts.oauth2.revoke

Mit der revoke-Methode werden alle Bereiche widerrufen, die der Nutzer der App gewährt hat. Um die Berechtigung zu widerrufen, ist ein gültiges Zugriffstoken erforderlich.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Argumente
accessToken String Erforderlich. Ein gültiges Zugriffstoken.
callback Funktion Optional. Handler für RevocationResponse

Datentyp: Widerrufsantwort

Ein RevocationResponse-JavaScript-Objekt wird an Ihre Callback-Methode übergeben.

In der folgenden Tabelle sind die Eigenschaften des Datentyps RevocationResponse aufgeführt.

Attribute
successful Boolescher Wert. true für Erfolg, false für Fehler.
error String. Bei Erfolg nicht definiert. Ein einzelner ASCII-Fehlercode. Dazu gehören unter anderem die standardmäßigen OAuth 2.0-Fehlercodes. Häufige Fehler bei der revoke-Methode:
  • invalid_token – Das Token ist bereits abgelaufen oder widerrufen, bevor die Methode revoke aufgerufen wird. In den meisten Fällen können Sie davon ausgehen, dass die mit der accessToken verknüpfte Berechtigung widerrufen wurde.
  • invalid_request – Das Token kann nicht widerrufen werden. Achten Sie darauf, dass accessToken gültige Google OAuth 2.0-Anmeldedaten sind.
error_description String. Bei Erfolg nicht definiert. Der von Menschen lesbare ASCII-Text enthält zusätzliche Informationen zur Property error. So können Entwickler den aufgetretenen Fehler besser nachvollziehen. Der error_description-String ist nur auf Englisch verfügbar. Für die in error aufgeführten häufigen Fehler die entsprechenden error_description:
  • invalid_token: Das Token ist abgelaufen oder widerrufen.
  • invalid_request – Das Token kann nicht widerrufen werden.