בדף העיון הזה מתועדים נקודות הקצה והממשקים ש-Google מציעה והאפליקציה שלכם משתמשת בהם במהלך תהליך קישור החשבון שמבוסס על OAuth.
דרישות מוקדמות וסטנדרטים
כדי ליצור אינטראקציה מוצלחת עם נקודות הקצה האלה של Google, השילוב שלכם צריך לעמוד בתקנים הבאים:
- OAuth 2.0: תואם ל-RFC 6749.
- אסימוני JWT (JSON Web Tokens): בהתאם ל-RFC 7519 (לקישור יעיל ול-RISC).
- אסימוני אירועי אבטחה: בהתאם ל-RFC 8417 (ל-RISC).
- HTTPS: כל הבקשות חייבות להתבצע דרך חיבור HTTPS מאובטח.
URI של הפניה אוטומטית ב-OAuth
נקודת הקצה שאליה הדפדפן של המשתמש מופנה על ידי השירות אחרי אימות והסכמה מוצלחים. פרמטר הנתיב YOUR_PROJECT_ID הוא המזהה שאתם מגדירים במהלך ההרשמה.
- כתובת ה-URL:
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID כתובת ה-URL של ארגז החול:
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_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)
ממשק 'החלפת אפליקציות'
במקרה של העברה בין אפליקציות, אפליקציית הנייד צריכה להחזיר את קוד ההרשאה או את אסימון הגישה לאפליקציית 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