Konzeptleitfaden zu OAuth und Google Log-in (Dialogflow)

Beim Verknüpfungstyp „OAuth“ und „Google Log-in“ wird Google Log-in zusätzlich zur OAuth-basierten Kontoverknüpfung hinzugefügt. 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.

OAuth und Google Log-in sind 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 OAuth und Google Log-in die richtige Lösung für dich sind, erfährst du auf der Seite Typ der Kontoverknüpfung auswählen.

Wichtige Begriffe

Bevor Sie sich mit der Funktionsweise von OAuth und Google Log-in vertraut machen, sollten Sie sich mit den folgenden Begriffen vertraut machen:

• 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"
}

• Hilfs-Intent für die Kontoanmeldung:Ein Hilfs-Intent, den Sie aufrufen, um von Assistant einen Kontoverknüpfungsvorgang anzufordern. Weitere Informationen findest du unter Kontoanmeldung.
  • Kontextstring:Ein benutzerdefinierter String, den Sie dem Hilfs-Intent für die Kontoanmeldung hinzufügen und dem Nutzer mitteilen, warum Sie sein Konto verknüpfen möchten.
• Vorgang mit Autorisierungscode:Ein OAuth 2.0-Vorgang, den Sie mit OAuth + Google Log-in implementieren können. Für diesen Ablauf sind zwei Endpunkte erforderlich:
  • 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 OAuth + Google Log-in 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

Um den Verknüpfungstyp „OAuth“ und „Google Log-in“ zu verwenden, benötigen Sie Folgendes:

• Einen OAuth 2-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 OAuth und Google Log-in beschrieben. Im folgenden Abschnitt OAuth- und GSI-Abläufe werden die verschiedenen Abläufe beschrieben, die auftreten können, je nachdem, ob Sie die Kontoerstellung per Spracheingabe aktivieren oder deaktivieren und b) ob Sie den impliziten Vorgang oder den Vorgang mit 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.

OAuth- und GSI-Abläufe

In diesem Abschnitt werden die verschiedenen Abläufe beschrieben, die mit OAuth und GSI auftreten können. In diesen Diagrammen werden die Abläufe im Ablauf mit Autorisierungscode und nicht mit dem impliziten Codefluss dargestellt. Es wird davon ausgegangen, dass Sie Dialogflow als Natural Language Understanding-Lösung für Ihre Aktion 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 rufen Sie den Hilfs-Intent actions.intent.SIGN_IN mit einem Kontextstring auf, den Sie anpassen. Bei diesem Intent wird der Nutzer um die Berechtigung zum Zugriff auf seine Google-Profilinformationen gebeten. Nachdem der Nutzer seine Einwilligung erteilt 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 eingeschränkte Anpassungsmöglichkeiten haben (Anfragen, für die eine Berechtigung erforderlich ist, gehören immer dem Assistant). Aus Sicht des Nutzers werden beide Arten von Antworten von Assistant ausgegeben.

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 benutzerdefinierten Intent 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 myregular“) entspricht dem benutzerdefinierten Intent order_drink.. Der Webhook übernimmt dann die Auftragsausfü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.

Hinweis :Für neue Konten ist normalerweise kein Passwort festgelegt. Es empfiehlt sich, 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 Spracheingabe aktiviert. Deshalb 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 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 OAuth-Konzeptleitfaden.

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 benutzerdefinierten Intent 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 findest du im OAuth-Konzeptleitfaden.

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 benutzerdefinierten Intent 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.