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

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

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth 2.0 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

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

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

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

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

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

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

   

6. בקטע Client Information:

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

הערה: אם רוצים שמזהה הלקוח יישלח כמחרוזת עם קידוד base64, לוחצים על החץ לתפריט הנפתח לצד הגדרת הלקוח (אופציונלי) ומסמנים את התיבה Google to transmit clientID and secret via HTTP basic auth header (שליחת מזהה הלקוח והסוד מ-Google באמצעות כותרת אימות בסיסי של HTTP).

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

הטמעת שרת 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.

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

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

הערה: כדי ליצור פעולה שמטמיעה קישור לחשבון, צריך להשתמש בActions Builder.

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

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