Kontoverknüpfung mit OAuth-basierter Google Log-in-Verknüpfung „Optimierte“

Beim Verknüpfungstyp OAuth-basiertes Google Log-in – „Optimiert“ wird Google Log-in zusätzlich zur OAuth-basierten Kontoverknüpfung hinzugefügt. So können Google-Nutzer ihre Konten ganz einfach per Sprachbefehl verknüpfen. Außerdem können Nutzer, die sich mit einer Nicht-Google-Identität bei Ihrem Dienst registriert haben, ihre Konten verknüpfen.

Diese Art der Verknüpfung beginnt mit der Anmeldung über Google. So können Sie prüfen, ob die Google-Profilinformationen des Nutzers in Ihrem System vorhanden sind. Wenn die Informationen des Nutzers in Ihrem System nicht gefunden werden, beginnt ein standardmäßiger OAuth-Ablauf. Der Nutzer kann auch ein neues Konto mit seinen Google-Profilinformationen erstellen.

Abbildung 1: Nachdem Ihre Aktion Zugriff auf das Google-Profil des Nutzers erhalten hat, können Sie es verwenden, um eine Übereinstimmung für den Nutzer in Ihrem Authentifizierungssystem zu finden.

So führen Sie die Kontoverknüpfung mit dem vereinfachten Verknüpfungstyp durch:

1. Bitten Sie den Nutzer zuerst um die Einwilligung, auf sein Google-Profil zuzugreifen.
2. Verwenden Sie die Informationen in seinem Profil, um den Nutzer zu identifizieren.
3. Wenn in Ihrem Authentifizierungssystem keine Übereinstimmung für den Google-Nutzer gefunden wird, wird der Ablauf fortgesetzt. Das hängt davon ab, ob Sie in der Actions Console für Ihr Actions-Projekt die Erstellung von Nutzerkonten per Sprachbefehl oder nur auf Ihrer Website konfiguriert haben.
   • Wenn Sie die Kontoerstellung per Sprachbefehl zulassen, müssen Sie das von Google empfangene ID-Token validieren. Anschließend können Sie einen Nutzer basierend auf den Profilinformationen im ID-Token erstellen.
   • Wenn Sie die Kontoerstellung per Sprachbefehl nicht zulassen, wird der Nutzer zu einem Browser weitergeleitet, in dem er Ihre Autorisierungsseite aufrufen und den Vorgang zur Nutzererstellung abschließen kann.

Abbildung 2. Eine visuelle Darstellung des OAuth- und Google-Log-in-Ablaufs, wenn die Informationen eines Nutzers in Ihrem System nicht gefunden werden.

Kontoerstellung per Sprachbefehl unterstützen

Wenn Sie die Erstellung von Nutzerkonten per Sprachbefehl zulassen, fragt Assistant den Nutzer, ob er Folgendes tun möchte:

• Erstellen Sie mit den Google-Kontoinformationen des Nutzers ein neues Konto in Ihrem System oder
• Melden Sie sich mit einem anderen Konto in Ihrem Authentifizierungssystem an, wenn Sie ein bestehendes Konto haben, das kein Google-Konto ist.

Wenn Sie die Reibung bei der Kontoerstellung minimieren möchten, empfiehlt es sich, die Kontoerstellung per Sprachbefehl zu ermöglichen. Der Nutzer muss den Sprachablauf nur verlassen, wenn er sich mit einem vorhandenen Konto anmelden möchte, das nicht von Google stammt.

Kontoerstellung per Sprachbefehl nicht zulassen

Wenn Sie die Erstellung von Nutzerkonten per Sprachbefehl nicht zugelassen haben, öffnet Assistant die URL der Website, die Sie für die Nutzerauthentifizierung angegeben haben. Wenn die Interaktion auf einem Gerät ohne Bildschirm stattfindet, leitet Assistant den Nutzer zu einem Smartphone weiter, um den Vorgang für die Kontoverknüpfung fortzusetzen.

Das Deaktivieren der Erstellung wird in den folgenden Fällen empfohlen:

