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

In dieser Referenz wird die Google 3P Authorization JavaScript Library API beschrieben, mit der Sie Autorisierungscodes oder Zugriffstokens von Google laden können.

Methode: google.accounts.oauth2.initCodeClient

Die Methode initCodeClient initialisiert und gibt einen Codeclient zurück, der die Konfigurationen im Parameter enthält.

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

Datentyp: CodeClientConfig

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

Attribute
client_id Erforderlich. Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API-Konsole.
scope Erforderlich. Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.
include_granted_scopes Optional, der Standardwert ist true. Ermöglicht Anwendungen, die inkrementelle Autorisierung zu verwenden, um Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf false setzen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken nur Bereiche ab, für die der scope in diesem CodeClientConfig angefordert hat.
redirect_uri Erforderlich für die Weiterleitung. Bestimmt, wohin der API-Server den Nutzer weiterleitet, nachdem der Nutzer 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. Er muss außerdem unseren Validierungsregeln für Weiterleitungs-URIs entsprechen. Die Eigenschaft wird von der Pop-up-Benutzeroberfläche ignoriert.
callback Erforderlich für Pop-up-UX. Die JavaScript-Funktion, die die zurückgegebene Codeantwort verarbeitet. Die Eigenschaft wird von der Weiterleitung ignoriert.
state Optional. Empfohlen für die Weiterleitung. Gibt einen beliebigen Stringwert an, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort des Autorisierungsservers aufrechtzuerhalten.
enable_granular_consent Optional, der Standardwert ist true. Durch die Einstellung false werden detailliertere Berechtigungen für Google-Konten für OAuth-Client-IDs deaktiviert, die vor 2019 erstellt wurden. Wenn sowohl enable_granular_consent als auch enable_serial_consent festgelegt sind, wird nur der Wert enable_granular_consent wirksam und der Wert enable_serial_consent wird ignoriert.

Keine Auswirkungen auf neuere OAuth-Client-IDs, da für sie immer detailliertere Berechtigungen aktiviert sind.
enable_serial_consent Eingestellt. Verwende stattdessen enable_granular_consent. Dies hat denselben Effekt wie enable_granular_consent. Vorhandene Anwendungen, die enable_serial_consent verwenden, können dies weiterhin tun. Sie sollten Ihren Code jedoch bei Ihrem nächsten Anwendungsupdate so aktualisieren, dass enable_granular_consent verwendet wird.
login_hint Optional. Wenn Ihre Anwendung weiß, welcher Nutzer die Anfrage autorisieren soll, kann sie mithilfe dieser Eigenschaft einen Anmeldehinweis an Google senden. Wenn der Vorgang erfolgreich war, wird die Kontoauswahl übersprungen. Der Wert im Feld sub der E-Mail-Adresse oder des ID-Tokens für den Zielnutzer. Weitere Informationen finden Sie in der Dokumentation zu OpenID Connect im Feld login_hint.
hd Optional. Wenn Ihre Anwendung die Workspace-Domain kennt, zu der der Nutzer gehört, können Sie damit Google einen Hinweis geben. Wenn der Vorgang erfolgreich ist, werden Nutzerkonten auf die angegebene Domain beschränkt oder vorab ausgewählt. Weitere Informationen finden Sie in der Dokumentation zu OpenID Connect im Feld hd.
ux_mode Optional. Der für den Autorisierungsablauf zu verwendende UX-Modus. 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, der den Nutzer zur Auswahl eines Kontos auffordert.
error_callback Optional. Die JavaScript-Funktion, die einige Nicht-OAuth-Fehler verarbeitet, z. B. dass das Pop-up-Fenster nicht geöffnet oder geschlossen wird, bevor eine OAuth-Antwort zurückgegeben wird.

Der genaue Grund wird im Feld „type“ des Eingabeparameters angegeben.
  • 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-Ablauf gestartet wird.

interface CodeClient {
  requestCode(): void;
}

Datentyp: CodeResponse

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

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

Attribute
code Der Autorisierungscode einer erfolgreichen Tokenantwort.
scope Eine durch Leerzeichen getrennte Liste der Bereiche, die vom Nutzer genehmigt wurden.
state Der Stringwert, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort aufrechtzuerhalten.
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 identifiziert. Er wird verwendet, um dem Cliententwickler zusätzliche Informationen zum Fehler bereitzustellen.

Methode: google.accounts.oauth2.initTokenClient

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

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

