Konzeptleitfaden für die OAuth-basierte Google Log-in-Verknüpfung

Der OAuth-basierte Verknüpfungstyp „Optimierte“ Google Log-in fügt Google Log-in zusätzlich zur OAuth-basierten Kontoverknüpfung hinzu. Wenn du diesen Verknüpfungstyp in deiner Aktion verwendest, beginnt der Ablauf mit Google Log-in. Damit kannst du prüfen, ob die Google-Profilinformationen des Nutzers in deinem System vorhanden sind. Ist dies nicht der Fall, beginnt ein standardmäßiger OAuth-Ablauf. Durch eine Kombination dieser beiden Verknüpfungstypen können Nutzer ihre Identität in deiner Aktion mit einem Google-Konto oder einem Nicht-Google-Konto verknüpfen. Wenn sie möchten, können sie auch ein neues Konto mit ihren Google-Profilinformationen erstellen.

Die optimierte Verknüpfung ist die empfohlene Kontoverknüpfungslösung, wenn eine der folgenden Bedingungen zutrifft:

• Du hast eine Aktion, die sich über mehrere Plattformen erstreckt (z. B. wenn deine Aktion mit einer Android-App funktioniert).
• Sie haben ein Authentifizierungssystem und möchten Nutzern erlauben, ihre Identitäten mit Nicht-Google-Konten zu verknüpfen. Das ist beispielsweise der Fall, wenn Sie ein Treuepunkteprogramm anbieten und dafür sorgen möchten, dass der Nutzer nicht die Punkte verliert, die er in seinem bestehenden Konto gesammelt hat.

Ob die optimierte Verknüpfung die richtige Lösung für dich ist, erfährst du auf der Seite Typ der Kontoverknüpfung auswählen.

Wichtige Begriffe

Bevor Sie die Funktionsweise von optimierten Verknüpfungen lesen, machen Sie sich mit den folgenden Begriffen vertraut:

• Google-ID-Token:Eine signierte Bestätigung der Identität eines Nutzers, die die grundlegenden Google-Profilinformationen eines Nutzers (Name, E-Mail-Adresse und Profilbild) enthält. Ein Google-ID-Token ist ein JSON-Webtoken (JWT). Im Folgenden finden Sie ein Beispiel für ein decodiertes Token:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

• user.verificationStatus:Ein vom System festgelegtes Attribut, mit dem angegeben wird, ob in der aktuellen Sitzung ein bestätigter Nutzer vorhanden ist.

• user.accountLinkingStatus: Ein vom System festgelegtes Attribut, mit dem angegeben wird, ob der Nutzer in der aktuellen Sitzung eine verknüpfte Identität hat.

• Systemszene für die Kontoverknüpfung:Eine vordefinierte Szene, die den Bestätigungsvorgang für die Kontoverknüpfung implementiert und an bestimmte Anwendungsfälle angepasst werden kann.

• Vorgang mit Autorisierungscode:Ein OAuth 2.0-Vorgang, den Sie mit optimierter Verknüpfung implementieren können. Dieser Ablauf erfordert zwei Endpunkte:

  • Autorisierungsendpunkt:Der Endpunkt, über den Nutzern, die noch nicht angemeldet sind, die Anmelde-UI präsentiert wird. Die Einwilligung zum angeforderten Zugriff wird in Form eines kurzlebigen Autorisierungscodes aufgezeichnet.
  • Endpunkt zum Tokenaustausch:Dieser Endpunkt ist für zwei Arten von Austauschen zuständig:
    1. Tauscht einen Autorisierungscode gegen ein langlebiges Aktualisierungstoken und ein kurzlebiges Zugriffstoken aus. Dieser Austausch findet statt, wenn der Nutzer den Prozess zur Kontoverknüpfung durchläuft.
    2. 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.

• Impliziter Codefluss:Ein OAuth 2.0-Vorgang, den Sie mit einer vereinfachten Verknüpfung implementieren können. Für diesen Vorgang ist nur ein Autorisierungsendpunkt erforderlich. Während dieses Vorgangs öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn die Anmeldung erfolgreich ist, geben Sie ein langlebiges Zugriffstoken an Google zurück. Dieses Zugriffstoken ist jetzt in jeder Anfrage enthalten, die von Assistant an deine Aktion gesendet wird.

• Zugriffstoken: Ein Token, das Ihren Dienst für den Zugriff auf Teile der Daten eines Nutzers autorisiert. Zugriffstokens sind mit jedem einzelnen Nutzer verknüpft.

• Aktualisierungstoken: Ein Token, das gegen ein neues Zugriffstoken ausgetauscht wird, sobald ein kurzlebiges Zugriffstoken abgelaufen ist.

Voraussetzungen

Wenn Sie den Verknüpfungstyp „Optimierte“ verwenden möchten, benötigen Sie Folgendes:

• Einen OAuth 2.0-Server

• Endpunkt des Tokenaustauschs

  Der Endpunkt des Tokenaustauschs muss erweitert werden, um Unterstützung für die Protokolle von Google für die automatische Verknüpfung und Kontoerstellung aus einem ID-Token hinzuzufügen. Sie müssen also die Parameter intent=get und intent=create in Anfragen an diesen Endpunkt hinzufügen.

Funktionsweise

In diesem Abschnitt wird der allgemeine Ablauf für eine optimierte Verknüpfung beschrieben. Im folgenden Abschnitt Optimierte Verknüpfungsabläufe werden die verschiedenen Abläufe beschrieben, die basierend darauf möglich sind, a) ob Sie die Kontoerstellung per Spracheingabe aktivieren oder deaktivieren und b) ob Sie den impliziten oder den Autorisierungscode verwenden.

Der grundlegende Ablauf sieht so aus:

1. Deine Aktion bittet den Nutzer um Einwilligung für den Zugriff auf sein Google-Profil.
2. Nachdem der Nutzer eingewilligt hat, erhält deine Aktion ein Google-ID-Token, das die Google-Profilinformationen des Nutzers enthält.
3. Sie müssen das Token validieren und decodieren, damit der Profilinhalt gelesen werden kann.
4. Deine Aktion verwendet dieses Token, um zu prüfen, ob die Google-Profilinformationen des Nutzers in deinem System vorhanden sind.
   1. Ist dies der Fall, hat sich der Nutzer bereits mit seinem Google-Konto in Ihrem System angemeldet und Assistant verknüpft die Identität des Nutzers mit seinem Google-Konto. Der Nutzer kann die Unterhaltung mit Assistant mit verknüpftem Konto fortsetzen.
   2. Ist dies nicht der Fall, fahren Sie mit Schritt 5 fort.
5. Der Nutzer kann entweder a) ein neues Konto mit seinen Google-Profilinformationen erstellen oder b) sich mit einem anderen Konto in Ihrem System anmelden. Die Auswahlmöglichkeiten für den Nutzer hängen davon ab, ob Sie die Kontoerstellung per Sprachbefehl aktivieren oder deaktivieren. Wenn sich der Nutzer mit einem anderen Konto in Ihrem System anmeldet, beginnt der standardmäßige OAuth-Ablauf.
6. Nachdem der Nutzer ein neues Konto erstellt oder sich bei einem anderen Anbieter angemeldet hat, gibt Ihr Dienst ein Zugriffstoken an Google zurück. Wenn Sie den Vorgang mit Autorisierungscode verwenden, gibt der Dienst auch ein Aktualisierungstoken zurück.
7. Der Nutzer kann die Unterhaltung mit Assistant jetzt mit verknüpftem Konto fortsetzen.

Optimierte Verknüpfungsabläufe

In diesem Abschnitt werden die verschiedenen Abläufe beschrieben, die bei der optimierten Verknüpfung möglich sind. In diesen Diagrammen werden die Abläufe beim Ablauf mit Autorisierungscode und nicht mit dem impliziten Codeablauf dargestellt. Es wird davon ausgegangen, dass Sie Actions Builder verwenden.

Hinweis :Bei den folgenden Abläufen wird davon ausgegangen, dass der Nutzer einwilligt, dass deine Aktion auf seine Google-Profilinformationen zugreift. Wenn ein Nutzer nicht einwilligt, biete ihm die Möglichkeit, deine Aktion mit einem alternativen, eingeschränkten Ablauf fortzusetzen. Weitere Informationen finden Sie in den Best Practices.

Jeder Ablauf enthält diese allgemeinen Schritte, nachdem der Nutzer deine Aktion aufgerufen hat:

Im obigen Ablauf wechseln Sie zur Szene des Kontoverknüpfungssystems und geben eine individuelle Begründung an. In der Szene wird der Nutzer um die Berechtigung zum Zugriff auf seine Google-Profilinformationen gebeten. Nachdem der Nutzer eingewilligt hat, sendet Assistant eine Anfrage mit den Profilinformationen für [e-mail].