• Sie möchten nicht, dass Nutzer mit Konten, die nicht von Google stammen, ein neues Nutzerkonto erstellen, sondern dass sie stattdessen eine Verknüpfung zu ihren bestehenden Nutzerkonten in Ihrem Authentifizierungssystem herstellen. Wenn Sie beispielsweise ein Treuepunkteprogramm anbieten, möchten Sie möglicherweise dafür sorgen, dass der Nutzer die auf seinem bestehenden Konto gesammelten Punkte nicht verliert.

• Sie müssen die volle Kontrolle über den Ablauf der Kontoerstellung haben. Sie können beispielsweise die Erstellung von Konten unterbinden, wenn Sie dem Nutzer während der Kontoerstellung Ihre Nutzungsbedingungen präsentieren müssen.

Hinweis :Wählen Sie eine der folgenden Ablaufoptionen aus, um mehr über die Implementierung des ausgewählten Ablaufs zu erfahren. Bei Bedarf wird der Inhalt des Leitfadens neu geladen und an deine Auswahl angepasst.

Kontoerstellung per Sprachbefehl zulassen Kontoerstellung per Sprachbefehl nicht zulassen

OAuth-basierte „Streamlined“-Verknüpfung für die Google-Anmeldung implementieren

Konten werden mit branchenüblichen OAuth 2.0-Vorgängen verknüpft. Actions on Google unterstützt den impliziten Ablauf und den Autorisierungscodefluss.

Hinweis :Wenn Sie die Kontoverknüpfung implementieren, um Finanzinformationen zu verarbeiten, gelten möglicherweise zusätzliche Richtlinien für Ihre Aktion. Die Überprüfung einer Action mit Kontoverknüpfung für Finanzinformationen kann bis zu sechs Wochen dauern. Berücksichtigen Sie diese Zeit bei der Planung Ihres Release-Zeitplans. Damit die Überprüfung reibungslos abläuft, solltest du die Richtlinien für Finanzdienstleistungen einhalten, bevor du deine Aktion zur Überprüfung einreichst.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

• 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
• 令牌交换端点，负责两种类型的交换：
  1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
  2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

注意 ：请选择您希望实施的 OAuth 2.0 流程。如果需要，本指南的内容会根据您的选择重新加载。

身份验证代码 隐式流程

Projekt konfigurieren

So konfigurieren Sie Ihr Projekt für die vereinfachte Verknüpfung:

1. Öffnen Sie die Actions Console und wählen Sie das gewünschte Projekt aus.
2. Klicken Sie auf den Tab Entwickeln und wählen Sie Kontoverknüpfung aus.
3. Aktiviere den Schalter neben Kontoverknüpfung.
4. Wählen Sie im Abschnitt Kontoerstellung die Option Ja aus.

5. Wählen Sie unter Verknüpfungstyp die Optionen OAuth & Google-Anmeldung und Implizit aus.

   

6. Führen Sie unter Client Information (Kundeninformationen) folgende Schritte aus:

   • Weisen Sie Client-ID, die von Ihren Actions an Google ausgegeben wird einen Wert zu, um Anfragen von Google zu identifizieren.
   • Fügen Sie die URLs für Ihre Autorisierungs- und Token-Austausch-Endpunkte ein.

7. Klicken Sie auf Speichern.

OAuth-Server implementieren

为了支持 OAuth 2.0 隐式流程，您的服务会进行授权 端点。此端点负责 就数据访问征得用户同意。授权端点 向尚未登录的用户显示登录界面，并记录 同意所请求的访问。

当您的 Action 需要调用您的某项授权的 API 时，Google 会使用 此端点来获得用户许可，以在其上调用这些 API 。

由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下特征： 以下流程：

1. Google 会在用户的浏览器中打开您的授权端点。通过 如果用户尚未登录，则可以登录，并且授予 Google 访问 通过您的 API 访问其数据（如果尚未授予权限）。
2. 您的服务会创建一个访问令牌并将其返回给 通过使用访问令牌将用户的浏览器重定向回 Google， 附件。
3. Google 调用您的服务的 API，并使用 。您的服务会验证访问令牌是否向 Google 授予 访问 API 的授权，然后完成 API 调用。

