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

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

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

דרישות

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

איך זה עובד

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

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

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

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

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

Google שולחת בקשת POST לנקודת הקצה של האסימון שלכם כדי לשמור קוד הרשאה שאתם ממירים באסימון המזהה של המשתמש. הבקשה כוללת את אסימון הגישה של המשתמש וקוד הרשאה של 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

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

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

קוד הרשאה ל-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

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

אמת ותפענח את קביעת JWT

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

כאשר מפוענח, קביעת 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 email ו- hd תוכלו לקבוע אם גוגל מארחת וסמכותית לכתובת דוא"ל. במקרים בהם גוגל סמכותית ידוע כי המשתמש הוא כיום בעל החשבון הלגיטימי ואתה יכול לדלג על סיסמה או על שיטות אתגרים אחרות. אחרת, ניתן להשתמש בשיטות אלה לאימות החשבון לפני הקישור.

מקרים בהם Google סמכותית:

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

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