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

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

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

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

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

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

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

קוד אימות תהליך משתמע

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

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

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

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

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

5. בקטע Linking type (סוג הקישור), בוחרים באפשרות OAuth ו-Implicit (מרומז).

   

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

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

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

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

הטמעה של שרת OAuth

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

פרמטרים של נקודת קצה להרשאה
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 הוא המזהה שנמצא בדף Project settings ב-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 לא תקדם את הפעולה באופן פעיל, מה שעלול לצמצם את תנועת המשתמשים של הפעולה.

הערה: צריך להשתמש בכלי ליצירת פעולות כדי ליצור Action (פעולה) שמטמיע קישור חשבונות.

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

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

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