מדריך קונספט לשימוש ב-OAuth ובכניסה באמצעות חשבון Google (Dialogflow)

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

השימוש ב-OAuth ובכניסה באמצעות חשבון Google הוא הפתרון המומלץ לקישור חשבונות, במקרים הבאים:

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

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

מונחי מפתח

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

  • אסימון של מזהה Google: טענת נכוֹנוּת (assertion) חתומה של זהות המשתמש שמכילה את הפרטים הבסיסיים של פרופיל Google של המשתמש (השם, כתובת האימייל ותמונת הפרופיל שלו). אסימון של מזהה Google הוא אסימון אינטרנט מסוג JSON (JWT). דוגמה לאסימון מפוענח:
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}
  • כוונת משתמש מסוג כניסה לחשבון: כוונה של גורם מסייע שקוראת לו לבקש תהליך קישור של חשבון מ-Assistant. למידע נוסף, ראו כניסה לחשבון.
    • Context string: מחרוזת מותאמת אישית שמוסיפים לכוונת המשתמש בכניסה לחשבון, שמציינת למשתמש למה אתם רוצים לקשר את החשבון שלו.
  • תהליך קוד ההרשאה: תהליך OAuth 2.0 שאפשר להטמיע באמצעות כניסה באמצעות חשבון OAuth + Google. לתהליך הזה נדרשות שתי נקודות קצה:
    • נקודת הקצה להרשאה: נקודת הקצה שמציגה את ממשק המשתמש לכניסה למשתמשים שעדיין לא מחוברים לחשבון. מתעדת ההסכמה לגישה המבוקשת בצורה של קוד הרשאה לטווח קצר.
    • נקודת הקצה של המרת אסימונים: נקודת הקצה הזו אחראית לשני סוגים של המרות:
      1. ממיר קוד הרשאה באסימון רענון לטווח ארוך ובאסימון גישה לטווח קצר. תהליך ההחלפה הזה מתרחש כשהמשתמש עובר את תהליך קישור החשבון.
      2. ממיר אסימון רענון לטווח ארוך באסימון גישה לטווח קצר. ההחלפה מתבצעת כש-Google צריכה אסימון גישה חדש כי פג תוקפו.
  • זרם קוד משתמע: תהליך OAuth 2.0 שאפשר להטמיע באמצעות כניסה באמצעות OAuth + Google. לתהליך הזה נדרשת רק נקודת קצה להרשאה. בתהליך הזה, Google פותחת את נקודת הקצה להרשאה בדפדפן של המשתמש. אם הכניסה תתבצע בהצלחה, תקבלו ל-Google אסימון גישה לטווח ארוך. אסימון הגישה נכלל עכשיו בכל בקשה שנשלחת מ-Assistant לפעולה שלכם.
  • אסימון גישה: אסימון שמאפשר לשירות שלכם לגשת לחלקים מנתוני המשתמש. אסימוני הגישה משויכים לכל משתמש בנפרד.
  • אסימון רענון: אסימון שמוחלף באסימון גישה חדש אחרי שפג התוקף של אסימון גישה לטווח קצר.

דרישות מוקדמות

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

  • שרת OAuth 2

  • נקודת קצה להמרת אסימונים

    צריך להרחיב את נקודת הקצה של המרת האסימון כדי להוסיף תמיכה בפרוטוקולים של Google לקישור אוטומטי וליצירת חשבון מאסימון מזהה (כלומר, יש להוסיף את הפרמטרים intent=get ו-intent=create בבקשות לנקודת הקצה הזו).

איך זה עובד

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

התהליך הבסיסי הוא:

  1. במסגרת הפעולה, המשתמש מבקש את הסכמתו לגשת לפרופיל Google שלו.
  2. אחרי שהמשתמש מביע הסכמה, הפעולה מקבלת אסימון מזהה של Google שמכיל את פרטי פרופיל Google שלו.
  3. צריך לאמת ולפענח את האסימון כדי לקרוא את תוכן הפרופיל.
  4. בפעולה נעשה שימוש באסימון הזה כדי לבדוק אם פרטי הפרופיל ב-Google קיימים במערכת שלכם.
    1. אם כן, המשתמש כבר נכנס למערכת עם חשבון Google שלו, ו-Assistant תקשר את זהות המשתמש לחשבון Google שלו. המשתמש יכול להמשיך את השיחה עם Assistant דרך החשבון שלו.
    2. אם היא לא מופיעה, עוברים לשלב 5.
  5. המשתמש יכול א) ליצור חשבון חדש עם פרטי פרופיל Google שלו, או ב) להיכנס למערכת שלכם באמצעות חשבון אחר. האפשרויות שמוצגות למשתמש משתנות בהתאם להפעלה או להשבתה של יצירת החשבון באמצעות הקול. אם המשתמש בוחר להיכנס למערכת עם חשבון אחר, מתחיל תהליך ה-OAuth הרגיל.
  6. אחרי שהמשתמש יוצר חשבון חדש או נכנס דרך ספק אחר, השירות מחזיר ל-Google אסימון גישה. (אם אתם משתמשים בתהליך קוד ההרשאה, השירות גם מחזיר אסימון רענון).
  7. עכשיו המשתמש יכול להמשיך את השיחה עם Assistant דרך החשבון שלו.

