Wenn Sie die OAuth-basierte Verknüpfung mit „Optimiert“ für Google Log-in verwenden, wird Google Log-in zusätzlich zur OAuth-basierten Kontoverknüpfung verwendet. So können Google-Nutzer*innen sprachbasierte Verknüpfungen herstellen. Nutzer, die sich mit einer nicht von Google stammenden Identität bei Ihrem Dienst registriert haben, können diese Funktion aber nutzen.
Dieser Verknüpfungstyp beginnt mit Google Log-in. Damit kannst du prüfen, ob die Google-Profilinformationen des Nutzers in deinem System vorhanden sind. Wenn die Nutzerinformationen in Ihrem System nicht gefunden werden, wird ein Standard-OAuth-Ablauf gestartet. Der Nutzer kann auch ein neues Konto mit seinen Google-Profilinformationen erstellen.

Führen Sie die folgenden allgemeinen Schritte aus, um eine Kontoverknüpfung mit dem Typ „Optimierte Verknüpfung“ durchzuführen:
- Bitten Sie den Nutzer um seine Einwilligung für den Zugriff auf sein Google-Profil.
- Den Nutzer anhand der Angaben im Profil identifizieren
- Wenn Sie in Ihrem Authentifizierungssystem keine Übereinstimmung für den Google-Nutzer finden, wird der Vorgang fortgesetzt, je nachdem, ob Sie Ihr Actions-Projekt in der Actions Console so konfiguriert haben, dass das Erstellen von Nutzerkonten per Sprachbefehl oder nur auf Ihrer Website möglich ist.
- Wenn Sie die Kontoerstellung per Sprachbefehl zulassen, validieren Sie das von Google erhaltene ID-Token. Sie können dann einen Nutzer anhand der im ID-Token enthaltenen Profilinformationen erstellen.
- Wenn Sie die Kontoerstellung per Sprachbefehl nicht zulassen, wird der Nutzer zu einem Browser übertragen, über den er die Autorisierungsseite laden und den Vorgang für die Nutzererstellung abschließen kann.

