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