Die Abläufe danach unterscheiden sich je nachdem, ob Sie die Kontoverknüpfung per Spracheingabe konfigurieren oder nicht, und ob die Informationen des Nutzers bereits in Ihrem System vorhanden sind. Jeder dieser Abläufe wird in den folgenden Abschnitten beschrieben.

Abläufe mit aktivierter Voice-Kontoerstellung

In diesem Abschnitt werden die Abläufe zur Kontoverknüpfung beschrieben, die auftreten können, wenn Sie die Kontoerstellung per Spracheingabe aktivieren.

Hinweis: Die folgenden Diagramme basieren auf dem Diagramm Häufig verwendete Schritte oben.

Ablauf 1: Nutzerinformationen sind in Ihrem System vorhanden

Hinweis: Eine Zeile von Webhook zu User steht für eine einfache Antwort, die Sie erstellen und anpassen. Von Assistant bis User gezogene Linien stellen Prompts dar, die Assistant gehören und nur begrenzte Anpassungsoptionen bieten (Anfragen, für die eine Berechtigung erforderlich ist, gehören immer Assistant). Aus Sicht des Nutzers werden beide Arten von Antworten von Assistant gesendet.

In diesem Fall ist der durch [e-mail] dargestellte Nutzer in Ihrem Back-End vorhanden. Daher gibt der Endpunkt des Tokenaustauschs ein Token für den Nutzer zurück. Die Identität des Nutzers in deiner Aktion ist jetzt mit seinem Google-Konto verknüpft. Die ursprüngliche Anfrage des Nutzers („Order my normal“) stimmt mit dem Nutzerabsicht order_drink. überein. Der Webhook übernimmt dann die Auftragsausführung des zugeordneten Intents und fragt Ihre Datenbank in der üblichen Reihenfolge von [e-mail] ab. Der Nutzer kann dann seine Unterhaltung mit Assistant fortsetzen.

Ablauf 2: Die Daten des Nutzers sind nicht vorhanden und der Nutzer erstellt ein Konto

Da Sie die Kontoerstellung per Spracheingabe aktiviert haben und [e-mail] in Ihrem Back-End nicht vorhanden ist, fragt Assistant den Nutzer, ob er eine der folgenden Aktionen ausführen möchte:

a) Sie erstellen mithilfe der Google-Profilinformationen ein neues Konto in Ihrem System. Dies erfolgt per Spracheingabe.

b) Melden Sie sich mit einem anderen Konto in Ihrem System an.

Hinweis :Sie können dem Nutzer auch erlauben, ein neues Konto bei einem anderen Anbieter zu erstellen. Diese Anbieter stellen Sie auf Ihrer Autorisierungsseite zur Verfügung.

In diesem Fall wählt der Nutzer die Möglichkeit, ein neues Konto per Spracheingabe zu erstellen. Google ruft den Tokenaustausch-Endpunkt Ihres Dienstes mit einer Anfrage zum Erstellen eines Kontos auf. Diese Anfrage enthält das Google-ID-Token mit den Komponenten, die zum Erstellen eines neuen Kontos erforderlich sind. Mit den Informationen aus diesem Token (Name und E-Mail-Adresse des Nutzers) können Sie dann ein Konto für den Nutzer erstellen.

Nachdem das Konto erstellt wurde, gibt der Dienst ein Zugriffstoken und ein Aktualisierungstoken für das neu erstellte Konto zurück. Die Identität des Nutzers in deiner Aktion ist jetzt mit seinem Google-Konto verknüpft. Die ursprüngliche Anfrage des Nutzers („Order my normal“) entspricht dem Nutzerabsicht order_drink.. Der Webhook übernimmt dann die Auftragsausführung und fragt Ihre Datenbank nach der üblichen Reihenfolge von [e-mail] ab, die noch nicht vorhanden ist, weil der Nutzer neu ist. Deine Aktion kann dann den Nutzer fragen, was er bestellen möchte.

Hinweis :Für neue Konten ist normalerweise kein Passwort festgelegt. Es wird empfohlen, Google Log-in anderen Plattformen hinzuzufügen, damit sich Nutzer auf allen Oberflächen deiner App über Google anmelden können. Alternativ können Sie dem Nutzer per E-Mail einen Link senden, mit dem die Passwortwiederherstellung gestartet wird. Dadurch kann der Nutzer ein Passwort für die Anmeldung auf anderen Plattformen festlegen.

