בדף העיון הזה מתועדים נקודות הקצה והממשקים ש-Google מציעה והאפליקציה שלכם משתמשת בהם במהלך תהליך קישור החשבון מבוסס-OAuth.
דרישות מוקדמות וסטנדרטים
כדי ליצור אינטראקציה מוצלחת עם נקודות הקצה האלה של Google, השילוב שלכם צריך לעמוד בסטנדרטים הבאים:
- OAuth 2.0: תואם ל-RFC 6749.
- אסימוני JWT (JSON Web Tokens): בהתאם ל-RFC 7519 (לקישור פשוט ול-RISC).
- אסימוני אירועי אבטחה: בהתאם ל-RFC 8417 (ל-RISC).
- HTTPS: כל הבקשות חייבות להתבצע דרך חיבור HTTPS מאובטח.
URI של הפניה לכתובת אחרת ב-OAuth
נקודת הקצה שאליה הדפדפן של המשתמש מופנה אחרי אימות והסכמה מוצלחים. פרמטר הנתיב YOUR_PARTNER_ID הוא מזהה השותף לקישור לחשבון Google (או מזהה הפרויקט) שהוגדר במהלך ההרשמה.
- כתובת ה-URL:
https://oauth-redirect.googleusercontent.com/r/YOUR_PARTNER_ID כתובת ה-URL של ארגז החול:
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PARTNER_IDשיטה:
GET(באמצעות הפניה אוטומטית של הדפדפן)
פרמטרים של בקשות
כשמפנים את המשתמש בחזרה אל Google, צריך לצרף פרמטרים לכתובת ה-URL. בהתאם לתהליך OAuth שבו משתמשים, הפרמטרים האלה מעוצבים כמחרוזת שאילתה (תהליך קוד אימות) או כפרגמנט URL (זרם הענקת גישה משתמע).
| פרמטר | תיאור |
|---|---|
code
|
(נדרש לתהליך קוד אימות) קוד האימות שנוצר על ידי השירות. |
state
|
(חובה) ערך הסטטוס שלא עבר שינוי, שהתקבל במקור מ-Google. |
access_token
|
(נדרש לזרימת אימות משתמשים מרומזת) אסימון הגישה לטווח ארוך שנוצר על ידי השירות. |
token_type
|
(חובה בתהליך הרשאה מרומז) הערך חייב להיות bearer. |
תשובות שגיאה
אם הבקשה ל-URI להפניה אוטומטית של OAuth היא פגומה, תקבלו שגיאה מסוג HTTP 400 Bad Request. גוף התגובה יכיל אובייקט JSON עם המבנה הבא:
| שדה | תיאור |
|---|---|
sendPostBody |
ההגדרה קובעת אם קוד ה-JS צריך להפנות מחדש אל redirectUri באמצעות POST. בדרך כלל false בתרחיש הזה. |
errorMessage |
הודעת שגיאה שתוצג ללקוח אם אי אפשר להשלים את ההפניה האוטומטית. אם יש קטעים חסרים, הערך הוא "A URI fragment or query string must be set." |
תשובות לשגיאות ב-OAuth 2.0
אם המשתמש לא מסכים או אם השירות נתקל בשגיאה, השירות צריך להפנות את המשתמש בחזרה לכתובת ה-URI להפניה אוטומטית של OAuth עם פרמטרים סטנדרטיים של שגיאות OAuth 2.0 (כמו error=access_denied). Google תעבד את הפרמטרים האלה ותציג למשתמש מסך שגיאה מתאים.
RISC API (אופציונלי)
השירות שלכם משתמש בפרוטוקול RISC כדי להודיע ל-Google באופן יזום כשמשתמש מבטל את הקישור של החשבון שלו בפלטפורמה שלכם, וכך לוודא שהפלטפורמות נשארות מסונכרנות.
- כתובת ה-URL:
https://risc.googleapis.com/v1/events:publish - שיטה:
POST - אימות: נדרש אסימון של חשבון שירות Google עם הרשאות מתאימות.
- Content-Type:
application/json
דרישות טוקן של אירוע אבטחה
אסימוני אירועי אבטחה שבהם אתם משתמשים כדי להודיע ל-Google על אירועים של ביטול אסימונים צריכים לעמוד בדרישות שבטבלה הבאה:
| מימוש | תיאור |
|---|---|
iss |
הצהרת המנפיק: זו כתובת URL שמתארחת אצלכם ומשותפת עם Google במהלך הרישום. |
aud |
טענת קהל: הטענה הזו מזהה את Google כמקבל של ה-JWT. הערך חייב להיות google_account_linking. |
jti |
טענת מזהה JWT: מזהה ייחודי שנוצר לכל אסימון של אירוע אבטחה. |
iat |
טענת Issued At: זהו ערך NumericDate שמייצג את הזמן שבו נוצר אסימון האירוע הזה. |
toe |
השעה שבה נרשמה התביעה על האירוע: זהו ערך אופציונלי NumericDate שמייצג את השעה שבה בוטל האסימון. |
exp |
הצהרה על תאריך התפוגה: אין לכלול את השדה הזה, כי האירוע שהוביל לשליחת ההתראה הזו כבר התרחש. |
events |
הצהרה על אירועי אבטחה: זהו אובייקט JSON, והוא חייב לכלול רק אירוע ביטול אחד של טוקן שמכיל את השדות הבאים:
|
מידע נוסף על סוגי שדות ופורמטים זמין במאמר בנושא JSON Web Token (JWT)
ממשק 'החלפת אפליקציות'
כדי להשתמש ב-App Flip, אפליקציית המובייל צריכה להחזיר את קוד ההרשאה או את טוקן הגישה לאפליקציית Google.
Android (תוצאת Intent)
האפליקציה נפתחת באמצעות אובייקט Intent. אחרי שהמשתמש מביע הסכמה, התהליך מסתיים ומוחזרת תוצאה ל-Google. מידע נוסף זמין במדריך ההטמעה ל-Android.
- פעולה:
com.google.android.gms.auth.CODE_AVAILABLE - תוספות:
code,state,access_token,token_type.
iOS (סכימה של כתובת URL מותאמת אישית וקישורים אוניברסליים)
האפליקציה שלכם פותחת את Google באמצעות סכימת כתובות URL מותאמת אישית או קישור אוניברסלי מסוג HTTPS. מידע נוסף זמין במדריך ההטמעה ל-iOS.
- פורמט:
<return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING