การลิงก์บัญชีด้วย 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
   • ใส่ URL สำหรับปลายทางการให้สิทธิ์และการแลกเปลี่ยนโทเค็น

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

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

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

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

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

เซสชันโฟลว์แบบไม่เจาะจงปลายทางของ OAuth 2.0 ที่ Google เป็นผู้เริ่มต้นจะมีขั้นตอนดังต่อไปนี้

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

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

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

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

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

     YOUR_PROJECT_ID คือรหัสที่อยู่ในหน้าการตั้งค่าโปรเจ็กต์ของคอนโซล Actions

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

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

4. ส่งการตอบกลับ HTTP ที่เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยัง URL ที่พารามิเตอร์ redirect_uri ระบุไว้ รวมพารามิเตอร์ต่อไปนี้ทั้งหมดในส่วนย่อยของ URL

   • access_token: โทเค็นเพื่อการเข้าถึงที่คุณเพิ่งสร้าง
   • token_type: สตริง bearer
   • state: ค่าสถานะที่ไม่มีการแก้ไขจากคำขอเดิม ต่อไปนี้คือตัวอย่างของ URL ที่ได้

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

ตัวแฮนเดิลการเปลี่ยนเส้นทาง OAuth 2.0 ของ Google จะได้รับโทเค็นเพื่อการเข้าถึงและยืนยันว่าค่า state ไม่มีการเปลี่ยนแปลง หลังจาก Google ได้รับโทเค็นเพื่อการเข้าถึงสำหรับบริการของคุณแล้ว Google จะแนบโทเค็นนั้นกับการเรียกการดำเนินการของคุณในภายหลังโดยเป็นส่วนหนึ่งของ AppRequest

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

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