קישור יעיל באמצעות OAuth וכניסה באמצעות חשבון Google

סקירה כללית

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

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

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

איור 1. קישור חשבון בטלפון של משתמש באמצעות קישור פשוט

הדרישות לקישור פשוט

• מטמיעים את תהליך הקישור הבסיסי לחשבון באמצעות OAuth. השירות שלכם צריך לתמוך בנקודות קצה של הרשאה והחלפת אסימונים שתואמות ל-OAuth 2.0.
• נקודת הקצה של החלפת האסימונים חייבת לתמוך בהצהרות JSON Web Token (JWT) וליישם את הכוונות check,‏ create ו-get.

• רישום מזהה הלקוח ב-Google API

הטמעת שרת OAuth

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

1. האם למשתמש יש חשבון במערכת האימות שלכם? (המשתמש מחליט על ידי בחירה באפשרות 'כן' או 'לא')
   1. כן : המשתמש משתמש בכתובת האימייל שמשויכת לחשבון Google שלו כדי להיכנס לפלטפורמה שלכם. (המשתמש מחליט על ידי בחירה באפשרות 'כן' או 'לא')
      1. כן : האם למשתמש יש חשבון תואם במערכת האימות שלכם? (מתקשרים אל check intent כדי לאשר)
         1. ‫YES : מתבצעת שיחה אל get intent והחשבון מקושר אם הכוונה get מוחזרת בהצלחה.
         2. לא : ליצור חשבון חדש? (המשתמש בוחר באפשרות YES או NO)
            1. כן : מתבצעת שיחה עם create intent והחשבון מקושר אם כוונת היצירה מוחזרת בהצלחה.
            2. לא : תהליך OAuth באינטרנט מופעל, המשתמש מועבר לדפדפן שלו ומוצגת לו האפשרות לקשר עם כתובת אימייל אחרת.
      2. לא : מופעל תהליך OAuth בדפדפן, המשתמש מועבר לדפדפן שלו ומוצגת לו אפשרות לקשר עם כתובת אימייל אחרת.
   2. לא : האם למשתמש יש חשבון תואם במערכת האימות שלך? (מתקשרים אל check intent כדי לאשר)
      1. ‫YES : מתבצעת שיחה אל get intent והחשבון מקושר אם הכוונה get מוחזרת בהצלחה.
      2. לא : מתבצעת קריאה אל create intent והחשבון מקושר אם כוונת היצירה מוחזרת בהצלחה.

חיפוש חשבון משתמש קיים (בדיקת הכוונה)

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

אם חשבון Google התואם כבר קיים באימות המערכת, נקודת הקצה של המרת האסימונים מגיבה עם account_found=true. אם חשבון Google לא תואם למשתמש קיים, שהוא נקודת הקצה של המרת האסימונים מחזירה שגיאת HTTP 404 Not Found (לא נמצא) עם account_found=false.

הבקשה מוצגת בפורמט הבא:

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

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

כדי להגיב לבקשות Intent מסוג check, נקודת הקצה (endpoint) של המרת האסימונים חייבת לבצע את השלבים הבאים:

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

