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

ระบบจะลิงก์บัญชีโดยใช้ขั้นตอน รหัสการให้สิทธิ์ OAuth 2.0 ซึ่งเป็นมาตรฐานอุตสาหกรรม

OAuth 2.1 และ PKCE สำหรับ Agent

เราขอแนะนำให้บังคับใช้ OAuth 2.1 สำหรับ Agent AI แบบไร้สถานะและไปป์ไลน์แบบมัลติโมดัล

  • PKCE (Proof Key for Code Exchange): ต้องใช้เพื่อรักษาความปลอดภัย ขั้นตอนรหัสการให้สิทธิ์ ซึ่งจะป้องกันการโจมตีแบบดักรับ
  • ไม่มีขั้นตอนการให้สิทธิ์โดยนัย: ขั้นตอนการให้สิทธิ์โดยนัยจะเปิดเผยโทเค็นเพื่อการเข้าถึงใน URL ซึ่งเป็นความเสี่ยงด้านความปลอดภัยสำหรับสภาพแวดล้อมของ Agent

บริการของคุณต้องรองรับปลายทาง การให้สิทธิ์และ การแลกเปลี่ยนโทเค็นที่สอดคล้องกับ OAuth 2.0/2.1

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. Click Create project.
  3. Enter a name or accept the generated suggestion.
  4. Confirm or edit any remaining fields.
  5. Click Create.

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.

  3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

    Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

    Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

    Support email: For users to contact you with questions about their consent.

    Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

    Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

    Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

    Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

    Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

    Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

  4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

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

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

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

การลิงก์บัญชี Google: ขั้นตอนรหัสการให้สิทธิ์ OAuth

แผนภาพลำดับต่อไปนี้แสดงรายละเอียดการโต้ตอบระหว่างผู้ใช้ Google และปลายทางของบริการ

ผู้ใช้ แอป Google / เบราว์เซอร์ เซิร์ฟเวอร์ของ Google ปลายทางการตรวจสอบสิทธิ์ของคุณ ปลายทางโทเค็นของคุณ 1. ผู้ใช้เริ่มการลิงก์ 2. เปลี่ยนเส้นทางไปยังปลายทางการให้สิทธิ์ (GET) client_id, redirect_uri, state, scope 3. แสดงหน้าจอลงชื่อเข้าใช้และความยินยอม 4. ผู้ใช้ตรวจสอบสิทธิ์และให้ความยินยอม 5. เปลี่ยนเส้นทางกลับไปที่ Google (GET) code, state 6. จัดการการเปลี่ยนเส้นทางและส่งรหัส/สถานะ 7. การแลกเปลี่ยนโทเค็น (POST) grant_type=authorization_code, code 8. ส่งคืนโทเค็น (200 OK) access_token, refresh_token 9. โทเค็นผู้ใช้ร้านค้า 10. เข้าถึงแหล่งข้อมูลของผู้ใช้
รูปที่ 1 ลำดับเหตุการณ์ในขั้นตอนรหัสการให้สิทธิ์ OAuth 2.0 สำหรับการลิงก์บัญชี Google

บทบาทและความรับผิดชอบ

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

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

เซสชันขั้นตอนรหัสการให้สิทธิ์ OAuth 2.0 ที่ Google เริ่มต้นจะมีโฟลว์ดังนี้

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

สูตรการติดตั้งใช้งาน

ทำตามขั้นตอนต่อไปนี้เพื่อใช้โฟลว์รหัสการให้สิทธิ์

ขั้นตอนที่ 1: จัดการคำขอการให้สิทธิ์

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

หากต้องการจัดการคำขอ ให้ดำเนินการต่อไปนี้

  1. ตรวจสอบคำขอ

    • ยืนยันว่า client_id ตรงกับรหัสไคลเอ็นต์ที่กำหนดให้กับ Google
    • ยืนยันว่า redirect_uri ตรงกับ URL การเปลี่ยนเส้นทางของ Google ที่คาดไว้ ดังนี้
      • Prod: https://oauth-redirect.googleusercontent.com/r/YOUR_PARTNER_ID
      • แซนด์บ็อกซ์: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PARTNER_ID
    • ตรวจสอบว่า response_type คือ code

  2. ตรวจสอบสิทธิ์ผู้ใช้:

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

  3. สร้างรหัสการให้สิทธิ์:

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

  4. เปลี่ยนเส้นทางกลับไปที่ Google

    • เปลี่ยนเส้นทางเบราว์เซอร์ไปยัง URL ที่ระบุใน redirect_uri
    • ต่อท้ายพารามิเตอร์การค้นหาต่อไปนี้
      • code: รหัสการให้สิทธิ์ที่คุณสร้าง
      • state: ค่าสถานะที่ไม่ได้แก้ไขซึ่งได้รับจาก Google

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

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

ก. แลกรหัสการให้สิทธิ์เป็นโทเค็น

