การลิงก์บัญชีด้วย OAuth

ประเภทการลิงก์ OAuth รองรับขั้นตอน OAuth 2.0 มาตรฐานอุตสาหกรรม 2 ขั้นตอน ได้แก่ ขั้นตอนของรหัสโดยนัยและการให้สิทธิ์

ในขั้นตอนการเขียนโค้ดแบบโดยนัย Google จะเปิดปลายทางการให้สิทธิ์ในเบราว์เซอร์ของผู้ใช้ เมื่อลงชื่อเข้าใช้สําเร็จ คุณจะส่งคืนโทเค็นเพื่อการเข้าถึงที่ใช้ได้นานแก่ Google ตอนนี้โทเค็นเพื่อการเข้าถึงนี้รวมอยู่ในคําขอทุกรายการที่ส่งจาก Assistant ไปยังการดําเนินการของคุณแล้ว

ในกระบวนการรหัสการให้สิทธิ์ คุณต้องมีปลายทาง 2 จุด ได้แก่

• ปลายทางการให้สิทธิ์ ซึ่งมีหน้าที่นําเสนอ UI การลงชื่อเข้าใช้แก่ผู้ใช้ที่ไม่ได้ลงชื่อเข้าใช้ และยินยอมให้มีการเข้าถึงการเข้าถึงที่ขอในรูปของรหัสการให้สิทธิ์ระยะสั้น
• ปลายทางของการแลกเปลี่ยนโทเค็นที่มีหน้าที่รับผิดชอบการแลกเปลี่ยน 2 ประเภท ได้แก่
  1. แลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นการรีเฟรชที่ใช้ได้นานและโทเค็นเพื่อการเข้าถึงที่ใช้ได้นาน การแลกเปลี่ยนนี้จะเกิดขึ้นเมื่อผู้ใช้เข้าสู่ กระบวนการเชื่อมโยงบัญชี
  2. แลกเปลี่ยนโทเค็นการรีเฟรชที่ใช้ได้นานกับโทเค็นเพื่อการเข้าถึงที่ใช้ได้ในระยะสั้น Exchange นี้จะเกิดขึ้นเมื่อ Google ต้องการโทเค็นเพื่อการเข้าถึงใหม่เนื่องจากโทเค็นหมดอายุ

แม้ว่าขั้นตอนการใช้รหัสโดยนัยจะง่ายกว่า Google ขอแนะนําว่าโทเค็นเพื่อการเข้าถึงที่ออกโดยใช้โฟลว์โดยนัยไม่มีวันหมดอายุ เนื่องจากการใช้การหมดอายุของโทเค็นด้วยขั้นตอนโดยนัยบังคับให้ผู้ใช้ลิงก์บัญชีอีกครั้ง หากคุณต้องการใช้การหมดอายุของโทเค็นด้วยเหตุผลด้านความปลอดภัย คุณควรพิจารณาการใช้ขั้นตอนการตรวจสอบสิทธิ์แทน

หมายเหตุ: โปรดเลือกขั้นตอน OAuth 2.0 ที่คุณต้องการใช้งาน หากจําเป็น เนื้อหาของคู่มือนี้จะโหลดซ้ําเพื่อปรับให้เข้ากับตัวเลือกของคุณ

รหัสการให้สิทธิ์ โฟลว์โดยนัย

ใช้การลิงก์บัญชี OAuth

หมายเหตุ: หากคุณใช้การลิงก์บัญชีเพื่อจัดการข้อมูลทางการเงิน โปรดทราบว่านโยบายเพิ่มเติมอาจมีผลบังคับใช้กับการดำเนินการของคุณ เราอาจใช้เวลาถึง 6 สัปดาห์ในการตรวจสอบการดำเนินการที่มีการลิงก์บัญชีสำหรับข้อมูลทางการเงิน ดังนั้นโปรดคำนึงถึงเวลาดังกล่าวเมื่อวางแผนกำหนดการเผยแพร่ โปรดตรวจสอบว่าคุณได้ปฏิบัติตามนโยบายบริการทางการเงินก่อนส่งการดำเนินการเข้ารับการตรวจสอบ

เพื่อช่วยให้กระบวนการตรวจสอบง่ายขึ้น

กำหนดค่าโปรเจ็กต์

หากต้องการกำหนดค่าโปรเจ็กต์เพื่อใช้การลิงก์ OAuth ให้ทำตามขั้นตอนต่อไปนี้

1. เปิดคอนโซล Actions แล้วเลือกโปรเจ็กต์ที่ต้องการใช้
2. คลิกแท็บพัฒนา และเลือกการลิงก์บัญชี
3. เปิดใช้สวิตช์ข้างการลิงก์บัญชี
4. ในส่วนการสร้างบัญชี ให้เลือกไม่ ฉันต้องการอนุญาตให้สร้างบัญชีบนเว็บไซต์เท่านั้น