אימות ופענוח של טענת הנכוֹנוּת (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 נוצר, אבל בעלות על הצד השלישי ייתכן שחשבון האימייל השתנה מאז.

בודקים אם חשבון Google כבר קיים במערכת האימות

בודקים אם אחד מהתנאים הבאים מתקיים:

• מספר חשבון Google, שנמצא בשדה sub בטענת הנכונות (assertion) שלך, נמצא אצל המשתמש. מסד נתונים.
• כתובת האימייל בטענת הנכונות (assertion) תואמת למשתמש במסד הנתונים של המשתמשים.

אם אחד מהתנאים מתקיים, המשתמש כבר נרשם. במקרה הזה, תשובה כזו:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

אם מספר חשבון Google או כתובת האימייל לא צוינו טענת הנכוֹנוּת (assertion) תואמת למשתמש במסד הנתונים, המשתמש עדיין לא נרשם. לחשבון במקרה הזה, נקודת הקצה (endpoint) של המרת האסימון צריכה להשיב עם שגיאת HTTP 404 שמציין את "account_found": "false", כמו בדוגמה הבאה:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

处理自动链接（获取 intent）

在用户同意访问其 Google 个人资料后，Google 会发送 请求，其中包含 Google 用户身份的已签名断言。通过 断言包含的信息包括用户的 Google 账号 ID、 姓名和电子邮件地址为您的 Google Cloud 控制台配置的令牌交换端点 项目处理该请求。

如果您的身份验证中已有相应的 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

您的令牌交换端点必须能够处理以下参数：

如需响应 get intent 请求，您的令牌交换端点必须执行以下步骤：

• 验证和解码 JWT 断言。
• 检查您的身份验证系统中是否已存在该 Google 账号。

אימות ופענוח של טענת הנכוֹנוּת (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 נוצר, אבל בעלות על הצד השלישי ייתכן שחשבון האימייל השתנה מאז.

检查您的身份验证系统中是否已存在该 Google 账号

请检查以下任一条件是否成立：

• Google 账号 ID（可在断言的 sub 字段中找到）位于您的用户中 数据库。
• 断言中的电子邮件地址与用户数据库中的用户匹配。

如果找到了用户的账号，请发出访问令牌，并在 HTTPS 响应正文的 JSON 对象中返回相应值，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

在某些情况下，基于 ID 令牌的账号关联可能会失败。如果 因为任何原因，您的令牌交换端点都需要以 HTTP 响应 指定 error=linking_error 的 401 错误，如以下示例所示：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

当 Google 收到包含 linking_error 的 401 错误响应时，会发送 使用 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

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

ה-JWT בפרמטר assertion מכיל את מזהה חשבון Google של המשתמש, את השם וכתובת האימייל שלו, ואפשר להשתמש בו כדי ליצור חשבון חדש בשירות שלכם.

כדי להגיב לבקשות של Intent create, נקודת הקצה להחלפת טוקנים צריכה לבצע את השלבים הבאים:

• מאמתים ומפענחים את הצהרת ה-JWT.
• מאמתים את פרטי המשתמש ויוצרים חשבון חדש.

אימות ופענוח של טענת הנכוֹנוּת (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 נוצר, אבל בעלות על הצד השלישי ייתכן שחשבון האימייל השתנה מאז.

אימות פרטי המשתמש ויצירת חשבון חדש

בודקים אם אחד מהתנאים הבאים מתקיים:

• מזהה חשבון 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 שולחת את המשתמש לנקודת הקצה (endpoint) של ההרשאה עם 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. כדי לעשות זאת, פועלים לפי השלבים הבאים:

1. עוברים אל דף הלקוחות.

2. יוצרים פרויקט ב-Google APIs או בוחרים פרויקט קיים.

   אם בפרויקט שלכם אין מזהה לקוח מסוג אפליקציית אינטרנט, לוחצים על יצירת לקוח כדי ליצור אחד. חשוב להוסיף את הדומיין של האתר לתיבה מקורות מורשים של JavaScript. כשמבצעים בדיקות מקומיות או פיתוח, צריך להוסיף את http://localhost ואת http://localhost:<port_number> לשדה מקורות JavaScript מורשים.

אימות ההטמעה

כדי לאמת את ההטמעה, אפשר להשתמש בכלי OAuth 2.0 Playground.

בכלי, מבצעים את השלבים הבאים:

1. לוחצים על Configuration (הגדרה) settings כדי לפתוח את חלון ההגדרה של OAuth 2.0.
2. בשדה OAuth flow (תהליך OAuth), בוחרים באפשרות Client-side (בצד הלקוח).
3. בשדה OAuth Endpoints (נקודות קצה של OAuth), בוחרים באפשרות Custom (מותאם אישית).
4. בשדות המתאימים, מציינים את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקציתם ל-Google.
5. בקטע Step 1, לא בוחרים אף היקף של Google. במקום זאת, משאירים את השדה הזה ריק או מקלידים היקף הרשאות שתקף לשרת (או מחרוזת שרירותית אם לא משתמשים בהיקפי הרשאות OAuth). בסיום, לוחצים על הרשאת ממשקי API.
6. בקטעים שלב 2 ושלב 3, עוברים על תהליך ההרשאה באמצעות OAuth 2.0 ומוודאים שכל שלב פועל כמו שצריך.

כדי לאמת את ההטמעה, אפשר להשתמש בכלי Google Account Linking Demo.

בכלי, מבצעים את השלבים הבאים:

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