处理授权请求

当您的 Action 需要通过 OAuth 2.0 隐式流程执行账号关联时， Google 会通过包含以下内容的请求将用户发送到您的授权端点： 以下参数：

授权端点参数
client_id	您分配给 Google 的客户 ID。
redirect_uri	此请求的响应发送到的网址。
state	将一个在 重定向 URI。
response_type	要在响应中返回的值的类型。对于 OAuth 2.0 隐式 则响应类型始终为 token。

例如，如果您的授权端点可通过 https://myservice.example.com/auth 访问， 请求可能如下所示：

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

为了让授权端点能够处理登录请求，请执行以下步骤：

1. 验证 client_id 和 redirect_uri 值， 防止向意外或配置错误的客户端应用授予访问权限：

   • 确认 client_id 是否与您的客户端 ID 匹配 分配给 Google。
   • 确认 redirect_uri 指定的网址 参数的格式如下：

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID 是项目设置页面上的 ID Actions 控制台界面。

2. 检查用户是否已登录您的服务。如果用户未登录 中，完成服务的登录或注册流程。

3. 生成 Google 将用于访问您的 API 的访问令牌。通过 访问令牌可以是任何字符串值，但必须唯一地表示 令牌对应的用户和客户端，且不得被猜到。

4. 发送 HTTP 响应，将用户浏览器重定向到相应网址 由 redirect_uri 参数指定。添加所有 以下参数：

   • access_token：您刚刚生成的访问令牌
   • token_type：字符串 bearer
   • state：原始状态的未修改状态值 请求 以下是生成的网址示例：

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google 的 OAuth 2.0 重定向处理程序将收到访问令牌并确认 state 值没有更改。在 Google 获得 访问令牌，则 Google 会将该令牌附加到后续调用 作为 AppRequest 的一部分添加到您的 Action。

处理自动关联

在用户同意你的 Action 访问他们的 Google 个人资料后，Google 发送请求，其中包含 Google 用户身份的已签名断言。 该断言包含的信息包括用户的 Google 账号 ID、姓名、 和电子邮件地址。为项目配置的令牌交换端点处理 请求。

如果您的身份验证系统中已经存在相应的 Google 账号， 您的令牌交换端点为用户返回令牌。如果 Google 账号没有 匹配现有用户，您的令牌交换端点会返回 user_not_found 错误。

请求的格式如下：

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

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
grant_type	所交换的令牌的类型。对于这类请求 参数的值为 urn:ietf:params:oauth:grant-type:jwt-bearer。
intent	对于这些请求，此参数的值为 `get`。
assertion	一个 JSON Web 令牌 (JWT)，提供 Google 用户身份。JWT 包含的信息包括 账号 ID、名称和电子邮件地址。
consent_code	可选：一个一次性代码（如果存在）用于表明 用户已同意你的 Action 访问指定范围。
scope	可选：您配置 Google 向用户请求的任何范围。

当您的令牌交换端点收到关联请求时，它应该 以下：

JWT-Assertion validieren und decodieren

Sie können die JWT-Assertion mit einer JWT-Decodierungsbibliothek für Ihre Sprache validieren und decodieren. Verwenden Sie die öffentlichen Schlüssel von Google (verfügbar in JWK oder PEM-Format), um die Signatur.

Hinweis: Die Schlüssel sollten nicht hartcodiert sein. Folgen Sie stattdessen der Anleitung unter OpenID Connect Discovery Protokoll und prüfen Sie den cache-control-Header, um zu entscheiden, wie lange der Schlüssel im Cache gespeichert werden soll.

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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

Zusätzlich zur Bestätigung der Signatur des Tokens muss der Aussteller der Assertion geprüft werden (Feld iss) https://accounts.google.com ist und die Zielgruppe (Feld aud) ist die Client-ID, die deiner Aktion zugewiesen ist.

