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

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

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

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

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

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

אם אתם מאפשרים יצירה של חשבון משתמש באמצעות קול, Assistant שואלת את המשתמש אם הוא רוצה לבצע את הפעולות הבאות:

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

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

איסור יצירת חשבון באמצעות קול

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

מומלץ להשבית את האפשרות ליצור קבוצות במקרים הבאים:

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

• צריכה להיות לכם שליטה מלאה בתהליך יצירת החשבון. לדוגמה, תוכלו לא לאפשר יצירה אם אתם צריכים להציג למשתמש את התנאים וההגבלות שלכם במהלך יצירת החשבון.

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

החשבונות מקושרים באמצעות תהליכי OAuth 2.0 מקובלים בתחום. ‫Actions on Google תומך בזרם הענקת גישה משתמע ובזרם הענקת הרשאה באמצעות קוד.

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

בתהליך הקוד של ההרשאה, נדרשות שתי נקודות קצה:

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

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

הגדרת הפרויקט

כדי להגדיר את הפרויקט לשימוש בקישור פשוט, פועלים לפי השלבים הבאים:

1. פותחים את מסוף Actions ובוחרים את הפרויקט שרוצים להשתמש בו.
2. לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות קישור חשבונות.
3. מפעילים את המתג לצד קישור חשבונות.
4. בקטע Account creation, בוחרים באפשרות Yes.

5. בקטע סוג הקישור, בוחרים באפשרות OAuth & Google Sign In (‏OAuth וכניסה באמצעות חשבון Google) ובאפשרות Implicit (מרומז).

   

6. בקטע Client Information (פרטי הלקוח), מבצעים את הפעולות הבאות:

   • מקצים ערך למזהה הלקוח שהונפק על ידי Actions on Google כדי לזהות בקשות שמגיעות מ-Google.
   • מזינים את כתובות ה-URL של נקודות הקצה של ההרשאה ושל החלפת הטוקנים.

7. לוחצים על שמירה.

הטמעת שרת OAuth

כדי לתמוך בזרם הענקת גישה משתמע ב-OAuth 2.0, השירות שלכם יוצר הרשאה נקודת הקצה שזמינה ב-HTTPS. נקודת הקצה (endpoint) הזו אחראית לאימות קבלת הסכמה מהמשתמשים לצורך גישה לנתונים. נקודת הקצה של ההרשאה שמציג ממשק משתמש לכניסה למשתמשים שעדיין לא מחוברים לחשבון, להסכים להרשאת הגישה המבוקשת.

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

בסשן זרם הענקת גישה משתמע ב-OAuth 2.0 ש-Google יזמה, התהליך הבא:

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

טיפול בבקשות הרשאה

כשהפעולה צריכה לבצע קישור חשבונות באמצעות זרם הענקת גישה משתמע ב-OAuth 2.0, Google שולחת את המשתמש לנקודת הקצה (endpoint) של ההרשאה עם בקשה שכוללת את הפרמטרים הבאים:

לדוגמה, אם נקודת הקצה להרשאה זמינה ב-https://myservice.example.com/auth, בקשה עשויה להיראות כך:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

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

1. צריך לאמת את הערכים client_id ו-redirect_uri כדי למנוע הענקת גישה לאפליקציות לקוח לא מכוונות או שהוגדרו באופן שגוי:

   • צריך לוודא שה-client_id תואם למזהה הלקוח שהוקצו ל-Google.
   • מוודאים שכתובת ה-URL שצוינה ב-redirect_uri נראה כך:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID הוא המזהה שמופיע בדף הגדרות הפרויקט של 'מסוף הפעולות'.

2. לבדוק אם המשתמש נכנס לשירות. אם המשתמש לא חתום להשלים את תהליך הכניסה או ההרשמה לשירות.

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

4. לשלוח תגובת HTTP שמפנה מחדש את דפדפן המשתמש לכתובת ה-URL צוין על ידי הפרמטר redirect_uri. יש לכלול את כל את הפרמטרים הבאים בקטע של כתובת ה-URL:

   • access_token: אסימון הגישה שיצרתם כרגע
   • token_type: המחרוזת bearer
   • state: ערך המצב ללא שינוי מהמקור בקשה הדוגמה הבאה היא של כתובת ה-URL שתתקבל:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

ה-handler של Google להפניה אוטומטית ב-OAuth 2.0 יקבל את אסימון הגישה ויאשר שהערך של state לא השתנה. לאחר ש-Google קיבלה אסימון הגישה לשירות שלך, Google תצרף את האסימון לשיחות הבאות לפעולה כחלק מה-AppRequest.

处理自动关联

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

如果您的身份验证系统中已经存在相应的 Google 账号， 您的令牌交换端点为用户返回令牌。如果 Google 账号没有 匹配现有用户，您的令牌交换端点会返回 user_not_found 错误。

请求的格式如下：

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&consent_code=CONSENT_CODE&scope=SCOPES

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

当您的令牌交换端点收到关联请求时，它应该 以下：

验证和解码 JWT 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 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
  "locale": "en_US"
}

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

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

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

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

如果满足上述任一条件，则表明用户已经注册，您可以发出 访问令牌。

如果断言中指定的 Google 账号 ID 和电子邮件地址都没有 与您数据库中的用户匹配，表示该用户尚未注册。在这种情况下，您的 令牌交换端点应回复 HTTP 401 错误，指定 error=user_not_found， 如以下示例中所示：

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

{
  "error":"user_not_found",
}

通过 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&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]

assertion 参数包含 JSON Web 令牌 (JWT)，可提供 Google 用户的身份的已签名断言。JWT 包含 其中包含用户的 Google 账号 ID、姓名和电子邮件地址 为您的服务创建一个新账号。

如需响应账号创建请求，您的令牌交换端点必须执行以下操作 以下：

验证和解码 JWT 断言

您可以使用适用于您语言的 JWT 解码库来验证和解码 JWT 断言。 使用 Google 的公钥（适用于 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
  "locale": "en_US"
}

除了验证令牌的签名之外，还要验证断言的颁发者 （iss 字段）为 https://accounts.google.com，且受众群体（aud 字段） 是分配给您的 Action 的客户端 ID。

验证用户信息并创建新账号

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

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

如果满足上述任一条件，则提示用户将其现有账号关联 通过使用 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 登录功能添加到其他平台，以便用户能够 在您的应用的各个界面上通过 Google 投放广告。或者，您也可以 通过电子邮件向用户发送链接，启动密码恢复流程，以便用户设置 密码，以便在其他平台上登录。

创建完成后，发出一个访问令牌 并在 HTTPS 响应的正文，如以下示例所示：

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

עיצוב ממשק המשתמש הקולי לתהליך האימות

בודקים אם המשתמש מאומת ומתחילים את תהליך קישור החשבון

1. פותחים את הפרויקט ב-Actions Builder בקונסולה ל-Actions.
2. כדי ליצור סצנה חדשה ולהתחיל את קישור החשבון בפעולה:
   1. לוחצים על סצנות.
   2. לוחצים על סמל ההוספה (+) כדי להוסיף סצנה חדשה.
3. בסצנה החדשה שנוצרה, לוחצים על סמל ההוספה add ליד תנאים.
4. מוסיפים תנאי שבודק אם המשתמש שמשויך לשיחה הוא משתמש מאומת. אם הבדיקה נכשלת, הפעולה לא יכולה לבצע קישור חשבונות במהלך השיחה, והיא צריכה לחזור למצב שבו היא מספקת גישה לפונקציות שלא דורשות קישור חשבונות.
   1. בשדה Enter new expression בקטע תנאי, מזינים את הלוגיקה הבאה: user.verificationStatus != "VERIFIED"
   2. בקטע מעבר, בוחרים סצנה שלא דורשת קישור חשבון או סצנה שהיא נקודת הכניסה לפונקציונליות שזמינה רק לאורחים.

1. לוחצים על סמל ההוספה add לצד תנאים.
2. מוסיפים תנאי להפעלת תהליך קישור החשבון אם למשתמש אין זהות משויכת.
   1. בשדה Enter new expression בקטע תנאי, מזינים את הלוגיקה הבאה: user.verificationStatus == "VERIFIED"
   2. בקטע Transition (מעבר), בוחרים את סצנת המערכת Account Linking (קישור חשבונות).
   3. לוחצים על שמירה.

אחרי השמירה, נוספת לפרויקט סצנה חדשה של מערכת קישור חשבונות בשם <SceneName>_AccountLinking.

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

1. בקטע Scenes (סצנות), בוחרים את סצנת מערכת קישור החשבונות.
2. לוחצים על שליחת הנחיה ומוסיפים משפט קצר שמתאר למשתמש למה הפעולה צריכה לגשת לפרטי הזהות שלו (לדוגמה, "כדי לשמור את ההעדפות שלך").
3. לוחצים על שמירה.

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

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

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

טיפול בבקשות גישה לנתונים

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