מדריך רעיון לקישור OAuth

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

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

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

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

מונחי מפתח

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

• user.verificationStatus: מאפיין שהמערכת הגדירה כדי לציין אם בסשן הנוכחי יש משתמש מאומת.

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

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

• תהליך קוד ההרשאה: במהלך התהליך של 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.

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

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

הערה: שורה מ-Webhook ל-User מייצגת תגובה פשוטה שאתם יוצרים ומתאימים אישית. הקווים שנלקחים מ-Assistant ל-User מייצגים הנחיות שנמצאות בבעלות של Assistant, ושיש בהן אפשרויות מוגבלות להתאמה אישית (בקשות שנדרשת להן הרשאה תמיד נמצאות בבעלות של Assistant). מנקודת המבט של המשתמשים, שני סוגי התשובות נשלחים מ-Assistant.

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

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

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

הערה: התרשים הזה מבוסס על תרשים השלבים הנפוצים שלמעלה.

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

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

הערה: התרשים הזה מבוסס על תרשים השלבים הנפוצים שלמעלה.

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

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