Datentyp: TokenClientConfig

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

Attribute
client_id Erforderlich. Die Client-ID für Ihre Anwendung. Sie finden diesen Wert in der API-Konsole.
callback Erforderlich. Die JavaScript-Funktion, die die zurückgegebene Tokenantwort verarbeitet.
scope Erforderlich. Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.
include_granted_scopes Optional, der Standardwert ist true. Ermöglicht Anwendungen, die inkrementelle Autorisierung zu verwenden, um Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf false setzen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken nur Bereiche ab, für die der scope in diesem TokenClientConfig angefordert hat.
prompt Optional; der Standardwert ist 'select_account'. Eine Liste von Eingabeaufforderungen, die durch Leerzeichen getrennt sind und auf die Groß- und Kleinschreibung achten müssen. Mögliche Werte sind:
  • Leerer String Der Nutzer wird nur dann aufgefordert, wenn Ihre Anwendung zum ersten Mal Zugriff anfordert. Kann nicht mit anderen Werten angegeben werden.
  • 'none': Es werden keine Authentifizierungs- oder Zustimmungsbildschirme angezeigt. Darf nicht mit anderen Werten angegeben werden.
  • 'consent': Der Nutzer wird um seine Einwilligung gebeten.
  • 'select_account': Fordere den Nutzer auf, ein Konto auszuwählen.
enable_granular_consent Optional, der Standardwert ist true. Durch die Einstellung false werden detailliertere Berechtigungen für Google-Konten für OAuth-Client-IDs deaktiviert, die vor 2019 erstellt wurden. Wenn sowohl enable_granular_consent als auch enable_serial_consent festgelegt sind, wird nur der Wert enable_granular_consent wirksam und der Wert enable_serial_consent wird ignoriert.

Keine Auswirkungen auf neuere OAuth-Client-IDs, da für sie immer detailliertere Berechtigungen aktiviert sind.
enable_serial_consent Eingestellt. Verwende stattdessen enable_granular_consent. Dies hat denselben Effekt wie enable_granular_consent. Vorhandene Anwendungen, die enable_serial_consent verwenden, können dies weiterhin tun. Sie sollten Ihren Code jedoch bei Ihrem nächsten Anwendungsupdate so aktualisieren, dass enable_granular_consent verwendet wird.
login_hint Optional. Wenn Ihre Anwendung weiß, welcher Nutzer die Anfrage autorisieren soll, kann sie mithilfe dieser Eigenschaft einen Anmeldehinweis an Google senden. Wenn der Vorgang erfolgreich war, wird die Kontoauswahl übersprungen. Der Wert im Feld sub der E-Mail-Adresse oder des ID-Tokens für den Zielnutzer. Weitere Informationen finden Sie in der Dokumentation zu OpenID Connect im Feld login_hint.
hd Optional. Wenn Ihre Anwendung die Workspace-Domain kennt, zu der der Nutzer gehört, können Sie damit Google einen Hinweis geben. Wenn der Vorgang erfolgreich ist, werden Nutzerkonten auf die angegebene Domain beschränkt oder vorab ausgewählt. Weitere Informationen finden Sie in der Dokumentation zu OpenID Connect im 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. dass das Pop-up-Fenster nicht geöffnet oder geschlossen wird, bevor eine OAuth-Antwort zurückgegeben wird.

Der genaue Grund wird im Feld „type“ des Eingabeparameters angegeben.
  • 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 requestAccessToken-Methode, mit der der UX-Vorgang für OAuth 2.0-Tokens gestartet wird.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumente
overrideConfig OverridableTokenClientConfig Optional. Die in dieser Methode zu überschreibenden Konfigurationen.

Datentyp: OverridableTokenClientConfig

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

Attribute
scope Optional. Eine durch Leerzeichen getrennte Liste von Bereichen, die die Ressourcen identifizieren, auf die Ihre Anwendung im Namen des Nutzers zugreifen kann. Diese Werte beziehen sich auf den Zustimmungsbildschirm, den Google dem Nutzer anzeigt.
include_granted_scopes Optional, der Standardwert ist true. Ermöglicht Anwendungen, die inkrementelle Autorisierung zu verwenden, um Zugriff auf zusätzliche Bereiche im Kontext anzufordern. Wenn Sie den Wert dieses Parameters auf false setzen und die Autorisierungsanfrage gewährt wird, deckt das neue Zugriffstoken nur Bereiche ab, für die der scope in diesem OverridableTokenClientConfig angefordert hat.
prompt Optional. Eine Liste mit durch Leerzeichen voneinander getrennten Aufforderungen für den Nutzer. Beachten Sie dabei die Groß- und Kleinschreibung.
enable_granular_consent Optional, der Standardwert ist true. Wenn false festgelegt ist, werden detailliertere Google-Kontoberechtigungen für OAuth-Client-IDs deaktiviert, die vor 2019 erstellt wurden.Wenn sowohl enable_granular_consent als auch enable_serial_consent festgelegt sind, wird nur der Wert enable_granular_consent wirksam und der Wert enable_serial_consent ignoriert.

