Account Linking API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

สคีมา OpenAPI 3.1

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • สถานะ 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 ซึ่งจำเป็นสำหรับฟีเจอร์ต่างๆ เช่น "การลิงก์ที่มีประสิทธิภาพ" หรือ "การลงชื่อเข้าใช้ด้วย One Tap"

  • วิธีการ: 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>