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