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

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

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

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

דרישות

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

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

איך זה עובד

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

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

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

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

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

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

לפני שמירת קוד ההרשאה, עליך לוודא ש-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

נקודת הקצה של המרת האסימון צריכה להיות מסוגלת לטפל בפרמטרים הבאים של הבקשה:

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

נקודת הקצה של המרת האסימון צריכה להגיב לבקשת ה-POST כך:

מוודאים שה-access_token הוענק ל-Google שזוהתה על ידי client_id.
להגיב באמצעות תגובת HTTP 200 (OK) אם הבקשה תקינה וקוד ההרשאה הוחלף בהצלחה באסימון Google ID, או קוד שגיאת 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: Bearer" בכותרת התגובה	אסימון הגישה של השותף לא תקין.
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."
}

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

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

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

שדות בקשה
`client_id`	חובה: מזהה הלקוח שהתקבל בדף פרטי הכניסה של קונסולת ה-API. בדרך כלל מדובר בפרטי הכניסה עם השם New Actions on Google App
`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 נוצר, אבל בעלות על הצד השלישי ייתכן שחשבון האימייל השתנה מאז.