5. ในประเภทการลิงก์ ให้เลือก OAuth และรหัสการให้สิทธิ์

   

6. ในส่วนข้อมูลลูกค้า:

   • กำหนดค่ารหัสลูกค้าที่ออกโดย Actions to Google เพื่อระบุคำขอที่มาจาก Google
   • จดบันทึกมูลค่าของรหัสลูกค้าที่ Google ออกให้กับการดำเนินการของคุณ
   • ใส่ URL สำหรับปลายทางการให้สิทธิ์และการแลกเปลี่ยนโทเค็น

หมายเหตุ: หากต้องการให้ส่งรหัสไคลเอ็นต์และข้อมูลลับเป็นสตริงที่เข้ารหัสแบบ Base64 ให้คลิกลูกศรแบบเลื่อนลงถัดจากกำหนดค่าไคลเอ็นต์ (ไม่บังคับ) แล้วเลือกช่อง Google เพื่อส่งรหัสไคลเอ็นต์และข้อมูลลับผ่านส่วนหัวการตรวจสอบสิทธิ์พื้นฐาน HTTP

6. คลิกบันทึก

ใช้งานเซิร์ฟเวอร์ OAuth

授权代码流程的 OAuth 2.0 服务器实现包括 两个端点，您的服务会通过 HTTPS 提供这两个端点。第一个端点 是授权端点，负责查找或获取 就数据访问征求用户意见。授权端点显示登录 尚未登录的用户的界面，并记录同意 请求的访问权限。第二个端点是令牌交换端点， 用于获取名为令牌（用于向 Action 用户授权）的加密字符串 以访问您的服务。

当您的 Action 需要调用您的某项服务的 API 时，Google 会使用这些 API 端点一起获取用户许可，以便在他们的 。

Google 发起的 OAuth 2.0 身份验证代码流程会话包含以下流程：

1. Google 会在用户的浏览器中打开您的授权端点。如果流 用户通过纯语音设备启动 Action，Google 会将 将代码执行到手机上

2. 用户登录（如果尚未登录）并授予 Google 以下权限： 通过您的 API 访问其数据。

   注意 ：您必须告知用户账号已与 Google 关联， 而不是特定的 Google 产品，例如 Google Home 或 Google 助理。

3. 您的服务会创建授权代码，并通过以下方式返回给 Google： 使用授权代码将用户的浏览器重定向回 Google 附件。

4. Google 会将授权代码发送到您的令牌交换端点， 验证代码的真实性并返回访问令牌和 刷新令牌。访问令牌是一个短期有效的令牌 作为访问 API 的凭据。刷新令牌长期有效 Google 可以存储该令牌，以便在用户首次访问该令牌时， 过期。

5. 在用户完成账号关联流程后， 从 Google 助理发送到您的 fulfillment webhook 的请求包含 访问令牌。

处理授权请求

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

授权端点参数
client_id	您在 Google 注册的 Google 客户端 ID。
redirect_uri	此请求的响应发送到的网址。
state	将一个在 重定向 URI。
scope	可选：一组以空格分隔的范围字符串，用于指定 Google 请求授权的数据
response_type	字符串 code。

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

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

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

1. 验证 client_id 与您注册的 Google 客户端 ID 是否一致 并且 redirect_uri 与 Google 提供的重定向网址相匹配 。这些检查对于防止向 意外或配置错误的客户端应用

   如果您支持多个 OAuth 2.0 流程，也请确认 response_type 为 code。

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

3. 生成 Google 将用于访问您的 API 的授权代码。 授权代码可以是任何字符串值，但它必须是唯一的 代表用户、令牌对应的客户端以及代码的有效期 而且不可猜测出来。您通常需要进行授权 会在大约 10 分钟后过期。

4. 确认 redirect_uri 参数指定的网址 采用以下格式：

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

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

5. 将用户的浏览器重定向到 redirect_uri 参数。添加您在 以及您在重定向时返回未经修改的原始状态值 方法是附加 code 和 state 参数。下面是一个示例 结果网址：

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

处理令牌交换请求

您的服务的令牌交换端点负责处理两种令牌 广告交易平台：

• 交换访问令牌和刷新令牌的授权代码
• 用刷新令牌换取访问令牌

令牌交换请求包含以下参数：

令牌交换端点参数
client_id	用于将请求来源标识为 Google 的字符串。此字符串必须 在您的系统中注册为 Google 的唯一标识符。
client_secret	您在 Google 中为您的服务注册的密钥字符串。
grant_type	所交换的令牌的类型。两者之一 authorization_code 或 refresh_token。
code	当 grant_type=authorization_code 时，代码 Google 从您的登录端点或令牌交换端点接收验证码。
redirect_uri	如果值为 grant_type=authorization_code，则此参数为 初始授权请求中使用的网址。
refresh_token	如果值为 grant_type=refresh_token，则刷新令牌 Google 从令牌交换端点接收的令牌

