Your Account Linking API

בדף ההפניה הזה מתועדים נקודות הקצה של ה-API שהשירות שלכם צריך להטמיע כדי לתמוך בקישור חשבונות ל-Google. האפשרויות האלה כוללות קישור OAuth, קישור חשבונות פשוט והחלפת אפליקציות.

דרישות מוקדמות וסטנדרטים

כדי להטמיע את נקודות הקצה האלה בהצלחה, השירות שלכם צריך לעמוד בתקנים הבאים:

  • ‫OAuth 2.0: תואם ל-RFC 6749.
  • ביטול טוקן: בהתאם ל-RFC 7009.
  • אסימוני JWT (‏JSON Web Tokens): בהתאם ל-RFC 7519 (נדרש לקישור פשוט).
  • ‫HTTPS: כל נקודות הקצה צריכות להיות מוצגות דרך חיבור HTTPS מאובטח.

Authorization Endpoint

נקודת הקצה של ההרשאה אחראית לאימות המשתמשים ולקבלת ההסכמה שלהם לקישור החשבונות שלהם ל-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).

Token Exchange Endpoint

נקודת הקצה הזו אחראית להחלפת קודי הרשאה באסימונים ולרענון אסימוני גישה שפג תוקפם.

  • כתובת 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 (אופציונלי) טקסט שאנשים יכולים לקרוא, שמספק מידע נוסף.

טיפול ב-Intents של קישור חשבונות פשוט

אם השירות שלכם תומך בקישור חשבונות פשוט (OAuth עם כניסה באמצעות חשבון Google), נקודת הקצה של החלפת האסימונים צריכה לתמוך גם בהצהרות של אסימוני JWT (‏JSON Web Token) וליישם את כוונות המשתמש 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 (זמינים בנקודת הקצה של Google מסוג JWK).
  • מנפיק (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.

נקודת קצה של פרטי המשתמש (אופציונלי)

היקף ההרשאה הזה משמש לאחזור מידע בסיסי על הפרופיל של המשתמש המקושר, כפי שמפורט במפרט OpenID Connect Core 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>