סקירה כללית
קישור כניסה באמצעות חשבון Google המבוסס על OAuth מוסיף את הכניסה לחשבון, בנוסף לקישור OAuth. כך מתאפשרת חוויית קישור חלקה למשתמשי Google, וגם יצירה של חשבון, המאפשרת למשתמש ליצור חשבון חדש בשירות שלך באמצעות חשבון Google שלו.
כדי לבצע קישור חשבונות באמצעות OAuth וכניסה באמצעות Google, פעלו לפי השלבים הכלליים הבאים:
- קודם כל, צריך לבקש מהמשתמש להביע הסכמה כדי לגשת לפרופיל Google שלו.
- משתמשים במידע שבפרופיל שלו כדי לבדוק אם חשבון המשתמש קיים.
- מקשרים משתמשים קיימים.
- אם אתם לא מוצאים התאמה למשתמש Google במערכת האימות שלכם, עליכם לאמת את אסימון האימות שקיבלתם מ-Google. לאחר מכן תוכלו ליצור משתמש על סמך פרטי הפרופיל הכלולים באסימון המזהה.
איור 1. קישור חשבונות בטלפון של משתמש עם קישור בעיצוב נקי
דרישות לקישור פשוט
- מטמיעים את התהליך של קישור Web OAuth בסיסי. השירות חייב לתמוך בנקודות קצה (endpoint) מסוג הרשאה והחלפת אסימונים התואמות ל-OAuth 2.0.
- נקודת הקצה החלפת אסימונים חייבת לתמוך בהצהרות אסימון אינטרנט של JSON (JWT) וליישם את הכוונות
check
,create
ו-get
.
הטמעה של שרת ה-OAuth
נקודת הקצה של החלפת אסימונים חייבת לתמוך באובייקטים של check
, create
ו-get
. השלבים הבאים מציגים את השלבים שהושלמו בתהליך קישור החשבון, ומציינים מתי קריאות שונות לכוונות:
- האם למשתמש יש חשבון במערכת האימות שלך? (המשתמש מחליט: 'כן' או 'לא')
- כן : האם המשתמש משתמש בכתובת האימייל המשויכת לחשבון Google שלו כדי להיכנס לפלטפורמה? (המשתמש מחליט: 'כן' או 'לא')
- כן : האם למשתמש יש חשבון תואם במערכת האימות שלך? (
check intent
יתקשר כדי לאשר)- כן: התקבלה שיחה אל
get intent
והחשבון יקושר אם בקשת ההחזרה תגיע בהצלחה. - לא : ליצור חשבון חדש? (המשתמש מחליט: 'כן' או 'לא')
- כן : התקבלה שיחה מ-
create intent
, והחשבון יקושר אם כוונת הרכישה תשוחזר. - לא : תהליך ה-OAuth באינטרנט מופעל, המשתמש מופנה לדפדפן שלו, והמשתמש מקבל אפשרות לקשר עם כתובת אימייל אחרת.
- כן : התקבלה שיחה מ-
- כן: התקבלה שיחה אל
- לא : זרימת ה-OAuth מופעלת, המשתמש מופנה לדפדפן, והמשתמש מקבל אפשרות לקשר עם כתובת אימייל אחרת.
- כן : האם למשתמש יש חשבון תואם במערכת האימות שלך? (
- לא : האם למשתמש יש חשבון תואם במערכת האימות שלך? (
check intent
יתקשר כדי לאשר)- כן : התקבלה שיחה אל
get intent
והחשבון יקושר אם בקשת ההחזרה תגיע בהצלחה. - לא : בוצעה קריאה ל-
create intent
והחשבון מקושר אם כוונת הרכישה חוזרת בהצלחה.
- כן : התקבלה שיחה אל
- כן : האם המשתמש משתמש בכתובת האימייל המשויכת לחשבון Google שלו כדי להיכנס לפלטפורמה? (המשתמש מחליט: 'כן' או 'לא')
Check for an existing user account (check intent)
After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.
If the corresponding Google account is already present in your authentication
system, your token exchange endpoint responds with account_found=true
. If the
Google account doesn't match an existing user, your token exchange endpoint
returns an HTTP 404 Not Found error with account_found=false
.
The request has the following form:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Your token exchange endpoint must be able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is
check . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
To respond to the check
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Check if the Google account is already present in your authentication system.
אמת ותפענח את קביעת 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, אולם הבעלות על חשבון הדוא"ל של צד שלישי עשויה להשתנות מאז.
Check if the Google account is already present in your authentication system
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If either condition is true, the user has already signed up. In that case, return a response like the following:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
If neither the Google Account ID nor the email address specified in the
assertion matches a user in your database, the user hasn't signed up yet. In
this case, your token exchange endpoint needs to reply with a HTTP 404 error
that specifies "account_found": "false"
, as in the following example:
HTTP/1.1 404 Not found Content-Type: application/json;charset=UTF-8 { "account_found":"false", }
ניהול קישורים אוטומטיים (קבלת כוונה)
אחרי שהמשתמש מביע הסכמה לגשת לפרופיל Google שלו, Google שולחת בקשה שמכילה הצהרה חתומה של זהות המשתמש ב-Google. ההצהרה מכילה מידע שכולל את מזהה החשבון, השם וכתובת האימייל של המשתמש ב-Google. נקודת הקצה להמרת אסימון שהוגדרה לפרויקט שלך טופלה בבקשה הזו.
אם חשבון Google המתאים כבר קיים במערכת האימות, נקודת הקצה של החלפת האסימון מחזירה אסימון עבור המשתמש. אם
חשבון Google לא תואם למשתמש קיים, נקודת הקצה של החלפת האסימון מחזירה שגיאת linking_error
ואופציונלי, login_hint
.
הבקשה כוללת את הטופס הבא:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
נקודת הקצה של החלפת אסימונים חייבת להיות מסוגלת לטפל בפרמטרים הבאים:
פרמטרים של נקודת קצה לאסימון | |
---|---|
intent |
עבור הבקשות האלה, ערך הפרמטר הזה הוא get . |
grant_type |
סוג האסימון שיוחלף. לבקשות האלה, הפרמטר הזה כולל את הערך urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
אסימון Web JSON (JWT) המספק הצהרה חתומה של זהות המשתמש של Google. ה-JWT מכיל מידע שכולל את מזהה החשבון, השם וכתובת האימייל של המשתמש ב-Google. |
scope |
אופציונלי: היקפים שהגדרת ל-Google בקשת ממשתמשים. |
client_id |
מספר הלקוח שהקצית ל-Google. |
client_secret |
סוד הלקוח שהקצית ל-Google. |
כדי להגיב לבקשות של get
כוונות, נקודת הקצה של החלפת אסימונים צריכה לבצע את הפעולות הבאות:
- אימות ופענוח של הצהרת JWT.
- בודקים אם חשבון Google כבר קיים במערכת האימות.
אמת ותפענח את קביעת 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, אולם הבעלות על חשבון הדוא"ל של צד שלישי עשויה להשתנות מאז.
בדיקה אם חשבון Google כבר קיים במערכת האימות
בודקים אם אחד מהתנאים הבאים מתקיים:
- מספר חשבון Google נמצא בשדה
sub
' - כתובת האימייל שבביטוי תואמת למשתמש במסד הנתונים של המשתמש.
אם נמצא חשבון עבור המשתמש, צריך להנפיק אסימון גישה ולהחזיר את הערכים באובייקט JSON בגוף תגובת ה-HTTPS, למשל בדוגמה הבאה:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
במקרים מסוימים, הקישור של החשבון באמצעות אסימון מזהה עלול להיכשל עבור המשתמש. אם כן
מסיבה כלשהי, נקודת הקצה של החלפת האסימון צריכה להשיב עם שגיאת HTTP
401 שמציינת את error=linking_error
, כמו בדוגמה הבאה:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
כש-Google מקבלת תגובה לשגיאה 401 עם linking_error
, Google שולחת
את המשתמש לנקודת הקצה להרשאה עם login_hint
. המשתמש משלים את תהליך קישור החשבון באמצעות תהליך הקישור ל-OAuth בדפדפן שלו.
ניהול יצירת החשבון באמצעות כניסה באמצעות חשבון Google (יצירת כוונה)
כאשר משתמש צריך ליצור חשבון בשירות שלך, Google שולחת בקשה
לנקודת הקצה של החלפת אסימונים המציינת את intent=create
.
הבקשה כוללת את הטופס הבא:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
נקודת הקצה של החלפת האסימון צריכה לטפל בפרמטרים הבאים:
פרמטרים של נקודת קצה לאסימון | |
---|---|
intent |
עבור הבקשות האלה, ערך הפרמטר הזה הוא create . |
grant_type |
סוג האסימון שיוחלף. לבקשות האלה, הפרמטר הזה כולל את הערך urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
אסימון Web JSON (JWT) המספק הצהרה חתומה של זהות המשתמש של Google. ה-JWT מכיל מידע שכולל את מזהה החשבון, השם וכתובת האימייל של המשתמש ב-Google. |
client_id |
מספר הלקוח שהקצית ל-Google. |
client_secret |
סוד הלקוח שהקצית ל-Google. |
ה-JWT בפרמטר assertion
מכיל את מזהה חשבון Google, שם המשתמש וכתובת האימייל של המשתמש, שאפשר להשתמש בהם כדי ליצור חשבון חדש בשירות שלך.
כדי להגיב לבקשות של create
כוונות, נקודת הקצה של החלפת אסימונים צריכה לבצע את הפעולות הבאות:
- אימות ופענוח של הצהרת JWT.
- לאמת את פרטי המשתמש וליצור חשבון חדש.
אמת ותפענח את קביעת 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, אולם הבעלות על חשבון הדוא"ל של צד שלישי עשויה להשתנות מאז.
אימות פרטי משתמש ויצירת חשבון חדש
בודקים אם אחד מהתנאים הבאים מתקיים:
- מספר חשבון Google נמצא בשדה
sub
' - כתובת האימייל שבביטוי תואמת למשתמש במסד הנתונים של המשתמש.
אם אחד מהתנאים מתקיים, מבקשים מהמשתמש לקשר את החשבון הקיים
לחשבון Google שלו. לשם כך, יש להגיב לבקשה עם שגיאת HTTP 401
המציינת את error=linking_error
ומספקת את כתובת האימייל של המשתמש כ-login_hint
. לפניכם תשובה לדוגמה:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
כש-Google מקבלת תגובה לשגיאה 401 עם linking_error
, Google שולחת
את המשתמש לנקודת הקצה להרשאה עם login_hint
. המשתמש משלים את תהליך קישור החשבון באמצעות תהליך הקישור ל-OAuth בדפדפן שלו.
אם אף אחד מהתנאים אינו מתקיים, יש ליצור חשבון משתמש חדש עם הפרטים שמצוינים ב-JWT. לחשבונות חדשים לא מוגדרת בדרך כלל סיסמה. מומלץ להוסיף את הכניסה באמצעות חשבון Google לפלטפורמות אחרות, כדי לאפשר למשתמשים להתחבר לחשבון Google בפלטפורמות השונות של האפליקציה. לחלופין, אפשר לשלוח למשתמש אימייל שמתחיל את תהליך שחזור הסיסמה כדי לאפשר למשתמש להגדיר סיסמה כדי להיכנס לחשבון בפלטפורמות אחרות.
בסיום היצירה, יש להנפיק אסימון גישה ולרענן אסימון ולהחזיר את הערכים באובייקט JSON בגוף תגובת ה-HTTPS, כמו בדוגמה הבאה:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
קבלת מספר הלקוח של Google API
תצטרכו לספק את מספר הלקוח שלכם ב-Google API בתהליך ההרשמה לקישור.
כדי לקבל את מספר הלקוח של ה-API באמצעות הפרויקט שיצרתם בזמן השלמת השלבים של קישור OAuth. לשם כך, עליכם לבצע את השלבים הבאים:
- פותחים את הדף פרטי הכניסה במסוף Google API.
יוצרים או בוחרים פרויקט ב-Google APIs.
אם לפרויקט שלך אין Client-ID לסוג אפליקציית האינטרנט, לוחצים על יצירת פרטי כניסה ו-gt; מזהה לקוח ב-OAuth כדי ליצור מזהה. הקפידו לכלול את הדומיין של האתר שלכם בתיבה מקורות JavaScript מורשים. כשמבצעים בדיקות או פיתוח מקומיים, צריך להוסיף את
http://localhost
וגם אתhttp://localhost:<port_number>
לשדה מקורות JavaScript מורשים.
אימות ההטמעה
אתה יכול לאמת את הביצוע שלך באמצעות מגרש 2.0 OAuth הכלי.
בצע את הפעולות הבאות בכלי:
- לחץ תצורת כדי לפתוח את חלון תצורת 2.0 OAuth.
- בתחום זרימת OAuth, בחר בצד הלקוח.
- בתחום נקודות קצה OAuth, בחר Custom.
- ציין את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקצית ל- Google בשדות המתאימים.
- במקטע שלב 1, לא יבחר אף היקפי Google. במקום זאת, השאר שדה זה ריק או הקלד טווח תקף עבור השרת שלך (או מחרוזת שרירותית אם אינך משתמש בהיקפי OAuth). כשתסיים, לחץ על הרשה APIs.
- בסעיפים שלב 2 ושלב 3, לעבור את זרימת 2.0 OAuth ולוודא כי כל צעד עובד כמתוכנן.
אתה יכול לאמת את הביצוע שלך באמצעות קישור הדגמת חשבון Google הכלי.
בצע את הפעולות הבאות בכלי:
- לחץ על כניסה עם כפתור גוגל.
- בחר את החשבון שברצונך לקשר.
- הזן את מזהה השירות.
- לחלופין, הזן אחד או יותר טווחים שאליהם תבקש גישה.
- לחץ על התחל הדגמה.
- כשתתבקש, אשר שאתה רשאי להסכים ולדחות את בקשת הקישור.
- אשר שהפנית לפלטפורמה שלך.