交换访问令牌和刷新令牌的授权代码

用户登录且您的授权端点返回短期授权后 代码，Google 就会向您的令牌交换端点发送请求， 访问令牌和刷新令牌的授权码。

对于这些请求，grant_type 的值为 authorization_code，值 code 是您先前向 Google 授予的授权代码的值。 以下是使用授权代码交换 访问令牌和刷新令牌：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

要将授权代码交换为访问令牌和刷新令牌，您的 令牌交换端点响应执行以下步骤的 POST 请求：

1. 验证 client_id 是否将请求来源标识为已获授权的来源。 并且 client_secret 与预期值匹配。
2. 请验证以下内容： <ph type="x-smartling-placeholder">
   </ph>
   • 授权代码有效且未过期，且客户端 请求中指定的 ID 与 授权代码。
   • redirect_uri 参数指定的网址完全相同 初始授权请求中使用的值。
3. 如果您无法验证上述所有条件，则返回 HTTP 正文为 {"error": "invalid_grant"} 的 400 Bad Request 错误。
4. 否则，使用授权代码中的用户 ID 生成刷新 令牌和访问令牌。这些标记可以是任何字符串值，但它们必须 唯一代表令牌的用户和客户端，不得 更容易被猜到。对于访问令牌，请记录令牌的到期时间 （通常在您发放令牌一小时后）。刷新令牌不会过期。
5. 在 HTTPS 响应的正文中返回以下 JSON 对象：

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

Google 会存储用户的访问令牌和刷新令牌，并记录 访问令牌的过期日期。访问令牌过期后，Google 会使用刷新 令牌，从令牌交换端点获取新的访问令牌。

用刷新令牌换取访问令牌

访问令牌过期后，Google 会向您的令牌交换端点发送请求 将刷新令牌交换为新的访问令牌。

对于这些请求，grant_type 的值为 refresh_token，值 refresh_token 是您之前授予 Google 的刷新令牌的值。 以下是用刷新令牌交换 访问令牌：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

如需将刷新令牌交换为访问令牌，令牌交换端点 对执行以下步骤的 POST 请求做出响应：

1. 验证 client_id 是否将请求来源标识为 并且 client_secret 与预期 值。
2. 请确认刷新令牌有效，以及在 请求与刷新令牌所关联的客户端 ID 相匹配。
3. 如果您无法验证上述所有条件，则返回 HTTP 正文为 {"error": "invalid_grant"} 的 400 Bad Request 错误。
4. 否则，请使用刷新令牌中的用户 ID 来生成访问权限 令牌。这些标记可以是任何字符串值，但它们必须唯一地表示 令牌对应的用户和客户端，并且不得被猜到。 对于访问令牌，请记录令牌的到期时间 （通常在您发放令牌一小时后）。
5. 在 HTTPS 的正文中返回以下 JSON 对象 回答：

   {
   "token_type": "不记名",
   "access_token": "ACCESS_TOKEN",
   “expires_in”：SECONDS_TO_EXPIRATION
   }

。

注意： 您可以选择在响应中返回新的 refresh_token。对于 如需详细了解何时首选返回新的 refresh_token，请参阅 使用令牌。

ออกแบบอินเทอร์เฟซผู้ใช้แบบเสียงสำหรับขั้นตอนการตรวจสอบสิทธิ์

คำเตือน: อย่าส่งข้อความแจ้งของการลิงก์บัญชีแก่ผู้ใช้เมื่อเริ่มต้นการสนทนากับการดำเนินการของคุณ แต่ให้มอบโฟลว์ผู้ใช้ที่ไม่ได้รับการตรวจสอบสิทธิ์เพื่อแสดงวิธีการทำงานของการดำเนินการของคุณแทน แล้วขอให้ลิงก์บัญชีในกรณีที่จำเป็นต้องดำเนินการเท่านั้น หากผู้ใช้ออกจากการดำเนินการอย่างต่อเนื่องเนื่องจากปัญหาในการลิงก์บัญชี Google จะไม่โปรโมตการดำเนินการดังกล่าวอย่างสม่ำเสมอ ซึ่งอาจลดการเข้าชมของผู้ใช้การดำเนินการดังกล่าว

หมายเหตุ: คุณต้องใช้ Action Builder เพื่อสร้างการดำเนินการที่ใช้การลิงก์บัญชี

ตรวจสอบว่าผู้ใช้ได้รับการยืนยันหรือไม่ และเริ่มขั้นตอนการลิงก์บัญชี