תהליכי OAuth ו-GSI

בקטע הזה נתאר את התהליכים השונים שיכולים להתרחש עם OAuth ו-GSI. התרשימים האלה מפרטים את התהליכים שמתרחשים בתהליך קוד ההרשאה ולא בתהליך הקוד המשתמע, מתוך הנחה שאתם משתמשים ב-Dialogflow כפתרון להבנת שפה טבעית (NLP) בפעולה שלכם.

כל תהליך כולל את השלבים הנפוצים הבאים אחרי שהמשתמש מפעיל את הפעולה:

בתהליך שלמעלה, מפעילים את ה-Intent המסייע actions.intent.SIGN_IN באמצעות מחרוזת הקשר בהתאמה אישית. כוונה כזו מבקשת מהמשתמש הרשאת גישה לפרטי פרופיל Google שלו. אחרי שהמשתמש מביע הסכמה, Assistant שולחת בקשה שמכילה את פרטי הפרופיל של user@gmail.com.

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

זרימות עם יצירת חשבון קולי מופעלת

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

שלב 1: פרטי המשתמש קיימים במערכת שלך

במקרה הזה, המשתמש שמיוצג על ידי user@gmail.com קיים בקצה העורפי, כך שנקודת הקצה של המרת האסימונים מחזירה אסימון עבור המשתמש. זהות המשתמש בפעולה מקושרת עכשיו לחשבון Google שלו. הבקשה המקורית של המשתמש ("Order my דואר") תואמת ל-Intent המותאם אישית order_drink. לאחר מכן, התגובה לפעולה מאתר אחר (webhook) תטפל במילוי ההזמנה של כוונת המשתמש ותשלח שאילתות אל מסד הנתונים שלך כדי לבדוק את ההזמנה הרגילה של user@gmail.com. לאחר מכן המשתמש יוכל להמשיך בשיחה עם Assistant.

שלב 2: פרטי המשתמש לא קיימים והמשתמש יוצר חשבון

מאחר שהפעלתם יצירת חשבון באמצעות הקול ו-user@gmail.com לא קיים בקצה העורפי שלכם, Assistant שואלת את המשתמשים אם הם רוצים לבצע אחת מהפעולות הבאות:

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

ב) היכנסו למערכת באמצעות חשבון אחר

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

אחרי שיוצרים את החשבון, השירות מחזיר אסימון גישה ואסימון רענון לחשבון החדש שנוצר. זהות המשתמש בפעולה מקושרת עכשיו לחשבון Google שלו. הבקשה המקורית של המשתמש ("Order myנמנע") תואמת ל-Intent המותאם אישית order_drink.. לאחר מכן, התגובה לפעולה מאתר אחר (webhook) תטפל במילוי הבקשה שנמצאה לה התאמה ותשלח שאילתות במסד הנתונים על ההזמנה הרגילה של user@gmail.com, שעדיין לא קיימת כי המשתמש חדש. הפעולה יכולה לשאול את המשתמש מה הוא רוצה להזמין.

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

הפעלתם את יצירת החשבון באמצעות הקול, לכן Assistant שואלת את המשתמשים אם לבצע את אחת מהפעולות הבאות:

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

ב) היכנסו למערכת באמצעות חשבון אחר

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

אחרי האימות של פרטי הכניסה של המשתמש, השירות מחזיר ל-Google אסימון גישה ואסימון רענון. זהות המשתמש בפעולה מקושרת עכשיו לחשבון שאינו של Google. הבקשה המקורית של המשתמש ("Order my דואר") תואמת ל-Intent המותאם אישית order_drink.. לאחר מכן, התגובה לפעולה מאתר אחר (webhook) תטופל בתגובה לכוונה התואמת ותשלח שאילתות במסד הנתונים על ההזמנה הרגילה של user@gmail.com, שעדיין לא קיימת כי המשתמש חדש. הפעולה יכולה לשאול את המשתמשים מה הם רוצים להזמין או להגדיר את ההזמנה הרגילה.

תהליך היצירה של חשבון קולי מושבת

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

שלב 4: פרטי המשתמש לא קיימים

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

אחרי האימות של פרטי הכניסה של המשתמש, השירות מחזיר ל-Google אסימון גישה ואסימון רענון. זהות המשתמש בפעולה מקושרת עכשיו לחשבון שאינו של Google. הבקשה המקורית של המשתמש ("Order my דואר") תואמת ל-Intent המותאם אישית order_drink.. לאחר מכן, התגובה לפעולה מאתר אחר (webhook) תטופל בתגובה לכוונה התואמת ותשלח שאילתות במסד הנתונים על ההזמנה הרגילה של user@gmail.com, שעדיין לא קיימת כי המשתמש חדש. הפעולה יכולה לבקש מהמשתמש להגדיר את הסדר הרגיל שלו.