คู่มือแนวคิดการลิงก์ OAuth

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

การลิงก์ OAuth คือโซลูชันการลิงก์บัญชีที่แนะนำในกรณีต่อไปนี้

• คุณใช้เซิร์ฟเวอร์ OAuth 2.0 อยู่แล้วและไม่สามารถขยายปลายทางการแลกเปลี่ยนโทเค็นเพื่อเพิ่มการรองรับโปรโตคอลของ Google สำหรับการลิงก์อัตโนมัติและการสร้างบัญชีจากโทเค็นรหัส (เช่น เพิ่มพารามิเตอร์ intent=get และ intent=create ในคำขอไปยังปลายทางนี้)

โปรดดูหน้าเลือกประเภทการลิงก์บัญชีเพื่อยืนยันว่าการลิงก์ OAuth เป็นโซลูชันที่เหมาะกับคุณ

คำสำคัญ

ก่อนที่จะอ่านข้อมูลเกี่ยวกับวิธีการทำงานของการลิงก์ OAuth โปรดศึกษาคำศัพท์ต่อไปนี้

• user.verificationStatus: พร็อพเพอร์ตี้ที่ระบบกำหนดเพื่อระบุว่าเซสชันปัจจุบันมีผู้ใช้ที่ยืนยันแล้วหรือไม่

• user.accountLinkingStatus: พร็อพเพอร์ตี้ที่ระบบกำหนดเพื่อระบุว่าผู้ใช้ในเซสชันปัจจุบันมีข้อมูลประจำตัวที่ลิงก์หรือไม่

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

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

  ขั้นตอนนี้ต้องมีปลายทาง 2 แห่ง ดังนี้

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

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

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

• โทเค็นเพื่อการเข้าถึง: โทเค็นที่แลกเปลี่ยนกับโทเค็นเพื่อการเข้าถึงใหม่เมื่อโทเค็นเพื่อการเข้าถึงที่มีอายุสั้นหมดอายุ

วิธีการทำงาน

ส่วนนี้จะอธิบายขั้นตอนทั่วไปสำหรับรหัสการให้สิทธิ์ OAuth และขั้นตอนโดยนัย ส่วนขั้นตอนการลิงก์ OAuth ต่อไปนี้จะอธิบายขั้นตอนต่างๆ ที่อาจเกิดขึ้นกับ OAuth

การทำงานของรหัสการให้สิทธิ์สามารถสรุปได้ดังนี้

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

ขั้นตอนของโค้ดโดยนัยสรุปได้ดังนี้

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

ขั้นตอนพื้นฐานของรหัสการให้สิทธิ์มีดังนี้

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

ขั้นตอนการลิงก์ OAuth

หัวข้อนี้จะอธิบายขั้นตอนต่างๆ เกี่ยวกับการลิงก์ OAuth

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

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

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

ขั้นตอนที่ 1: ผู้ใช้ลงชื่อเข้าใช้ด้วยขั้นตอนโดยนัย

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

ขั้นตอนที่ 2: ผู้ใช้ลงชื่อเข้าใช้ด้วยขั้นตอนการใช้รหัสการให้สิทธิ์

หลังจากที่ผู้ใช้เข้าสู่ระบบและยืนยันข้อมูลเข้าสู่ระบบแล้ว บริการจะสร้างรหัสการให้สิทธิ์และส่งคืนให้กับ Google

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