קישור חשבונות באמצעות OAuth

סוג הקישור OAuth תומך בשני תהליכים מקובלים בתחום של OAuth 2.0: התהליך המרומז והתהליך של קוד הרשאה.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

  • 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
  • 令牌交换端点，负责两种类型的交换：
    1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
    2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

הטמעה של קישור לחשבון OAuth

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

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

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

  5. בקטע סוג הקישור, בוחרים באפשרות OAuth ואז באפשרות מרומז.

  6. בקטע Client Information:

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

הטמעת שרת 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) של ההרשאה עם בקשה שכוללת את הפרמטרים הבאים:

פרמטרים של נקודת קצה להרשאה
client_id מזהה הלקוח שהקצית ל-Google.
redirect_uri כתובת ה-URL שאליה שולחים את התגובה לבקשה הזו.
state ערך של ניהול חשבונות שמועבר אל Google ללא שינוי URI להפניה אוטומטית.
response_type סוג הערך שיוחזר בתשובה. ל-OAuth 2.0 משתמע סוג התגובה הוא תמיד token.

לדוגמה, אם נקודת הקצה להרשאה זמינה ב-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.

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

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

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

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