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

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

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

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

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

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

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

קוד אימות זרם משתמע

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

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

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

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

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

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

   

6. בקטע פרטי הלקוח:

   • מקצים ערך ל-Client ID שמונפק על ידי Google Actions כדי לזהות בקשות מ-Google.
   • יש להזין את כתובות ה-URL של נקודות הקצה של Authorization ו- Token Exchange.

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

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

הטמעה של שרת ה-OAuth

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

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

זהו תהליך גמיש משתמע של OAuth 2.0 ש-Google מפעילה, בתהליך הזה:

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

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

כשהפעולה צריכה לבצע קישור חשבונות באמצעות תהליך משתמע של OAuth 2.0, Google שולחת את המשתמש לנקודת הקצה להרשאה עם בקשה שכוללת את הפרמטרים הבאים:

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

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

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

תכנון ממשק המשתמש של הקול לתהליך האימות

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

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

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

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. בקטע מעבר, בוחרים בסצינת המערכת קישור חשבונות.
   3. לוחצים על שמירה.

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

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

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

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

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

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

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

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