检查您的身份验证系统中是否已存在该 Google 账号

请检查以下任一条件是否成立：

• Google 账号 ID 可在断言的 sub 字段中找到，也可位于您的用户数据库中。
• 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，则表明用户已经注册，您可以发出 访问令牌。

如果断言中指定的 Google 账号 ID 和电子邮件地址都没有 与您数据库中的用户匹配，表示该用户尚未注册。在这种情况下，您的 令牌交换端点应回复 HTTP 401 错误，指定 error=user_not_found， 如以下示例中所示：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"user_not_found",
}

当 Google 收到包含 user_not_found 错误的 401 错误响应时， 使用 intent 参数的值调用您的令牌交换端点 设置为 create 并发送包含用户个人资料信息的 ID 令牌 一起发送。

通过 Google 登录功能处理账号创建

当用户需要在您的服务中创建账号时，Google 会 向令牌交换端点发送的请求 intent=create，如以下示例所示：

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]

assertion 参数包含 JSON Web 令牌 (JWT)，可提供 Google 用户的身份的已签名断言。JWT 包含 其中包含用户的 Google 账号 ID、姓名和电子邮件地址 为您的服务创建一个新账号。

如需响应账号创建请求，您的令牌交换端点必须执行以下操作 以下：

JWT-Assertion validieren und decodieren

Sie können die JWT-Assertion mit einer JWT-Decodierungsbibliothek für Ihre Sprache validieren und decodieren. Verwenden Sie die öffentlichen Schlüssel von Google (verfügbar in JWK oder PEM-Format), um die Signatur.

Hinweis: Die Schlüssel sollten nicht hartcodiert sein. Folgen Sie stattdessen der Anleitung unter OpenID Connect Discovery Protokoll und prüfen Sie den cache-control-Header, um zu entscheiden, wie lange der Schlüssel im Cache gespeichert werden soll.

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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

Zusätzlich zur Bestätigung der Signatur des Tokens muss der Aussteller der Assertion geprüft werden (Feld iss) https://accounts.google.com ist und die Zielgruppe (Feld aud) ist die Client-ID, die deiner Aktion zugewiesen ist.

验证用户信息并创建新账号

请检查以下任一条件是否成立：

• Google 账号 ID 可在断言的 sub 字段中找到，也可位于您的用户数据库中。
• 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，则提示用户将其现有账号关联 通过使用 HTTP 401 错误响应请求 error=linking_error，并将用户的电子邮件地址为 login_hint，如 示例：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

如果以上两个条件都不满足，请使用相应信息创建一个新的用户账号 。新账号通常不会设置密码。时间是 建议您将 Google 登录功能添加到其他平台，以便用户能够 在您的应用的各个界面上通过 Google 投放广告。或者，您也可以 通过电子邮件向用户发送链接，启动密码恢复流程，以便用户设置 密码，以便在其他平台上登录。

创建完成后，发出一个访问令牌 并在 HTTPS 响应的正文，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  
  "expires_in": SECONDS_TO_EXPIRATION
}

Sprachbenutzeroberfläche für den Authentifizierungsvorgang entwerfen

Warnung:Fordern Sie Nutzer nicht gleich zu Beginn der Unterhaltung mit Ihrer Aktion auf, ihr Konto zu verknüpfen. Stattdessen sollten Sie nicht authentifizierten Nutzern einen Gastablauf zur Verfügung stellen, um zu zeigen, wie Ihre Aktion funktioniert. Die Kontoverknüpfung sollte erst dann angefordert werden, wenn sie für die weitere Nutzung erforderlich ist. Wenn Nutzer die Aktion aufgrund von Problemen mit der Kontoverknüpfung immer wieder verlassen, wird sie von Google nicht aktiv beworben. Das kann zu einem Rückgang des Nutzerverkehrs führen.

Hinweis :Sie müssen Actions Builder verwenden, um eine Aktion zu erstellen, die die Kontoverknüpfung implementiert.

Prüfen, ob der Nutzer bestätigt ist, und den Kontoverknüpfungsvorgang starten