Konten per Sprachbefehl erstellen
Wenn Sie die Erstellung von Nutzerkonten per Sprachbefehl zulassen, fragt Assistant den Nutzer, ob er Folgendes tun möchte:
- Ein neues Konto auf dem System mit den Google-Kontoinformationen erstellen oder
- Melden Sie sich mit einem anderen Konto bei Ihrem Authentifizierungssystem an, wenn es bereits ein Google-Konto gibt.
Wenn Sie die Reibung des Kontos möglichst gering halten möchten, empfehlen wir, die Kontoerstellung per Sprachbefehl zu erlauben. Der Nutzer muss den Sprachfluss nur verlassen, wenn er sich mit einem bestehenden Google-Konto anmelden möchte.
Kontoerstellung per Sprachbefehl nicht zulassen
Wenn Sie die Erstellung von Nutzerkonten per Sprachbefehl nicht erlaubt haben, öffnet Assistant die URL der Website, die Sie für die Nutzerauthentifizierung angegeben haben. Wenn die Interaktion auf einem Gerät ohne Bildschirm erfolgt, leitet Assistant den Nutzer auf ein Smartphone weiter, um die Kontoverknüpfung fortzusetzen.
Das ist in den folgenden Fällen empfehlenswert:
Sie möchten nicht zulassen, dass Nutzer, die keine Google-Konten haben, ein neues Nutzerkonto erstellen, und können stattdessen eine Verknüpfung mit den vorhandenen Nutzerkonten in Ihrem Authentifizierungssystem herstellen. Wenn Sie beispielsweise ein Treuepunkteprogramm anbieten, können Sie dafür sorgen, dass der Nutzer die Punkte verliert, die er in seinem bestehenden Konto gesammelt hat.
Sie müssen vollständige Kontrolle über den Vorgang bei der Kontoerstellung haben. Sie können sie beispielsweise verhindern, dass beim Erstellen des Kontos die Nutzungsbedingungen angezeigt werden.
OAuth-basierte Verknüpfung mit Google Log-in implementieren
Die Konten sind mit den branchenüblichen OAuth 2.0-Abläufen verknüpft. Actions on Google unterstützt den impliziten und den Autorisierungscode-Ablauf.
Im impliziten Codeablauf öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Nach erfolgreicher Anmeldung geben Sie ein langlebiges Zugriffstoken an Google zurück. Dieses Zugriffstoken ist jetzt in jeder Anfrage enthalten, die von Assistant an Ihre Aktion gesendet wird.
Für den Autorisierungscodeablauf benötigen Sie zwei Endpunkte:
- Der Endpunkt für die Autorisierung, der für die Darstellung der Anmelde-UI für Nutzer sorgt, die noch nicht angemeldet sind, und die Einwilligung zum angeforderten Zugriff in Form eines kurzlebigen Autorisierungscodes erfasst.
- Der Endpunkt Tokenaustausch, der für zwei Arten von Austauschen verantwortlich ist:
- Tauscht einen Autorisierungscode gegen ein langlebiges Aktualisierungstoken und ein kurzlebiges Zugriffstoken aus. Dieser Austausch erfolgt, wenn der Nutzer die Kontoverknüpfung durchläuft.
- Tauscht ein langlebiges Aktualisierungstoken gegen ein kurzlebiges Zugriffstoken aus. Dieser Austausch findet statt, wenn Google ein neues Zugriffstoken benötigt, weil das abgelaufene Token abgelaufen ist.
Der implizite Codeablauf ist zwar einfacher zu implementieren, aber Google empfiehlt, dass mit dem impliziten Vorgang ausgestellte Zugriffstokens nie ablaufen, da die Verwendung des Tokenablaufs mit dem impliziten Vorgang den Nutzer zwingt, sein Konto noch einmal zu verknüpfen. Wenn Sie aus Sicherheitsgründen ein Token auslaufen müssen, sollten Sie stattdessen den Autorisierungscode-Ablauf verwenden.
Projekt konfigurieren
So konfigurieren Sie Ihr Projekt für die optimierte Verknüpfung:
- Öffnen Sie die Actions Console und wählen Sie das gewünschte Projekt aus.
- Klicken Sie auf den Tab Entwickeln und wählen Sie Kontoverknüpfung aus.
- Aktivieren Sie den Schalter neben Kontoverknüpfung.
- Wählen Sie im Abschnitt Kontoerstellung die Option Ja aus.
Wählen Sie unter Verknüpfungstyp die Option OAuth & Google Log-in und Impliziert aus.
Gehen Sie unter Kundeninformationen so vor:
- Weisen Sie der von Ihren Actions to Google ausgestellten Client-ID einen Wert zu, um Anfragen von Google zu identifizieren.
- Fügen Sie die URLs für Ihre Autorisierungs- und Token Exchange-Endpunkte ein.
Klicken Sie auf Speichern.
OAuth-Server implementieren
Zur Unterstützung des impliziten OAuth 2.0-Vorgangs stellt Ihr Dienst einen HTTPS-Endpunkt zur Verfügung. Dieser Endpunkt ist dafür verantwortlich, die Nutzer für den Datenzugriff zu authentifizieren und die Einwilligung einzuholen. Der Autorisierungsendpunkt stellt Ihren Nutzern eine Anmelde-UI zur Verfügung, die noch nicht angemeldet sind. Außerdem wird die Einwilligung für den angeforderten Zugriff erfasst.
Wenn Ihre Aktion eine der autorisierten APIs Ihres Dienstes aufrufen muss, verwendet Google diesen Endpunkt, um die Berechtigung der Nutzer einzuholen, die APIs in ihrem Namen aufzurufen.
Eine typische von Google initiierte OAuth 2.0-Ablaufsitzung hat den folgenden Ablauf:
- Google öffnet den Autorisierungsendpunkt im Browser des Nutzers. Der Nutzer meldet sich an, wenn er nicht bereits angemeldet ist. Außerdem gewährt er Google mit Ihrer API die Berechtigung, auf seine Daten zuzugreifen, falls er es noch nicht getan hat.
- Der Dienst erstellt ein Zugriffstoken und leitet es an Google zurück. Dazu wird der Browser des Nutzers mit dem angehängten Zugriffstoken an Google zurückgesendet.
- Google ruft die APIs Ihres Dienstes auf und hängt mit jeder Anfrage das Zugriffstoken an. Ihr Dienst prüft, ob das Zugriffstoken Google die Berechtigung für den Zugriff auf die API gewährt, und schließt dann den API-Aufruf ab.
Autorisierungsanfragen verarbeiten
Wenn für Ihre Aktion eine Kontoverknüpfung über einen impliziten OAuth 2.0-Vorgang durchgeführt werden muss, sendet Google den Nutzer mit einer Anfrage, die die folgenden Parameter enthält, an Ihren Autorisierungsendpunkt:
Autorisierungsendpunktparameter | |
---|---|
client_id |
Die Client-ID, die Sie Google zugewiesen haben. |
redirect_uri |
Die URL, an die die Antwort auf diese Anfrage gesendet wird. |
state |
Ein Wert für die Buchführung, der im Weiterleitungs-URI unverändert an Google zurückgegeben wird. |
response_type |
Der Typ des Werts, der in der Antwort zurückgegeben werden soll. Beim impliziten OAuth 2.0-Vorgang ist der Antworttyp immer token . |
Wenn Ihr Autorisierungsendpunkt unter https://myservice.example.com/auth
verfügbar ist, könnte eine Anfrage so aussehen:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token
Gehen Sie so vor, damit der Autorisierungsendpunkt Anmeldeanfragen verarbeiten kann:
Überprüfen Sie die Werte
client_id
undredirect_uri
, um den Zugriff auf unbeabsichtigte oder falsch konfigurierte Client-Apps zu verhindern:- Prüfen Sie, ob
client_id
mit der Client-ID übereinstimmt, die Sie Google zugewiesen haben. - Prüfen Sie, ob die durch den Parameter
redirect_uri
angegebene URL das folgende Format hat:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID ist die ID, die auf der Seite Projekteinstellungen der Actions Console gefunden wurde.
- Prüfen Sie, ob
Prüfen Sie, ob der Nutzer in Ihrem Dienst angemeldet ist. Wenn der Nutzer nicht angemeldet ist: Schließe den Anmelde- oder Registrierungsvorgang für deinen Dienst ab.
Generieren Sie ein Zugriffstoken, das Google für den Zugriff auf Ihre API verwendet. Das Zugriffstoken kann ein beliebiger Stringwert sein. Es muss jedoch den Nutzer und den Client eindeutig repräsentieren und darf das Token nicht erraten.
Sende eine HTTP-Antwort, die den Browser des Nutzers an die durch den Parameter
redirect_uri
angegebene URL weiterleitet. Füge dem URL-Fragment alle folgenden Parameter hinzu:access_token
: das gerade generierte Zugriffstokentoken_type
: der Stringbearer
state
: der unveränderte Wert aus der ursprünglichen Anfrage. Unten sehen Sie ein Beispiel für die resultierende URL:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
Der OAuth 2.0-Weiterleitungs-Handler empfängt das Zugriffstoken und bestätigt, dass sich der state
-Wert nicht geändert hat. Nachdem Google ein Zugriffstoken für Ihren Dienst erhalten hat, hängt Google es im Rahmen des AppRequest an nachfolgende Aufrufe an Ihre Aktion an.
Umgang mit automatischer Verknüpfung
Nachdem der Nutzer deiner Aktion den Zugriff auf sein Google-Profil gewährt hat, sendet Google eine Anfrage mit einer signierten Zusicherung der Identität des Google-Nutzers. Die Assertion enthält Informationen, die die Google-Konto-ID, den Namen und die E-Mail-Adresse des Nutzers enthalten. Der für Ihr Projekt konfigurierte Endpunkt für den Tokenaustausch verarbeitet diese Anfrage.
Wenn das entsprechende Google-Konto bereits in Ihrem Authentifizierungssystem vorhanden ist, gibt der Tokenaustausch-Endpunkt ein Token für den Nutzer zurück. Wenn das Google-Konto nicht mit einem vorhandenen Nutzer übereinstimmt, gibt der Tokenaustausch-Endpunkt den Fehler user_not_found
zurück.
Die Anfrage hat folgendes Format:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&consent_code=CONSENT_CODE&scope=SCOPES
Der Tokenaustausch-Endpunkt muss die folgenden Parameter verarbeiten können:
Token-Endpunktparameter | |
---|---|
grant_type |
Der Typ des ausgetauschten Tokens. Für diese Anfragen hat dieser Parameter den Wert urn:ietf:params:oauth:grant-type:jwt-bearer . |
intent |
Bei diesen Anfragen lautet der Wert dieses Parameters „get“. |
assertion |
Ein JSON Web Token (JWT), das eine signierte Assertion der Identität des Google-Nutzers bereitstellt. Das JWT enthält Informationen wie die Google-Konto-ID, den Namen und die E-Mail-Adresse des Nutzers. |
consent_code |
Optional: Ein einmaliger Code, der angibt, dass der Nutzer eingewilligt hat, dass deine Aktion auf die angegebenen Bereiche zugreifen darf. |
scope |
Optional: Jeder Bereich, den Sie Google für Anfragen von Nutzern konfiguriert haben. |
Wenn der Endpunkt Ihrer Tokenaustausch die Verknüpfungsanfrage erhält, sollte er Folgendes tun:
JWT-Assertion validieren und decodieren
Sie können die JWT-Assertion mithilfe einer JWT-Decodierungsbibliothek für Ihre Sprache validieren und decodieren. Verwenden Sie die öffentlichen Schlüssel von Google (verfügbar im Format JWK oder PEM), um die Signatur des Tokens zu überprüfen.
Nach der Decodierung sieht die JWT-Assertion so aus:
{ "sub": 1234567890, // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "locale": "en_US" }
Prüfen Sie nicht nur die Signatur des Tokens, sondern auch, ob der Aussteller der Aufgabe (Feld iss
) https://accounts.google.com
ist. Außerdem muss die Zielgruppe (Feld aud
) die Client-ID sein, die Ihrer Aktion zugewiesen ist.
Prüfen, ob das Google-Konto bereits in Ihrem Authentifizierungssystem vorhanden ist
Prüfen Sie, ob eine der folgenden Bedingungen erfüllt ist:
- Die Google-Konto-ID, die im Feld
sub
der Erklärung aufgeführt ist, befindet sich in Ihrer Nutzerdatenbank. - Die E-Mail-Adresse in der Assertion stimmt mit einem Nutzer in Ihrer Nutzerdatenbank überein.
Wenn eine der beiden Bedingungen erfüllt ist, hat sich der Nutzer bereits registriert und Sie können ein Zugriffstoken ausstellen.
Wenn weder die Google-Konto-ID noch die in der Assertion angegebene E-Mail-Adresse mit einem Nutzer in Ihrer Datenbank übereinstimmt, hat sich der Nutzer noch nicht registriert. In diesem Fall sollte der Tokenaustausch-Endpunkt einen HTTP 401-Fehler zurückgeben, der error=user_not_found
angibt, wie im folgenden Beispiel:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"user_not_found", }Wenn Google die 401-Fehlerantwort mit dem Fehler
user_not_found
erhält, ruft Google deinen Endpunkt für den Tokenaustausch mit dem Wert des Parameters intent
auf, der auf create gesetzt ist. Er sendet ein ID-Token, das die Profilinformationen des Nutzers enthält.
Kontoerstellung über Google Log-in abwickeln
Wenn ein Nutzer ein Konto für Ihren Dienst erstellen muss, sendet Google eine Anfrage an Ihren Tokenaustausch-Endpunkt, die intent=create
angibt. Beispiel:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]
Der Parameter assertion
enthält ein JSON-Webtoken (JWT), das eine signierte Identität der Identität des Google-Nutzers bereitstellt. Das JWT enthält Informationen wie die Google-Konto-ID, den Namen und die E-Mail-Adresse des Nutzers, mit denen du ein neues Konto in deinem Dienst erstellen kannst.
Um auf Anfragen zur Kontoerstellung zu reagieren, muss der Tokenaustausch-Endpunkt die folgenden Schritte ausführen:
JWT-Assertion validieren und decodieren
Sie können die JWT-Assertion mithilfe einer JWT-Decodierungsbibliothek für Ihre Sprache validieren und decodieren. Verwenden Sie die öffentlichen Schlüssel von Google (verfügbar im Format JWK oder PEM), um die Signatur des Tokens zu überprüfen.
Nach der Decodierung sieht die JWT-Assertion so aus:
{ "sub": 1234567890, // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "locale": "en_US" }
Prüfen Sie nicht nur die Signatur des Tokens, sondern auch, ob der Aussteller der Aufgabe (Feld iss
) https://accounts.google.com
ist. Außerdem muss die Zielgruppe (Feld aud
) die Client-ID sein, die Ihrer Aktion zugewiesen ist.
Nutzerinformationen bestätigen und neues Konto erstellen
Prüfen Sie, ob eine der folgenden Bedingungen erfüllt ist:
- Die Google-Konto-ID, die im Feld
sub
der Erklärung aufgeführt ist, befindet sich in Ihrer Nutzerdatenbank. - Die E-Mail-Adresse in der Assertion stimmt mit einem Nutzer in Ihrer Nutzerdatenbank überein.
Wenn eine der beiden Bedingungen erfüllt ist, musst du den Nutzer bitten, sein Konto mit seinem Google-Konto zu verknüpfen. Antworte dazu auf die Anfrage mit dem HTTP-401-Fehler. Gib dabei error=linking_error
und die E-Mail-Adresse des Nutzers als login_hint
an, wie im folgenden Beispiel gezeigt:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
Wenn keine der beiden Bedingungen erfüllt ist, erstelle ein neues Nutzerkonto mithilfe der Informationen im JWT. Für neue Konten ist normalerweise kein Passwort festgelegt. Es wird empfohlen, dass Sie Google Log-in anderen Plattformen hinzufügen, damit sich Nutzer auf den Oberflächen Ihrer Anwendung über Google anmelden können. Alternativ können Sie dem Nutzer per E-Mail einen Link senden, über den der Passwortwiederherstellungsvorgang gestartet wird. So kann er ein Passwort für die Anmeldung auf anderen Plattformen festlegen.
Geben Sie nach Abschluss der Erstellung ein Zugriffstoken an Geben Sie dann die Werte in einem JSON-Objekt im Text Ihrer HTTPS-Antwort zurück, wie im folgenden Beispiel gezeigt:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Sprachbenutzeroberfläche für den Authentifizierungsvorgang entwickeln
Prüfe, ob der Nutzer bestätigt ist, und starte die Kontoverknüpfung
- Öffnen Sie das Actions Builder-Projekt in der Actions Console.
- Erstellen Sie eine neue Szene, um die Kontoverknüpfung in Ihrer Aktion zu starten:
- Klicken Sie auf Szenen.
- Klicke auf das Symbol Hinzufügen +, um eine neue Szene hinzuzufügen.
- Klicken Sie in der neu erstellten Szene auf das Symbol add für Bedingungen.
- Fügen Sie eine Bedingung hinzu, die prüft, ob der mit der Unterhaltung verknüpfte Nutzer ein bestätigter Nutzer ist. Wenn die Prüfung fehlschlägt, kann deine Aktion während der Unterhaltung keine Kontoverknüpfung durchführen. Sie sollte wieder auf Funktionen zugreifen, für die keine Kontoverknüpfung erforderlich ist.
- Geben Sie im Feld
Enter new expression
unter Bedingung die folgende Logik ein:user.verificationStatus != "VERIFIED"
- Wählen Sie unter Übergang eine Szene aus, für die keine Kontoverknüpfung erforderlich ist, oder eine Szene, die der Einstiegspunkt für Funktionen nur für Gäste ist.
- Geben Sie im Feld
- Klicken Sie auf das Symbol add für Bedingungen.
- Fügen Sie eine Bedingung hinzu, die einen Kontoverknüpfungsvorgang auslöst, wenn der Nutzer keine verknüpfte Identität hat.
- Geben Sie im Feld
Enter new expression
unter Bedingung die folgende Logik ein:user.verificationStatus == "VERIFIED"
- Wählen Sie unter Umstellung die Systemszene Kontoverknüpfung aus.
- Klicken Sie auf Speichern.
- Geben Sie im Feld
Nach dem Speichern wird Ihrem Projekt die neue Systemverknüpfung <SceneName>_AccountLinking
hinzugefügt.
Kontoverknüpfungsszene anpassen
- Wählen Sie unter Szenen die Szene für das System zur Kontoverknüpfung aus.
- Klicken Sie auf Aufforderung senden und fügen Sie einen kurzen Satz hinzu, um dem Nutzer zu erklären, warum die Aktion auf seine Identität zugreifen muss (z. B. zum Speichern Ihrer Einstellungen).
- Klicken Sie auf Speichern.
- Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung abgeschlossen hat.
- Konfigurieren Sie, wie der Ablauf ausgeführt werden soll, wenn der Nutzer der Verknüpfung seines Kontos zustimmt. Sie können beispielsweise den Webhook aufrufen, um die erforderliche benutzerdefinierte Geschäftslogik zu verarbeiten und zur ursprünglichen Szene zurückzukehren.
- Klicken Sie auf Speichern.
- Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung aufhebt oder schließt.
- Konfigurieren Sie die Vorgehensweise, wenn der Nutzer nicht mit der Kontoverknüpfung einverstanden ist. Senden Sie beispielsweise eine Bestätigungsnachricht und leiten Sie zu Szenen weiter, die Funktionen erfordern, die keine Kontoverknüpfung erfordern.
- Klicken Sie auf Speichern.
- Klicken Sie unter Bedingungen auf Wenn ein System- oder Netzwerkfehler auftritt.
- Konfigurieren Sie, wie der Vorgang fortgesetzt werden soll, wenn die Kontoverknüpfung aufgrund von System- oder Netzwerkfehlern nicht abgeschlossen werden kann. Senden Sie beispielsweise eine Bestätigungsnachricht und leiten Sie zu Szenen weiter, die Funktionen erfordern, die keine Kontoverknüpfung erfordern.
- Klicken Sie auf Speichern.
Anfragen für den Datenzugriff verarbeiten
Wenn die Assistant-Anfrage ein Zugriffstoken enthält, prüfen Sie zuerst, ob es gültig ist und nicht abgelaufen ist. Rufen Sie dann das mit dem Token verknüpfte Nutzerkonto aus Ihrer Nutzerkontodatenbank ab.