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

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

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

  • The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
  • The token exchange endpoint, which is responsible for two types of exchanges:
    1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
    2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

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