1. เปิดโปรเจ็กต์ Actions Builder ในคอนโซล Actions
2. สร้างฉากใหม่เพื่อเริ่มลิงก์บัญชีใน Action ของคุณ
   1. คลิกฉาก
   2. คลิกไอคอนเพิ่ม (+) เพื่อเพิ่มฉากใหม่
3. ในโหมดที่สร้างขึ้นใหม่ ให้คลิกไอคอนเพิ่ม สำหรับเงื่อนไข
4. เพิ่มเงื่อนไขที่ตรวจสอบว่าผู้ใช้ที่เชื่อมโยงกับการสนทนาเป็นผู้ใช้ที่ได้รับการยืนยันหรือไม่ หากการตรวจสอบไม่สำเร็จ การดำเนินการของคุณจะไม่สามารถลิงก์บัญชีในระหว่างการสนทนา และควรกลับไปให้สิทธิ์เข้าถึงฟังก์ชันการทำงานที่ไม่จำเป็นต้องมีการลิงก์บัญชี
   1. ในช่อง Enter new expression ในส่วนเงื่อนไข ให้ป้อนตรรกะต่อไปนี้ user.verificationStatus != "VERIFIED"
   2. ในส่วนการเปลี่ยน ให้เลือกฉากที่ไม่ต้องมีการลิงก์บัญชีหรือฉากที่เป็นจุดเข้าถึงฟังก์ชันการทำงานสำหรับผู้มาเยือนเท่านั้น

1. คลิกไอคอนเพิ่ม สำหรับเงื่อนไข
2. เพิ่มเงื่อนไขเพื่อทริกเกอร์โฟลว์การลิงก์บัญชีหากผู้ใช้ไม่มีข้อมูลระบุตัวตนที่เชื่อมโยง
   1. ในช่อง Enter new expression ในส่วนเงื่อนไข ให้ป้อนตรรกะต่อไปนี้ user.verificationStatus == "VERIFIED"
   2. ในส่วนการเปลี่ยน ให้เลือกโหมดระบบการลิงก์บัญชี
   3. คลิกบันทึก

เมื่อบันทึกแล้ว ระบบจะเพิ่มโหมดระบบการลิงก์บัญชีใหม่ที่ชื่อว่า <SceneName>_AccountLinking ลงในโปรเจ็กต์

ปรับแต่งฉากการลิงก์บัญชี

1. เลือกโหมดระบบการลิงก์บัญชีในส่วนฉาก
2. คลิกส่งพรอมต์ แล้วเพิ่มประโยคสั้นๆ เพื่ออธิบายให้ผู้ใช้ทราบว่าทำไมการดำเนินการจึงจำเป็นต้องเข้าถึงข้อมูลประจำตัว (เช่น "เพื่อบันทึกค่ากำหนดของคุณ")
3. คลิกบันทึก

1. ในส่วนเงื่อนไข ให้คลิกหากผู้ใช้ลิงก์บัญชีสำเร็จแล้ว
2. กำหนดค่าว่าขั้นตอนควรดำเนินการอย่างไรหากผู้ใช้ตกลงที่จะลิงก์บัญชี เช่น เรียกใช้เว็บฮุคเพื่อประมวลผลตรรกะทางธุรกิจที่กำหนดเองที่จำเป็น แล้วเปลี่ยนกลับไปยังฉากที่สร้างขึ้น
3. คลิกบันทึก

1. คลิกหากผู้ใช้ยกเลิกหรือปิดการลิงก์บัญชีในส่วนเงื่อนไข
2. กำหนดค่าว่าขั้นตอนควรดำเนินการอย่างไรหากผู้ใช้ไม่ตกลงที่จะลิงก์บัญชี เช่น ส่งข้อความตอบรับและเปลี่ยนเส้นทางไปยังฉากที่มีฟังก์ชันการทำงานที่ไม่ต้องใช้การลิงก์บัญชี
3. คลิกบันทึก

1. ในส่วนเงื่อนไข ให้คลิกหากระบบหรือเครือข่ายเกิดข้อผิดพลาด
2. กำหนดค่าว่าขั้นตอนควรดำเนินการอย่างไรหากดำเนินการลิงก์บัญชีไม่สำเร็จเนื่องจากข้อผิดพลาดของระบบหรือเครือข่าย เช่น ส่งข้อความตอบรับและเปลี่ยนเส้นทางไปยังฉากที่มีฟังก์ชันการทำงานที่ไม่ต้องใช้การลิงก์บัญชี
3. คลิกบันทึก

จัดการคำขอเข้าถึงข้อมูล

หากคำขอ Assistant มีโทเค็นเพื่อการเข้าถึง ก่อนอื่นให้ตรวจสอบว่าโทเค็นเพื่อการเข้าถึงถูกต้อง (และยังไม่หมดอายุ) แล้วจึงเรียกข้อมูลบัญชีผู้ใช้ที่เชื่อมโยงจากฐานข้อมูล