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

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

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

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

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

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

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

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

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

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

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

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

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

הטמעה של שרת OAuth

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

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

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

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

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

  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
}

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

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

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