דף זה תורגם על ידי Cloud Translation API.

כניסה לחשבון מקושר

קישור של חשבון Google מאפשר לבעלי חשבון Google להתחבר במהירות, בצורה חלקה ובטוחה לשירותים שלך ולשתף נתונים עם Google.

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

דרישות

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

יש לך יישום של קישור OAuth של חשבון Google שתומך בתהליך באמצעות קוד הרשאה מסוג OAuth 2.0. הטמעת OAuth חייבת לכלול את נקודות הקצה הבאות:
- נקודת קצה (endpoint) הרשאה לטיפול בבקשות הרשאה.
- נקודת קצה (endpoint) של אסימון לטיפול בבקשה לאסימוני גישה ורענון.
- נקודת קצה של userinfo כדי לאחזר פרטי חשבון בסיסיים על המשתמש המקושר, שמוצגים למשתמש במהלך הכניסה לחשבון מקושר.
יש לכם אפליקציה ל-Android.

איך זה עובד

דרישות מוקדמות : המשתמש קישר בעבר את חשבון Google שלו לחשבון שלו בשירות שלך.

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

הטמעת כניסה לחשבון מקושר באפליקציה ל-Android

כדי לתמוך בכניסה לחשבון מקושר באפליקציה ל-Android, צריך לפעול לפי ההוראות שמפורטות במדריך ההטמעה של Android.

טיפול בבקשות לקוד הרשאה מ-Google

Google שולחת בקשת POST לנקודת הקצה (endpoint) של האסימון כדי לשמור קוד הרשאה שמחליפים באסימון המזהה של המשתמש. הבקשה מכילה את אסימון הגישה של המשתמש וקוד הרשאת OAuth2 ש-Google מנפיקה.

לפני שמירת קוד ההרשאה, עליך לאמת שאסימון הגישה שנתת ל-Google, שמזוהה על ידי client_id.

בקשת HTTP

בקשה לדוגמה

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN

נקודת הקצה (endpoint) של המרת האסימונים חייבת להיות מסוגלת לטפל בפרמטרים הבאים של הבקשה:

פרמטרים של נקודת קצה של אסימון
`code`	נדרש קוד הרשאה מסוג OAuth2 של Google
`client_id`	חובה מזהה הלקוח שהונפק ל-Google
`client_secret`	סוד לקוח נדרש שהונפק ל-Google
`access_token`	חובה אסימון גישה שהונפק ל-Google. נשתמש בשדה הזה כדי לקבל את ההקשר של המשתמש
`grant_type`	הערך חובה צריך להיות `urn:ietf:params:oauth:grant-type:reciprocal`

נקודת הקצה (endpoint) של המרת האסימון אמורה להגיב לבקשת ה-POST באופן הבא:

מוודאים שaccess_token הוענקה ל-Google שזוהתה על ידי client_id.
ניתן להשיב באמצעות תשובת HTTP 200 (OK) אם הבקשה תקינה וקוד ההרשאה הוחלף בהצלחה באסימון מזהה של Google, או בקוד שגיאת HTTP אם הבקשה לא חוקית.

תגובת HTTP

הפעולה הצליחה

החזרת קוד מצב HTTP 200 OK

דוגמה לתגובה מוצלחת

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}

שגיאות

במקרה של בקשת HTTP לא חוקית, מגיבים עם אחד מקודי שגיאות ה-HTTP הבאים:

קוד מצב HTTP	גוף	תיאור
400	`{"error": "invalid_request"}`	בבקשה חסר פרמטר ולכן השרת לא יכול להמשיך בתהליך הבקשה. אפשר גם להחזיר את השדה הזה אם הבקשה כוללת פרמטר שאינו נתמך או אם היא חוזרת על פרמטר
401	`{"error": "invalid_request"}`	אימות הלקוח נכשל. לדוגמה: אם הבקשה מכילה סוד או מזהה לקוח לא חוקיים
401	`{"error": "invalid_token"}` לכלול 'WWW-Authentication: Barder' בדיקת אימות בכותרת התשובה	אסימון הגישה של השותף לא חוקי.
403	`{"error": "insufficient_permission"}` לכלול 'WWW-Authentication: Bearer' בדיקת אימות בכותרת התשובה	אסימון הגישה של השותף לא מכיל את ההיקפים הנדרשים לביצוע פרוטוקול OAuth הדדי
500	`{"error": "internal_error"}`	שגיאה בחיבור לשרת

תגובת השגיאה צריכה להכיל את השדות הבאים :

