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

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

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

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

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

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

注意 ：请选择您希望实施的 OAuth 2.0 流程。如果需要，本指南的内容会根据您的选择重新加载。

身份验证代码 隐式流程

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

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

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

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

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

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

   

6. בקטע Client Information:

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

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

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

הטמעת שרת OAuth

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

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

סשן זרימת קוד אימות OAuth 2.0 ש-Google יזמה:

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

2. המשתמש נכנס לחשבון (אם הוא עדיין לא מחובר) ומעניק ל-Google הרשאה לגשת לנתונים שלהם באמצעות ה-API, אם הם עדיין לא העניקו הרשאה.

   הערה: עליך להודיע על קישור חשבון המשתמש ל-Google, ולא למוצר ספציפי של Google, כמו Google Home או Google Assistant.

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

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

5. אחרי שהמשתמש משלים את תהליך קישור החשבון, כל קישור שנשלחה מ-Assistant ל-webhook של מילוי הבקשה, מכילה אסימון גישה.

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

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

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

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

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

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

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

   אם אתם תומכים בכמה תהליכי OAuth 2.0, צריך גם לוודא response_type היא code.

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

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

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

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

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

5. מפנים את דפדפן המשתמש לכתובת ה-URL שצוינה ב- הפרמטר redirect_uri. מוסיפים את קוד ההרשאה שנוצר עכשיו והערך של המצב המקורי שלא השתנה כאשר מבצעים הפניה אוטומטית על ידי הוספת הפרמטרים code ו-state. זאת דוגמה של כתובת ה-URL שתתקבל:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

טיפול בבקשות להחלפת אסימונים

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

• המרת קודי הרשאה באסימוני גישה ובאסימוני רענון
• המרת אסימוני רענון באסימוני גישה

בקשות להחלפת אסימונים כוללות את הפרמטרים הבאים:

פרמטרים של נקודת קצה להחלפת אסימונים
client_id	מחרוזת המזהה את מקור הבקשה כ-Google. המחרוזת הזו חייבת יהיה רשום במערכת שלך כמזהה הייחודי של Google.
client_secret	מחרוזת סודית שרשמתם ב-Google לשירות שלכם.
grant_type	סוג האסימון המוחלף. אחד משני הערכים authorization_code או refresh_token.
code	כאשר grant_type=authorization_code, הקוד Google שהתקבלו מנקודת הקצה של הכניסה או של המרת האסימון.
redirect_uri	כשהערך הוא grant_type=authorization_code, הפרמטר הזה כתובת ה-URL ששימשה בבקשת ההרשאה הראשונית.
refresh_token	כאשר grant_type=refresh_token, אסימון הרענון Google שהתקבלו מנקודת הקצה של המרת האסימונים.

המרת קודי הרשאה באסימוני גישה ובאסימוני רענון

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

בבקשות האלה, הערך של grant_type הוא authorization_code והערך code הוא הערך של קוד ההרשאה שנתת ל-Google בעבר. דוגמה לבקשה להחלפת קוד הרשאה אסימון גישה ואסימון רענון:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

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

1. מוודאים ש-client_id מזהה את מקור הבקשה כמקור מורשה, ושה-client_secret תואם לערך הצפוי.
2. מוודאים את הפרטים הבאים:
   • קוד ההרשאה חוקי ולא פג, והלקוח המזהה שצוין בבקשה תואם למזהה הלקוח שמשויך אל קוד הרשאה.
   • כתובת ה-URL שצוינה על ידי הפרמטר redirect_uri זהה לערך שנעשה בו שימוש בבקשת ההרשאה הראשונית.
3. אם אין אפשרות לאמת את כל הקריטריונים שלמעלה, צריך להחזיר HTTP שגיאה מסוג 'בקשה שגויה' 400 עם {"error": "invalid_grant"} בגוף ההודעה.
4. אחרת, באמצעות מזהה המשתמש מקוד ההרשאה, צריך ליצור רענון וגם אסימון גישה. האסימונים האלה יכולים להיות כל ערכי מחרוזת, אבל הם חייבים מייצגים באופן ייחודי את המשתמש ואת הלקוח שעבורו האסימון מיועד, ואסור להם שאפשר לנחש. לאסימוני גישה, צריך לתעד גם את זמן התפוגה של האסימון (בדרך כלל שעה אחרי הנפקת האסימון). אין תפוגה לאסימוני רענון.
5. מחזירים את אובייקט ה-JSON הבא בגוף תגובת ה-HTTPS:

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

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

המרת אסימוני רענון באסימוני גישה

כשפג התוקף של אסימון הגישה, Google שולחת בקשה לנקודת הקצה (endpoint) של המרת האסימון כדי להחליף אסימון רענון באסימון גישה חדש.

בבקשות האלה, הערך של grant_type הוא refresh_token והערך של refresh_token הוא הערך של אסימון הרענון שהענקת ל-Google בעבר. דוגמה לבקשה להחלפת אסימון רענון אסימון גישה:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

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

1. אימות שה-client_id מזהה את מקור הבקשה בתור Google, ושהclient_secret תואם לציפיות עם ערך מסוים.
2. יש לוודא שאסימון הרענון חוקי, ושמזהה הלקוח שצוין ב- הבקשה תואמת למזהה הלקוח שמשויך לאסימון הרענון.
3. אם אין אפשרות לאמת את כל הקריטריונים שלמעלה, צריך להחזיר HTTP שגיאה מסוג 'בקשה שגויה' 400 עם {"error": "invalid_grant"} בגוף ההודעה.
4. אחרת, משתמשים במזהה המשתמש מאסימון הרענון כדי ליצור גישה ב-Assistant. האסימונים האלה יכולים להיות כל ערכי מחרוזת, אבל הם חייבים לייצג באופן ייחודי בין המשתמש ובין הלקוח שבשבילו האסימון, ואסור לנחש אותם. לאסימוני גישה, צריך לתעד גם את זמן התפוגה של האסימון (בדרך כלל שעה אחרי הנפקת האסימון).
5. החזרת אובייקט ה-JSON הבא בגוף ה-HTTPS תגובה:

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

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

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

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