เมื่อ Google ได้รับรหัสการให้สิทธิ์แล้ว ระบบจะเรียกใช้ปลายทางการแลกเปลี่ยนโทเค็น (POST) เพื่อดึงข้อมูลโทเค็น

  1. ตรวจสอบคำขอ

    • ยืนยัน client_id และ client_secret
    • ตรวจสอบว่ารหัสการให้สิทธิ์ถูกต้องและยังไม่หมดอายุ
    • ตรวจสอบว่า redirect_uri ตรงกับค่าที่ใช้ในขั้นตอนที่ 1
    • หากการตรวจสอบไม่สำเร็จ ให้ส่งคืน HTTP 400 Bad Request พร้อม {"error": "invalid_grant"}

  2. ออกโทเค็น

    • สร้างrefresh_tokenที่มีอายุการใช้งานยาวนานและaccess_tokenที่มีอายุการใช้งานสั้น (โดยปกติคือ 1 ชั่วโมง)
    • ส่งคืน HTTP 200 OK พร้อมการตอบกลับโทเค็น JSON มาตรฐาน

ข. รีเฟรชโทเค็นเพื่อการเข้าถึง

เมื่อโทเค็นเพื่อการเข้าถึงหมดอายุ Google จะขอโทเค็นใหม่โดยใช้โทเค็นการรีเฟรช

  1. ตรวจสอบคำขอ

    • ยืนยัน client_id, client_secret และ refresh_token
    • หากการตรวจสอบไม่สำเร็จ ให้ส่งคืน HTTP 400 Bad Request พร้อม {"error": "invalid_grant"}

  2. ออกโทเค็นเพื่อการเข้าถึงใหม่

    • สร้าง access_token ที่ใช้งานได้ชั่วคราวใหม่
    • ส่งคืน HTTP 200 OK พร้อมการตอบกลับโทเค็น JSON (รวมถึงโทเค็นการรีเฟรชใหม่ด้วยก็ได้)
จัดการคำขอ Userinfo

ปลายทาง userinfo เป็นทรัพยากรที่มีการป้องกันด้วย OAuth 2.0 ซึ่งส่งกลับการอ้างสิทธิ์เกี่ยวกับผู้ใช้ที่ลิงก์ การติดตั้งใช้งานและการโฮสต์ปลายทาง userinfo เป็นตัวเลือกที่ไม่บังคับ ยกเว้นกรณีการใช้งานต่อไปนี้

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

ส่วนหัวของคำขอปลายทางของ userinfo
Authorization header โทเค็นเพื่อการเข้าถึงของประเภท Bearer

ตัวอย่างเช่น หากปลายทาง userinfo พร้อมใช้งานที่ https://myservice.example.com/userinfo คำขออาจมีลักษณะดังต่อไปนี้

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

หากต้องการให้ปลายทาง userinfo จัดการคำขอ ให้ทำตามขั้นตอนต่อไปนี้

  1. แยกโทเค็นเพื่อการเข้าถึงจากส่วนหัวการให้สิทธิ์ แล้วแสดงผลข้อมูลสำหรับผู้ใช้ที่เชื่อมโยงกับโทเค็นเพื่อการเข้าถึง
  2. หากโทเค็นเพื่อการเข้าถึงไม่ถูกต้อง ให้แสดงข้อผิดพลาด HTTP 401 Unauthorized ด้วยการใช้ส่วนหัวการตอบกลับ WWW-Authenticate ตัวอย่างการตอบกลับข้อผิดพลาดเกี่ยวกับ Userinfo มีดังนี้ 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    หากข้อผิดพลาด 401 Unauthorized หรือการตอบกลับที่ผิดพลาดอื่นๆ ที่ไม่สำเร็จในระหว่างกระบวนการลิงก์ ข้อผิดพลาดดังกล่าวจะกู้คืนไม่ได้ ระบบจะทิ้งโทเค็นที่ดึงมาและผู้ใช้จะต้องเริ่มกระบวนการลิงก์อีกครั้ง

  3. หากโทเค็นเพื่อการเข้าถึงถูกต้อง ให้แสดงผลและการตอบสนอง HTTP 200 ด้วยออบเจ็กต์ JSON ต่อไปนี้ในเนื้อหาของ HTTPS การตอบกลับ: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     หากปลายทาง userinfo ส่งการตอบกลับที่สำเร็จ HTTP 200 ระบบจะลงทะเบียนโทเค็นที่ดึงมาและการอ้างสิทธิ์กับบัญชี Google ของผู้ใช้

    การตอบสนองของปลายทาง userinfo
    sub รหัสที่ไม่ซ้ำกันที่ระบุผู้ใช้ในระบบ
    email อีเมลของผู้ใช้
    given_name ไม่บังคับ: ชื่อของผู้ใช้
    family_name ไม่บังคับ: นามสกุลของผู้ใช้
    name ไม่บังคับ: ชื่อเต็มของผู้ใช้
    picture ไม่บังคับ: รูปโปรไฟล์ของผู้ใช้

การตรวจสอบการติดตั้งใช้งาน

คุณสามารถตรวจสอบการติดตั้งใช้งานได้โดยใช้เครื่องมือ OAuth 2.0 Playground

ในเครื่องมือ ให้ทำตามขั้นตอนต่อไปนี้

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

คุณสามารถตรวจสอบการติดตั้งใช้งานได้โดยใช้เครื่องมือสาธิตการลิงก์บัญชี Google

ในเครื่องมือ ให้ทำตามขั้นตอนต่อไปนี้

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