Account Linking API

หน้านี้เป็นเอกสารอ้างอิงเกี่ยวกับปลายทาง API ที่บริการของคุณต้องใช้ เพื่อรองรับการลิงก์บัญชีกับ Google ซึ่งรวมถึง การลิงก์บัญชีที่อิงตาม OAuth, การลิงก์บัญชีที่ปรับปรุงแล้ว และ การสลับแอป

ข้อกำหนดเบื้องต้นและมาตรฐาน

บริการของคุณต้องเป็นไปตามมาตรฐานต่อไปนี้จึงจะติดตั้งใช้งานปลายทางเหล่านี้ได้สำเร็จ

  • OAuth 2.0: เป็นไปตาม RFC 6749
  • การเพิกถอนโทเค็น: เป็นไปตาม RFC 7009
  • JSON Web Token (JWT): เป็นไปตาม RFC 7519 (ต้องใช้สำหรับการลิงก์ที่คล่องตัว)
  • HTTPS: ต้องแสดงปลายทางทั้งหมดผ่านการเชื่อมต่อ HTTPS ที่ปลอดภัย

ปลายทางการให้สิทธิ์

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

  • URL: กำหนดค่าในคอนโซล Actions หรือ Google Cloud Console
  • วิธีการ: GET

พารามิเตอร์คำขอ

พารามิเตอร์ คำอธิบาย
client_id รหัสไคลเอ็นต์ที่คุณกำหนดให้กับ Google
redirect_uri URL ที่คุณส่งการตอบกลับคำขอนี้
state ค่าการทำบัญชีที่ส่งกลับไปยัง Google โดยไม่มีการเปลี่ยนแปลงใน URI การเปลี่ยนเส้นทาง
response_type ต้องเป็น code สำหรับขั้นตอนรหัสการให้สิทธิ์
scope (ไม่บังคับ) รายการขอบเขตที่คั่นด้วยช่องว่างสำหรับข้อมูลที่ Google ร้องขอ
user_locale (ไม่บังคับ) การตั้งค่าภาษาของบัญชี Google ที่ระบุโดยใช้แท็กภาษา BCP-47 (เช่น en-US)

ปลายทางการแลกเปลี่ยนโทเค็น

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

  • URL: กำหนดค่าในคอนโซล Actions หรือ Google Cloud Console
  • วิธีการ: POST
  • Content-Type: application/x-www-form-urlencoded

เปลี่ยนรหัสการให้สิทธิ์ของโทเค็น

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

พารามิเตอร์คำขอ

พารามิเตอร์ คำอธิบาย
client_id รหัสไคลเอ็นต์ที่คุณกำหนดให้กับ Google
client_secret รหัสลับไคลเอ็นต์ที่คุณกำหนดให้กับ Google
grant_type ต้องเป็น authorization_code
code รหัสการให้สิทธิ์ที่ได้รับจากปลายทางการให้สิทธิ์
redirect_uri URI เปลี่ยนเส้นทางเดียวกันกับที่ใช้ในคำขอเริ่มต้น

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

พารามิเตอร์ต่อไปนี้ใช้เมื่อรีเฟรชโทเค็นเพื่อการเข้าถึง

พารามิเตอร์คำขอ

พารามิเตอร์ คำอธิบาย
client_id รหัสไคลเอ็นต์ที่คุณกำหนดให้กับ Google
client_secret รหัสลับไคลเอ็นต์ที่คุณกำหนดให้กับ Google
grant_type ต้องเป็น refresh_token
refresh_token โทเค็นการรีเฟรชที่ออกให้ Google ก่อนหน้านี้

การตอบกลับ (JSON)

ส่งคืนการตอบกลับที่สำเร็จพร้อมออบเจ็กต์ JSON ในเนื้อหาของการตอบกลับ HTTPS

  • สถานะ HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
ช่อง คำอธิบาย
token_type ต้องระบุ ต้องเป็น bearer
access_token ต้องระบุ โทเค็นที่มีอายุสั้นซึ่งใช้เพื่อเข้าถึง API ของบริการ
refresh_token ต้องระบุสำหรับ authorization_code grant_type โทเค็นที่ใช้ได้นานซึ่งใช้เพื่อขอโทเค็นเพื่อการเข้าถึงใหม่
expires_in ต้องระบุ อายุการใช้งานที่เหลือของโทเค็นเพื่อการเข้าถึงเป็นวินาที

การตอบกลับข้อผิดพลาด

หากคำขอไปยังปลายทางโทเค็นล้มเหลว ให้แสดงข้อผิดพลาด HTTP 400 Bad Request พร้อมกับการตอบสนอง JSON ที่มีช่องต่อไปนี้

  • สถานะ HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