שדות של תגובות לשגיאה
`error`	חובה מחרוזת שגיאה
`error_description`	תיאור קריא (לבני אדם) של השגיאה
`error_uri`	URI שמספק פרטים נוספים על השגיאה

דוגמה לתגובה מסוג שגיאה 400

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "Request was missing the 'access_token' parameter."
}

קוד הרשאה של Exchange באסימון מזהה

תצטרכו להחליף את קוד ההרשאה שקיבלתם באסימון מזהה של Google שמכיל מידע על חשבון Google של המשתמש.

כדי להחליף קוד הרשאה באסימון מזהה של Google, צריך להפעיל את נקודת הקצה https://oauth2.googleapis.com/token ולהגדיר את הפרמטרים הבאים:

שדות בקשה
`client_id`	חובה מזהה הלקוח שהתקבל מהדף 'פרטי כניסה' של מסוף ה-API. אלה יהיו בדרך כלל פרטי הכניסה עם השם New Actions on Google app (אפליקציית פעולות חדשות ב-Google).
`client_secret`	חובה סוד הלקוח שהתקבל מהדף 'פרטי כניסה' של מסוף ה-API
`code`	חובה קוד ההרשאה שנשלח בבקשה הראשונית
`grant_type`	חובה כפי שמוגדר במפרט OAuth 2.0, הערך בשדה הזה צריך להיות `authorization_code`.

בקשה לדוגמה

POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET

Google מגיבה לבקשה הזו על ידי החזרת אובייקט JSON שמכיל אסימון גישה לטווח קצר ואסימון רענון.

התשובה תכיל את השדות הבאים:

שדות תשובה
`access_token`	אסימון גישה שהונפק על ידי Google שהאפליקציה שלך שולחת כדי לאשר בקשה ל-Google API
`id_token`	האסימון המזהה מכיל את פרטי חשבון Google של המשתמש. בקטע אימות התגובה מוסבר איך מפענחים ומאמתים את התגובה של האסימון המזהה
`expires_in`	משך החיים שנותר לאסימון הגישה בשניות
`refresh_token`	אסימון שאפשר להשתמש בו כדי לקבל אסימון גישה חדש. אסימוני הרענון תקפים עד שהמשתמש מבטל את הגישה
`scope`	הערך בשדה הזה תמיד מוגדר כ-openid בתרחיש לדוגמה של 'כניסה לחשבון מקושר'
`token_type`	סוג האסימון המוחזר. בשלב הזה, הערך בשדה הזה תמיד מוגדר כ-`Bearer`

דוגמה לתשובה

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8

{
  "access_token": "Google-access-token",
  "id_token": "Google-ID-token",
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "openid",
  "refresh_token": "Google-refresh-token"
}


POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret

אימות התגובה של האסימון המזהה

אימות ופענוח של טענת הנכוֹנוּת (assertion) של JWT

אפשר לאמת ולפענח את טענת הנכוֹנוּת (assertion) של JWT באמצעות ספריית פענוח קוד JWT לשפה שלכם. כדאי להשתמש המפתחות הציבוריים של Google זמינים ב JWK או של PEM לצורך אימות לחתימה של האסימון.

אחרי הפענוח, טענת הנכוֹנוּת (assertion) של ה-JWT תיראה כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

בנוסף לאימות החתימה של האסימון, צריך לוודא מנפיק (השדה iss) הוא https://accounts.google.com, שהקהל (השדה aud) הוא מזהה הלקוח שהוקצה לך, ושתוקף האסימון לא פג (השדה exp).

באמצעות השדות email, email_verified ו-hd אפשר לקבוע אם Google מארחת כתובת אימייל מסוימת, והיא מהימן. במקרים שבהם Google מהימן, כרגע ידוע שהמשתמש הוא הבעלים החוקיים של החשבון ותוכלו לדלג על סיסמה או על שיטות אחרות לאתגרים. אחרת, השיטות האלה יכול לשמש לאימות החשבון לפני הקישור.

מקרים שבהם Google היא מהימן:

ל-email יש סיומת @gmail.com. זהו חשבון Gmail.
email_verified מוגדר כ-True ו-hd מוגדר. זהו חשבון G Suite.

משתמשים יכולים להירשם לחשבונות Google בלי להשתמש ב-Gmail או ב-G Suite. מתי email לא מכיל סיומת @gmail.com ו-hd חסר Google מומלץ לאמת סיסמה או סיסמה או שיטות אחרות לאימות למשתמש. email_verified יכול להיות גם נכון כי Google אימתה בהתחלה את משתמש כשחשבון Google נוצר, אבל בעלות על הצד השלישי ייתכן שחשבון האימייל השתנה מאז.