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	חובה. משך החיים שנותר של אסימון הגישה בשניות.

הערה: אפשר להחזיר refresh_token חדש בתגובה כש-Google מחליפה טוקן רענון בטוקן גישה חדש.

תשובות שגיאה

אם בקשה לנקודת הקצה של הטוקן נכשלת, צריך להחזיר שגיאה מסוג HTTP 400 Bad Request יחד עם תגובת JSON שמכילה את השדות הבאים:

• סטטוס HTTP: 400 Bad Request
• Content-Type: application/json;charset=UTF-8

שדות שגיאה (JSON)	תיאור
error	חובה. חייב להיות invalid_grant.
error_description	(אופציונלי) טקסט שאנשים יכולים לקרוא, שמספק מידע נוסף.

טיפול בכוונות של קישור פשוט

אם השירות שלכם תומך בקישור חשבונות פשוט (OAuth עם התחברות באמצעות חשבון Google), נקודת הקצה להחלפת אסימונים צריכה לתמוך גם בהצהרות של אסימוני JWT (‏JSON Web Token) וליישם את כוונות check ו-get הנדרשות, ואופציונלית את כוונת create.

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

הפרמטרים הבאים נמצאים בשימוש בבקשות האלה:

פרמטרים של בקשות

פרמטרים	תיאור
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	חובה להגדיר את הערך token לפרמטר create:

אימות 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 (אופציונלי)

הכוונה create היא אופציונלית. אם השירות שלכם תומך ביצירת חשבון באמצעות קישור פשוט, בקשה עם intent=create יוזמת את היצירה של חשבון משתמש חדש עם המידע שסופק ב-JWT.

• סטטוס HTTP: 200 OK
• Content-Type: application/json;charset=UTF-8

אובייקט ה-JSON של התגובה המוצלחת משתמש באותה מבנה בדיוק כמו תגובה רגילה מוצלחת של החלפת אסימון (החזרת access_token,‏ refresh_token וכו').

אם המשתמש כבר קיים, או אם השירות שלכם לא תומך ביצירת חשבון, מוחזרת שגיאת HTTP 401 כדי להנחות את Google לחזור לתהליך הקישור הרגיל של OAuth.

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