ฟิลด์ข้อผิดพลาด (JSON) คำอธิบาย
error ต้องระบุ ต้องเป็น invalid_grant
error_description (ไม่บังคับ) ข้อความที่มนุษย์อ่านได้ซึ่งให้ข้อมูลเพิ่มเติม

จัดการ Intent การลิงก์ที่มีประสิทธิภาพ

หากบริการรองรับการลิงก์บัญชีที่ปรับปรุงแล้ว (OAuth ที่ใช้การลงชื่อเข้าใช้ด้วย Google) ปลายทางการแลกเปลี่ยนโทเค็นต้องรองรับการยืนยัน JSON Web Token (JWT) เพิ่มเติม และใช้ Intent check, create และ get

คำขอเหล่านี้ใช้พารามิเตอร์ต่อไปนี้

พารามิเตอร์คำขอ

พารามิเตอร์ คำอธิบาย
intent ความตั้งใจในการลิงก์ที่มีประสิทธิภาพเฉพาะที่ขอ: check, get หรือ create
grant_type สำหรับคำขอเหล่านี้ พารามิเตอร์นี้จะมีค่า urn:ietf:params:oauth:grant-type:jwt-bearer เสมอ
assertion โทเค็นเว็บ JSON (JWT) ที่ให้การยืนยันตัวตนของผู้ใช้ Google ที่ลงนามแล้ว JWT มีข้อมูลซึ่งรวมถึงรหัสบัญชี Google, ชื่อ และอีเมลของผู้ใช้

เซิร์ฟเวอร์ต้องตรวจสอบ JWT นี้โดยใช้เกณฑ์ที่ระบุไว้ในส่วนการตรวจสอบ JWT
client_id รหัสไคลเอ็นต์ที่คุณกำหนดให้กับ Google
client_secret รหัสลับไคลเอ็นต์ที่คุณกำหนดให้กับ Google
scope ไม่บังคับ: ขอบเขตใดก็ตามที่คุณกำหนดค่าให้ Google ขอจากผู้ใช้ มักจะแสดงในความตั้งใจ get และ create
response_type ต้องระบุสำหรับเจตนา create: ต้องตั้งค่าเป็น token

การตรวจสอบ JWT

เซิร์ฟเวอร์ของคุณต้องตรวจสอบความถูกต้องของ assertion (JWT) ตามเกณฑ์ต่อไปนี้เพื่อให้การลิงก์ที่ปรับปรุงแล้วมีความปลอดภัย

  • ลายเซ็น: ยืนยันลายเซ็นกับคีย์สาธารณะของ Google (ดูได้ที่ปลายทาง JWK ของ Google)
  • ผู้ออก (iss): ต้องเป็น https://accounts.google.com
  • กลุ่มเป้าหมาย (aud): ต้องตรงกับรหัสไคลเอ็นต์ของ Google API ที่กำหนดให้กับการผสานรวม ของคุณ
  • วันหมดอายุ (exp): ต้องเป็นวันที่ในอนาคต

การตอบกลับสำหรับความตั้งใจ check

คำขอที่มี intent=check จะตรวจสอบว่าบัญชี Google (ระบุโดยการอ้างสิทธิ์ sub หรือ email ในการยืนยัน JWT ที่ถอดรหัสแล้ว) มีอยู่ในฐานข้อมูลผู้ใช้หรือไม่

  • สถานะ HTTP: 200 OK (พบบัญชี) หรือ 404 Not Found (ไม่พบบัญชี)
  • Content-Type: application/json;charset=UTF-8
ช่อง คำอธิบาย
account_found ต้องระบุ true หากมีบัญชีอยู่ false มิฉะนั้น

การตอบกลับสำหรับความตั้งใจ get

คำขอที่มี intent=get จะขอโทเค็นเพื่อการเข้าถึงสำหรับบัญชี Google ที่มีอยู่

  • สถานะ HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

ออบเจ็กต์ JSON ของการตอบกลับที่สำเร็จจะใช้โครงสร้างเดียวกับการตอบกลับการแลกเปลี่ยนโทเค็นมาตรฐานที่สำเร็จ (แสดงผล access_token, refresh_token ฯลฯ)

หากลิงก์บัญชีไม่ได้ ระบบจะแสดงข้อผิดพลาด HTTP 401

  • สถานะ HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
ฟิลด์ข้อผิดพลาด (JSON) คำอธิบาย
error ต้องระบุ ต้องเป็น linking_error
login_hint (ไม่บังคับ) อีเมลของผู้ใช้ที่จะส่งไปยังขั้นตอนการลิงก์ OAuth แบบสำรอง

การตอบกลับสำหรับความตั้งใจ create

คำขอที่มี intent=create จะขอสร้างบัญชีผู้ใช้ใหม่โดยใช้ ข้อมูลที่ระบุใน JWT

  • สถานะ HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

