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

כשהפעולה צריכה לבצע קריאה לאחד מממשקי ה-API של השירות, Google משתמשת בנקודות הקצה האלה יחד כדי לקבל הרשאה מהמשתמשים לקרוא לממשקי ה-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 שולחת את המשתמש לנקודת הקצה של ההרשאה שלכם עם בקשה שכוללת את הפרמטרים הבאים:

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

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

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

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

נקודת הקצה של המרת האסימונים של השירות שלכם אחראית לשני סוגים של החלפת אסימונים:

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

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

פרמטרים של נקודת קצה ל-Token Exchange
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 קיבלה מנקודת הקצה של המרת האסימונים.
החלפת קודי הרשאה באסימוני גישה ובאסימוני רענון

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

בבקשות האלה, הערך 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

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

  1. יש לוודא ש-client_id מזהה את מקור הבקשה כמקור מורשה, וש-client_secret תואם לערך הצפוי.
  2. מאמתים את הפרטים הבאים:
    • קוד ההרשאה בתוקף ותקף, ומזהה הלקוח שצוין בבקשה תואם למזהה הלקוח שמשויך לקוד ההרשאה.
    • כתובת ה-URL שצוינה בפרמטר redirect_uri זהה לערך שנעשה בו שימוש בבקשת ההרשאה הראשונית.
  3. אם לא מצליחים לאמת את כל הקריטריונים שצוינו, צריך להחזיר שגיאת HTTP 400 Bad Request עם הקוד {"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 שולחת בקשה לנקודת הקצה של המרת האסימונים כדי להחליף אסימון רענון באסימון גישה חדש.

בבקשות האלה, הערך 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 Bad Request עם הקוד {"error": "invalid_grant"} כגוף.
  4. אחרת, משתמשים ב-User-ID מאסימון הרענון כדי ליצור אסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם צריכים לייצג באופן ייחודי את המשתמש ואת הלקוח שעבורם משויך האסימון, ולא ניתן לנחש אותם. לגבי אסימוני גישה, מתעדים גם את זמן התפוגה של האסימון (בדרך כלל שעה אחרי הנפקת האסימון).
  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 מכילה אסימון גישה, קודם צריך לוודא שאסימון הגישה תקין (ותוקפו לא פג) ואז לאחזר ממסד הנתונים את חשבון המשתמש המשויך.