Keine Auswirkungen auf neuere OAuth-Client-IDs, da für sie immer detailliertere Berechtigungen aktiviert sind.
enable_serial_consent Eingestellt. Verwende stattdessen enable_granular_consent. Dies hat denselben Effekt wie enable_granular_consent. Vorhandene Anwendungen, die enable_serial_consent verwenden, können dies weiterhin tun. Sie sollten Ihren Code jedoch bei Ihrem nächsten Anwendungsupdate so aktualisieren, dass enable_granular_consent verwendet wird.
login_hint Optional. Wenn Ihre Anwendung weiß, welcher Nutzer die Anfrage autorisieren soll, kann sie mithilfe dieser Eigenschaft einen Anmeldehinweis an Google senden. Wenn der Vorgang erfolgreich war, wird die Kontoauswahl übersprungen. Der Wert im Feld sub der E-Mail-Adresse oder des ID-Tokens für den Zielnutzer. Weitere Informationen finden Sie in der Dokumentation zu OpenID Connect im 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 an Ihre Callback-Methode im Pop-up-Fenster übergeben.

In der folgenden Tabelle sind die Attribute 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 Eingabeaufforderungswert, der aus der möglichen Liste von Werten verwendet wurde, die von TokenClientConfig oder OverridableTokenClientConfig angegeben wurde.
token_type Der Typ des ausgestellten Tokens.
scope Eine durch Leerzeichen getrennte Liste der Bereiche, die vom Nutzer genehmigt wurden.
state Der Stringwert, den Ihre Anwendung verwendet, um den Status zwischen Ihrer Autorisierungsanfrage und der Antwort aufrechtzuerhalten.
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 identifiziert. Er wird verwendet, um dem Cliententwickler zusätzliche Informationen zum Fehler bereitzustellen.

Methode: google.accounts.oauth2.hasGrantedAllScopes

Überprü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 zu prüfende Bereiche.
Rückgaben
boolean „True“, wenn alle Bereiche gewährt wurden.

Methode: google.accounts.oauth2.hasGrantedAnyScope

Überprü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 zu prüfende Bereiche.
Rückgaben
boolean „True“, wenn einer der Bereiche gewährt wurde.

Methode: google.accounts.oauth2.revoke

Mit der Methode revoke werden alle Bereiche widerrufen, die der Nutzer der Anwendung gewährt hat. Zum Widerrufen der Berechtigung 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. RevocationResponse-Handler zurück.

Datentyp: RevocationResponse

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

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

Attribute
successful Boolescher Wert. true bei erfolgreich, false bei Fehler.
error String. Bei Erfolg nicht definiert. Ein einzelner ASCII-Fehlercode. Dazu zählen unter anderem die OAuth 2.0-Standardfehlercodes. Häufige Fehler für die Methode revoke:
  • invalid_token: Das Token ist bereits abgelaufen oder wurde widerrufen, bevor die Methode revoke aufgerufen wird. In den meisten Fällen können Sie davon ausgehen, dass die mit der accessToken verknüpfte Erteilung widerrufen wird.
  • invalid_request: Das Token kann nicht widerrufen werden. Achten Sie darauf, dass accessToken gültige Anmeldedaten für Google OAuth 2.0 ist.
error_description String. Bei Erfolg nicht definiert. Für Menschen lesbarer ASCII-Text finden Sie zusätzliche Informationen zum Attribut error. Anhand dieser Informationen können Entwickler den aufgetretenen Fehler besser nachvollziehen. Der String error_description ist nur auf Englisch verfügbar. Für die häufigen Fehler, die in error aufgeführt sind, die entsprechende error_description:
  • invalid_token: Das Token ist abgelaufen oder wurde widerrufen.
  • invalid_request: Das Token kann nicht widerrufen werden.