Ablauf 3: Die Daten des Nutzers sind nicht vorhanden und der Nutzer meldet sich mit einem anderen Konto an

Du hast die Kontoerstellung per Sprachbefehl aktiviert. Assistant fragt daher den Nutzer, ob er eine der folgenden Aktionen ausführen möchte:

a) Sie erstellen mithilfe der Google-Profilinformationen ein neues Konto in Ihrem System. Dies erfolgt per Spracheingabe.

b) Melden Sie sich mit einem anderen Konto in Ihrem System an.

Hinweis: Sie können dem Nutzer auch erlauben, ein neues Konto bei einem anderen Anbieter zu erstellen. Diese Anbieter stellen Sie auf Ihrer Autorisierungsseite zur Verfügung.

In diesem Fall meldet sich der Nutzer mit einem anderen Konto an, wodurch der standardmäßige OAuth-Ablauf gestartet wird. Wenn der Ablauf auf einem Sprachgerät begann, überträgt Google die Ausführung auf ein Smartphone. Google öffnet dann deinen Autorisierungsendpunkt im Browser des Nutzers. Je nach Konfiguration kann der Nutzer auswählen, ob er sich a) mit einem vorhandenen Konto, das Google Log-in nicht verwendet, bei deinem Dienst anmelden oder b) ein neues Konto mit einem anderen Anbieter erstellen möchte. Weitere Informationen zum OAuth-Ablauf findest du im Konzeptleitfaden für die OAuth-Verknüpfung.

Nach der Überprüfung der Anmeldedaten des Nutzers gibt der Dienst ein Zugriffstoken und ein Aktualisierungstoken an Google zurück. Die Identität des Nutzers in deiner Aktion ist jetzt mit einem Nicht-Google-Konto verknüpft. Die ursprüngliche Anfrage des Nutzers ("Order my normal") stimmt mit dem Nutzerabsicht order_drink. überein. Der Webhook übernimmt dann die Ausführung des zugeordneten Intents und fragt Ihre Datenbank nach der üblichen Reihenfolge von [e-mail] ab, die noch nicht vorhanden ist, da der Nutzer neu ist. Deine Aktion kann dann den Nutzer fragen, was er bestellen möchte, oder ihn bitten, die übliche Reihenfolge einzurichten.

Ablauf mit deaktiviertem Voice-Kontoerstellung

In diesem Abschnitt wird der Kontoverknüpfungsvorgang beschrieben, der ausgeführt werden kann, wenn Sie die Kontoerstellung per Spracheingabe deaktivieren.

Hinweis: Die folgenden Diagramme basieren auf dem Diagramm Häufig verwendete Schritte oben.

Ablauf 4: Die Daten des Nutzers sind nicht vorhanden

Sie haben die Kontoerstellung per Spracheingabe nicht aktiviert und der Nutzer ist in Ihrem Back-End nicht vorhanden. Daher beginnt der standardmäßige OAuth-Ablauf. Assistant öffnet den Autorisierungsendpunkt im Browser des Nutzers. Wenn der Vorgang auf einem sprachgesteuerten Gerät begann, überträgt Google die Ausführung auf ein Gerät mit einem Bildschirm. Der Nutzer kann sich entweder a) bei einem anderen Anbieter anmelden, wenn er sich mit einem anderen Konto bei Ihrem Dienst registriert hat, oder b) ein neues Konto bei einem anderen Anbieter erstellen. Weitere Informationen zum OAuth-Ablauf finden Sie im Konzeptleitfaden für die OAuth-Verknüpfung.

Nach der Überprüfung der Anmeldedaten des Nutzers gibt der Dienst ein Zugriffstoken und ein Aktualisierungstoken an Google zurück. Die Identität des Nutzers in deiner Aktion ist jetzt mit einem Nicht-Google-Konto verknüpft. Die ursprüngliche Anfrage des Nutzers ("Order my normal") stimmt mit dem Nutzerabsicht order_drink. überein. Der Webhook übernimmt dann die Ausführung des zugeordneten Intents und fragt Ihre Datenbank nach der üblichen Reihenfolge von [e-mail] ab, die noch nicht vorhanden ist, da der Nutzer neu ist. Deine Aktion kann den Nutzer dann bitten, die übliche Reihenfolge einzurichten.