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

Beim OAuth-basierten Google Log-in-Verknüpfungstyp „Optimierte“ wird Google Log-in zusätzlich zur OAuth-basierten Kontoverknüpfung hinzugefügt. Dies bietet eine nahtlose sprachbasierte Verknüpfung für Google-Nutzer und gleichzeitig die Kontoverknüpfung für Nutzer, die sich nicht mit einer Google-Identität bei Ihrem Dienst registriert haben.

Dieser Verknüpfungstyp beginnt mit Google Log-in. Damit können Sie prüfen, ob die Google-Profilinformationen des Nutzers in Ihrem System vorhanden sind. Wenn die Nutzerinformationen nicht in Ihrem System gefunden werden, beginnt ein Standard-OAuth-Ablauf. Der Nutzer kann auch ein neues Konto mit seinen Google-Profilinformationen erstellen.

Abbildung 1: Nachdem deine Aktion Zugriff auf das Google-Profil des Nutzers erhalten hat, kannst du damit eine Übereinstimmung für den Nutzer in deinem Authentifizierungssystem finden.

So erstellst du eine Kontoverknüpfung mit dem Verknüpfungstyp „Optimierte“:

1. Bitten Sie den Nutzer zuerst um Einwilligung für den Zugriff auf sein Google-Profil.
2. Die Informationen in seinem Profil verwenden, um den Nutzer zu identifizieren
3. Wenn Sie in Ihrem Authentifizierungssystem keine Übereinstimmung für den Google-Nutzer finden, wird der Ablauf abhängig davon fortgesetzt, ob Sie Ihr Actions-Projekt in der Actions Console so konfiguriert haben, dass das Erstellen von Nutzerkonten per Spracheingabe oder nur auf Ihrer Website zulässig ist.
   • Wenn Sie die Kontoerstellung per Spracheingabe zulassen, validieren Sie das von Google erhaltene ID-Token. Anschließend können Sie anhand der im ID-Token enthaltenen Profilinformationen einen Nutzer erstellen.
   • Wenn Sie die Kontoerstellung per Spracheingabe nicht zulassen, wird der Nutzer zu einem Browser weitergeleitet, wo er Ihre Autorisierungsseite laden und den Vorgang zur Nutzererstellung abschließen kann.

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

Kontoerstellung per Spracheingabe unterstützen

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

• ein neues Konto in Ihrem System mit den Google-Kontoinformationen erstellen oder
• Melden Sie sich mit einem anderen Konto in Ihrem Authentifizierungssystem an, wenn es bereits ein Nicht-Google-Konto hat.

Es empfiehlt sich, die Kontoerstellung per Spracheingabe zuzulassen, wenn Sie den Ablauf der Kontoerstellung minimieren möchten. Der Nutzer muss den Voice Flow nur verlassen, wenn er sich mit einem vorhandenen Nicht-Google-Konto anmelden möchte.

Kontoerstellung per Sprachbefehl nicht zulassen

Wenn Sie das Erstellen von Nutzerkonten per Spracheingabe nicht zugelassen haben, öffnet Assistant die URL zu der Website, die Sie für die Nutzerauthentifizierung angegeben haben. Wenn die Interaktion auf einem Gerät ohne Bildschirm erfolgt, leitet Assistant den Nutzer zu einem Smartphone weiter, um den Kontoverknüpfungsvorgang fortzusetzen.

In folgenden Fällen empfiehlt es sich, die Erstellung nicht zu untersagen:

• Sie möchten nicht, dass Nutzer, die keine Google-Konten haben, ein neues Nutzerkonto erstellen, sondern stattdessen eine Verknüpfung mit ihren vorhandenen Nutzerkonten in Ihrem Authentifizierungssystem herstellen. Wenn Sie beispielsweise ein Treuepunkteprogramm anbieten, sollten Sie darauf achten, dass der Nutzer nicht die mit seinem bestehenden Konto gesammelten Punkte verliert.

• Sie müssen die volle Kontrolle über die Kontoerstellung haben. Sie können die Erstellung beispielsweise nicht zulassen, wenn Sie dem Nutzer während der Kontoerstellung Ihre Nutzungsbedingungen anzeigen lassen möchten.

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, um ihn an deine Auswahl anzupassen.

Kontoerstellung per Sprachbefehl zulassen Kontoerstellung per Sprachbefehl nicht zulassen

„Optimierte“ Verknüpfung mit OAuth-basiertem 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 Vorgang und den Vorgang mit Autorisierungscode.