1. Öffnen Sie Ihr Actions Builder-Projekt in der Actions Console.
2. Erstellen Sie eine neue Szene, um die Kontoverknüpfung in Ihrer Aktion zu starten:
   1. Klicken Sie auf Szenen.
   2. Klicken Sie auf das Hinzufügen-Symbol (+), um eine neue Szene hinzuzufügen.
3. Klicken Sie in der neu erstellten Szene auf das Symbol zum Hinzufügen  für Bedingungen.
4. 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 für Ihre Aktion während der Unterhaltung keine Kontoverknüpfung durchgeführt werden. In diesem Fall sollte auf Funktionen zurückgegriffen werden, für die keine Kontoverknüpfung erforderlich ist.
   1. Geben Sie im Feld Enter new expression unter Bedingung die folgende Logik ein: user.verificationStatus != "VERIFIED"
   2. Wählen Sie unter Übergang eine Szene aus, für die keine Kontoverknüpfung erforderlich ist, oder eine Szene, die den Einstiegspunkt für Funktionen ist, die nur für Gäste verfügbar sind.

1. Klicken Sie für Bedingungen auf das Symbol zum Hinzufügen .
2. Fügen Sie eine Bedingung hinzu, um einen Vorgang für die Kontoverknüpfung auszulösen, wenn der Nutzer keine zugehörige Identität hat.
   1. Geben Sie im Feld Enter new expression unter Bedingung die folgende Logik ein:: user.verificationStatus == "VERIFIED"
   2. Wählen Sie unter Übergang die Systemszene Kontoverknüpfung aus.
   3. Klicken Sie auf Speichern.

Nach dem Speichern wird Ihrem Projekt eine neue Szene für die Kontoverknüpfung mit dem Namen <SceneName>_AccountLinking hinzugefügt.

Szene für die Kontoverknüpfung anpassen

1. Wählen Sie unter Szenen die Systemszene für die Kontoverknüpfung aus.
2. Klicken Sie auf Prompt senden und fügen Sie einen kurzen Satz hinzu, um dem Nutzer zu erklären, warum die Action auf seine Identität zugreifen muss (z. B. „Zum Speichern Ihrer Einstellungen“).
3. Klicken Sie auf Speichern.

1. Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung erfolgreich abschließt.
2. Konfigurieren Sie, wie der Ablauf fortgesetzt werden soll, wenn der Nutzer der Verknüpfung seines Kontos zustimmt. Rufen Sie den Webhook beispielsweise auf, um die erforderliche benutzerdefinierte Geschäftslogik zu verarbeiten und zur ursprünglichen Szene zurückzukehren.
3. Klicken Sie auf Speichern.

1. Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung abbricht oder schließt.
2. Konfigurieren Sie, wie der Vorgang fortgesetzt werden soll, wenn der Nutzer der Verknüpfung seines Kontos nicht zustimmt. Senden Sie beispielsweise eine Bestätigungsnachricht und leiten Sie Nutzer zu Szenen weiter, die Funktionen bieten, für die keine Kontoverknüpfung erforderlich ist.
3. Klicken Sie auf Speichern.

1. Klicken Sie unter Bedingungen auf Bei System- oder Netzwerkfehler.
2. Konfigurieren Sie, wie der Ablauf fortgesetzt werden soll, wenn der Ablauf für die Kontoverknüpfung aufgrund von System- oder Netzwerkfehlern nicht abgeschlossen werden kann. Senden Sie beispielsweise eine Bestätigungsnachricht und leiten Sie Nutzer zu Szenen weiter, die Funktionen bieten, für die keine Kontoverknüpfung erforderlich ist.
3. Klicken Sie auf Speichern.

Datenzugriffsanfragen bearbeiten

Wenn die Assistant-Anfrage ein Zugriffstoken enthält, prüfe zuerst, ob das Zugriffstoken gültig ist und nicht abgelaufen ist. Rufe dann aus deiner Nutzerkontodatenbank das mit dem Token verknüpfte Nutzerkonto ab.