ออบเจ็กต์ JSON ของการตอบกลับที่สำเร็จจะใช้โครงสร้างเดียวกับการตอบกลับการแลกเปลี่ยนโทเค็นมาตรฐานที่สำเร็จ (แสดงผล access_token, refresh_token ฯลฯ)

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

  • สถานะ HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
ฟิลด์ข้อผิดพลาด (JSON) คำอธิบาย
error ต้องระบุ ต้องเป็น linking_error
login_hint อีเมลของผู้ใช้ที่จะส่งไปยังโฟลว์การลิงก์ OAuth แบบสำรอง

ปลายทาง UserInfo (ไม่บังคับ)

ใช้เพื่อดึงข้อมูลโปรไฟล์พื้นฐานเกี่ยวกับผู้ใช้ที่ลิงก์ตามที่ระบุไว้ ในข้อกำหนดหลักของ OpenID Connect 1.0 คุณต้องดำเนินการนี้สำหรับฟีเจอร์ต่างๆ เช่น "การลิงก์ที่ราบรื่น" หรือ "การลงชื่อเข้าใช้ด้วยการแตะเพียงครั้งเดียว"

  • วิธีการ: GET
  • การตรวจสอบสิทธิ์: Authorization: Bearer ACCESS_TOKEN

การตอบกลับ (JSON)

ส่งคืนการตอบกลับที่สำเร็จพร้อมออบเจ็กต์ JSON ในเนื้อหาของการตอบกลับ HTTPS

  • สถานะ HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

ฟิลด์การตอบกลับ

ช่อง คำอธิบาย
sub ต้องระบุ รหัสที่ไม่ซ้ำกันซึ่งระบุผู้ใช้ในระบบของคุณ
email ต้องระบุ อีเมลของผู้ใช้
email_verified ต้องระบุ บูลีนที่ระบุว่าอีเมลได้รับการยืนยันแล้วหรือไม่
given_name (ไม่บังคับ) ชื่อจริงของผู้ใช้
family_name (ไม่บังคับ) นามสกุลของผู้ใช้
name (ไม่บังคับ) ชื่อเต็มของผู้ใช้
picture (ไม่บังคับ) URL ของรูปโปรไฟล์ผู้ใช้

การตอบกลับข้อผิดพลาด

หากโทเค็นเพื่อการเข้าถึงไม่ถูกต้องหรือหมดอายุ ให้แสดงข้อผิดพลาด HTTP 401 Unauthorized นอกจากนี้ คุณควรใส่ส่วนหัวการตอบกลับ WWW-Authenticate ด้วย

การตอบกลับที่ไม่สำเร็จ (4xx หรือ 5xx) ที่แสดงผลในระหว่างกระบวนการลิงก์จะถือว่ากู้คืนไม่ได้ ในกรณีเหล่านี้ Google จะทิ้งโทเค็นที่เรียกคืนมา และผู้ใช้ต้องเริ่มกระบวนการลิงก์บัญชีอีกครั้ง

ปลายทางการเพิกถอนโทเค็น (ไม่บังคับ)

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

  • วิธีการ: POST
  • Content-Type: application/x-www-form-urlencoded

พารามิเตอร์คำขอ

พารามิเตอร์ คำอธิบาย
client_id สตริงที่ระบุแหล่งที่มาของคำขอเป็น Google คุณต้องลงทะเบียนสตริงนี้ภายในระบบเป็นตัวระบุที่ไม่ซ้ำกันของ Google
client_secret สตริงลับที่คุณลงทะเบียนกับ Google สําหรับบริการของคุณ
token โทเค็นที่จะเพิกถอน
token_type_hint (ไม่บังคับ) คำใบ้เกี่ยวกับประเภทของโทเค็นที่ถูกเพิกถอน ไม่ว่าจะเป็น access_token หรือ refresh_token หากไม่ได้ระบุไว้ ระบบจะใช้ access_token เป็นค่าเริ่มต้น

คำตอบ

ส่งการตอบกลับที่สำเร็จเมื่อลบโทเค็นสำเร็จ หรือหากโทเค็นไม่ถูกต้องอยู่แล้ว

  • สถานะ HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

การตอบกลับข้อผิดพลาด

หากลบโทเค็นไม่ได้ไม่ว่าด้วยเหตุผลใดก็ตาม (เช่น ฐานข้อมูลไม่พร้อมใช้งาน) ให้แสดงข้อผิดพลาด HTTP 503 Google จะลองส่งคำขออีกครั้งในภายหลังหรือตามที่ระบุไว้ในส่วนหัว Retry-After

  • สถานะ HTTP: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • ส่วนหัว: Retry-After: <HTTP-date / delay-seconds>