מדריך קונספט של OAuth (Dialogflow)

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

OAuth הוא הפתרון המומלץ לקישור חשבונות, אם מתקיים התנאים הבאים:

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

כדי לוודא ש-OAuth הוא הפתרון שמתאים לכם, עיינו בדף Choose your account link type (בחירת סוג הקישור של החשבון).

מונחי מפתח

לפני שתקראו איך OAuth פועל, כדאי שתכירו את המונחים הבאים:

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

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

  לתהליך הזה נדרשות שתי נקודות קצה:

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

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

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

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

איך זה עובד

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

ניתן לסכם את זרימת קוד ההרשאה באופן הבא:

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

ניתן לסכם את זרימת הקוד המשתמעת באופן הבא:

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

כך מתבצע התהליך של קוד ההרשאה הבסיסי:

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

תהליכי OAuth

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

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

בתהליך שלמעלה, מפעילים את Intent המסייע actions.intent.SIGN_IN כדי להתחיל את תהליך קישור החשבון. Assistant שואלת את המשתמש אם הוא רוצה לקשר את החשבון לשירות שלכם, ומראה לו מסך עם ההרשאות המבוקשות. כשהמשתמש מביע הסכמה, Google מפנה אותו אוטומטית לנקודת הקצה של ההרשאה של השירות בדפדפן. המשתמש נכנס לחשבון (או, בהתאם להגדרות שלכם, יוצר חשבון חדש) ומעניק ל-Action הרשאת גישה לנתונים שלו.

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

שלב 1: המשתמש נכנס באמצעות זרימה מרומזת

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

שלב 2: משתמש נכנס באמצעות זרימת קוד הרשאה

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

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