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

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

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

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

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

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

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

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

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

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

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

   

6. ในข้อมูลลูกค้า ให้ทำดังนี้

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

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

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

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

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

เซสชันขั้นตอนการใช้รหัสการตรวจสอบสิทธิ์ OAuth 2.0 ที่ Google เป็นผู้เริ่มจะมีขั้นตอนดังนี้

1. Google จะเปิดปลายทางการให้สิทธิ์ในเบราว์เซอร์ของผู้ใช้ หากขั้นตอน เริ่มต้นในอุปกรณ์ที่มีแต่เสียงสำหรับการดำเนินการ Google จะโอน กับโทรศัพท์

2. ผู้ใช้ลงชื่อเข้าใช้ (หากยังไม่ได้ลงชื่อเข้าใช้) และให้สิทธิ์ Google ในการ เข้าถึงข้อมูลของตนด้วย API ของคุณหากผู้ใช้เหล่านั้นยังไม่ได้ให้สิทธิ์

3. บริการของคุณจะสร้างรหัสการให้สิทธิ์และส่งคืนให้ Google ภายในวันที่ เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้กลับไปยัง Google ด้วยรหัสการให้สิทธิ์ ที่แนบมากับคำขอ

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

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

จัดการคำขอการให้สิทธิ์

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

ตัวอย่างเช่น หากปลายทางการให้สิทธิ์อยู่ที่ 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 ที่ลงทะเบียนไว้ Google และ redirect_uri ตรงกับ URL เปลี่ยนเส้นทางที่ Google ระบุไว้ สำหรับบริการของคุณ ซึ่งการตรวจสอบเหล่านี้มีความสําคัญในการป้องกันไม่ให้ให้สิทธิ์เข้าถึง แอปไคลเอ็นต์ที่ไม่ได้ตั้งใจหรือกำหนดค่าไม่ถูกต้อง

   หากคุณรองรับขั้นตอน OAuth 2.0 หลายขั้นตอน ให้ตรวจสอบด้วยว่า response_type คือcode

2. ตรวจสอบว่าผู้ใช้ลงชื่อเข้าใช้บริการของคุณหรือไม่ หากผู้ใช้ไม่ได้ลงชื่อเข้าใช้ ดำเนินการตามขั้นตอนการลงชื่อเข้าใช้หรือลงชื่อสมัครใช้บริการให้เสร็จสิ้น

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

4. ยืนยันว่า URL ที่ระบุโดยพารามิเตอร์ redirect_uri มีรูปแบบต่อไปนี้

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

   YOUR_PROJECT_ID คือรหัสในหน้าการตั้งค่าโปรเจ็กต์ ของคอนโซลการดำเนินการ

5. เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยัง URL ที่ระบุโดย พารามิเตอร์ redirect_uri ระบุรหัสการให้สิทธิ์ที่คุณ เพิ่งสร้าง และค่าสถานะเดิมที่ไม่มีการแก้ไขเมื่อคุณเปลี่ยนเส้นทาง ด้วยการเพิ่มพารามิเตอร์ code และ state ต่อท้าย ตัวอย่างมีดังต่อไปนี้ ของ URL ผลลัพธ์:

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

จัดการคำขอแลกเปลี่ยนโทเค็น

ปลายทางการแลกเปลี่ยนโทเค็นของบริการมีโทเค็น 2 ประเภท การแลกเปลี่ยน:

• แลกเปลี่ยนรหัสการให้สิทธิ์สำหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช
• แลกเปลี่ยนโทเค็นการรีเฟรชสำหรับโทเค็นเพื่อการเข้าถึง

คำขอแลกเปลี่ยนโทเค็นมีพารามิเตอร์ต่อไปนี้

แลกเปลี่ยนรหัสการให้สิทธิ์สำหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช

หลังจากผู้ใช้ลงชื่อเข้าใช้และอุปกรณ์ปลายทางของการให้สิทธิ์จะแสดงการให้สิทธิ์ที่มีอายุสั้น ไปยัง 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. โปรดตรวจสอบสิ่งต่อไปนี้
   • รหัสการให้สิทธิ์ถูกต้องและไม่หมดอายุ และไคลเอ็นต์ รหัสที่ระบุในคำขอตรงกับรหัสไคลเอ็นต์ที่เชื่อมโยงกับ รหัสการให้สิทธิ์ของคุณ
   • URL ที่ระบุโดยพารามิเตอร์ redirect_uri เหมือนกัน กับค่าที่ใช้ในคำขอการให้สิทธิ์เริ่มต้น
3. หากยืนยันเกณฑ์ข้างต้นทั้งหมดไม่ได้ ให้แสดงผล HTTP 400 ข้อผิดพลาด "คำขอไม่ถูกต้อง" ที่มี {"error": "invalid_grant"} เป็นเนื้อความ
4. หรือใช้รหัสผู้ใช้จากรหัสการให้สิทธิ์เพื่อสร้างการรีเฟรช และโทเค็นเพื่อการเข้าถึง โทเค็นเหล่านี้จะเป็นค่าสตริงใดก็ได้ แต่ต้อง เป็นตัวแทนของผู้ใช้และไคลเอ็นต์ที่ใช้โทเค็นโดยไม่ซ้ำกัน และจะต้องไม่ คาดเดาได้ สำหรับโทเค็นเพื่อการเข้าถึง ให้บันทึกเวลาหมดอายุของโทเค็นด้วย (โดยทั่วไปคือ 1 ชั่วโมงหลังจากคุณออกโทเค็น) โทเค็นการรีเฟรชไม่มีวันหมดอายุ
5. แสดงผลออบเจ็กต์ JSON ต่อไปนี้ในส่วนเนื้อหาของการตอบกลับ HTTPS

   {
   "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 ระบุที่มาของคำขอเป็น Google และ client_secret ตรงกับที่คาดไว้
2. ตรวจสอบว่าโทเค็นการรีเฟรชถูกต้อง และรหัสไคลเอ็นต์ที่ระบุใน คำขอตรงกับรหัสไคลเอ็นต์ที่เชื่อมโยงกับโทเค็นการรีเฟรช
3. หากยืนยันเกณฑ์ข้างต้นทั้งหมดไม่ได้ ให้แสดงผล HTTP 400 ข้อผิดพลาด "คำขอไม่ถูกต้อง" ที่มี {"error": "invalid_grant"} เป็นเนื้อความ
4. หรือใช้รหัสผู้ใช้จากโทเค็นการรีเฟรชเพื่อสร้างการเข้าถึง โทเค็น โทเค็นเหล่านี้จะเป็นค่าสตริงใดก็ได้ แต่จะต้องไม่ซ้ำกัน ผู้ใช้และไคลเอ็นต์ที่ใช้โทเค็น โดยต้องคาดเดาไม่ได้ สำหรับโทเค็นเพื่อการเข้าถึง ให้บันทึกเวลาหมดอายุของโทเค็นด้วย (โดยทั่วไปคือ 1 ชั่วโมงหลังจากคุณออกโทเค็น)
5. แสดงผลออบเจ็กต์ JSON ต่อไปนี้ในส่วนเนื้อหาของ HTTPS การตอบกลับ:

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

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

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

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

1. คลิกไอคอนเพิ่ม add สำหรับเงื่อนไข
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 มีโทเค็นเพื่อการเข้าถึง ให้ตรวจสอบก่อนว่าโทเค็นเพื่อการเข้าถึงนั้นถูกต้อง (และยังไม่หมดอายุ) จากนั้นดึงข้อมูลบัญชีผู้ใช้ที่เชื่อมโยงจากฐานข้อมูล