Hinweis :Wenn du eine Kontoverknüpfung zur Verarbeitung von Finanzdaten implementierst, beachte, dass für deine Aktion möglicherweise zusätzliche Richtlinien gelten. Es kann bis zu sechs Wochen dauern, bis wir eine Aktion mit Kontoverknüpfung auf Finanzinformationen prüfen. Berücksichtigen Sie diese Zeit daher bei der Planung Ihres Veröffentlichungszeitplans. Um den Überprüfungsprozess zu erleichtern, musst du die Richtlinien für Finanzdienstleistungen einhalten, bevor du deine Aktion zur Überprüfung einreichst.

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:
  1. Tauscht einen Autorisierungscode gegen ein langlebiges Aktualisierungstoken und ein kurzlebiges Zugriffstoken aus. Dieser Austausch erfolgt, wenn der Nutzer die 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.

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.

Hinweis :Wähle aus, welchen OAuth 2.0-Vorgang du implementieren möchtest. Bei Bedarf wird der Inhalt dieses Leitfadens neu geladen und an deine Auswahl angepasst.

Authentifizierungscode Impliziter Ablauf

Projekt konfigurieren

So konfigurieren Sie Ihr Projekt für die Verwendung der optimierten 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. Aktivieren Sie den Schieberegler 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 Log-in und Impliziert aus.

   

6. Führen Sie unter Clientinformationen die folgenden Schritte aus:

   • Weisen Sie der Client-ID von Actions to Google 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 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 JWK 或 PEM 格式）来验证令牌的 签名。

注意 ：不得对键进行硬编码。而应按照 OpenID Connect Discovery 协议 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如以下示例所示：

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

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

检查您的身份验证系统中是否已存在该 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 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 JWK 或 PEM 格式）来验证令牌的 签名。

注意 ：不得对键进行硬编码。而应按照 OpenID Connect Discovery 协议 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如以下示例所示：

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

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

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

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

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

Die Sprach-Benutzeroberfläche für den Authentifizierungsablauf entwerfen

Warnung:Gib Nutzern zu Beginn der Unterhaltung mit deiner Aktion keine erforderliche Aufforderung zur Kontoverknüpfung. Stelle nicht authentifizierten Nutzern stattdessen einen Gastablauf vor, um zu zeigen, wie deine Aktion funktioniert, und fordere dann nur die Kontoverknüpfung an, wenn dies erforderlich ist, um fortzufahren. Wenn Nutzer die Aktion aufgrund von Problemen mit der Kontoverknüpfung regelmäßig verlassen, wird sie von Google nicht aktiv beworben. Dadurch kann sich die Anzahl der Nutzerzugriffe für die Aktion verringern.

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

Prüfe, ob der Nutzer bestätigt ist, und starte den Vorgang zur Kontoverknüpfung

1. Öffnen Sie Ihr Actions Builder-Projekt in der Actions Console.
2. Erstelle eine neue Szene, um die Kontoverknüpfung in deiner Aktion zu starten:
   1. Klicken Sie auf Szenen.
   2. Klicken Sie auf das Symbol Hinzufügen (+), um eine neue Szene hinzuzufügen.
3. Klicken Sie in der neu erstellten Szene auf das Symbol zum Hinzufügen von 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 deine Aktion während der Unterhaltung keine Kontoverknüpfung vornehmen und sollte auf Funktionen zugreifen, 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 der Einstiegspunkt für die Funktion nur für Gäste ist.

1. Klicken Sie unter Conditions (Bedingungen) auf das Symbol zum Hinzufügen .
2. Fügen Sie eine Bedingung hinzu, um einen Kontoverknüpfungsvorgang auszulösen, wenn der Nutzer keine verknüpfte 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 Umstellung die Systemszene Kontoverknüpfung aus.
   3. Klicken Sie auf Speichern.

Nach dem Speichern wird dem Projekt eine neue Systemszene zur 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. Klicke auf Prompt senden und füge einen kurzen Satz hinzu, um dem Nutzer zu beschreiben, warum die Aktion auf seine Identität zugreifen muss (z. B. „Zum Speichern deiner Einstellungen“).
3. Klicken Sie auf Speichern.

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

1. Klicken Sie unter Bedingungen auf Wenn der Nutzer die Kontoverknüpfung aufhebt oder ablehnt.
2. Legen Sie fest, wie der Ablauf ausgeführt werden soll, wenn der Nutzer der Verknüpfung seines Kontos nicht zustimmt. Sie können beispielsweise eine Bestätigungsnachricht senden und zu Szenen weiterleiten, 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 Netzwerkfehlern.
2. Legen Sie fest, wie der Ablauf ausgeführt werden soll, wenn der Kontoverknüpfungsvorgang aufgrund von System- oder Netzwerkfehlern nicht abgeschlossen werden kann. Sie können beispielsweise eine Bestätigungsnachricht senden und zu Szenen weiterleiten, die Funktionen bieten, für die keine Kontoverknüpfung erforderlich ist.
3. Klicken Sie auf Speichern.

Datenzugriffsanfragen verarbeiten

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