הסוג של קישור OAuth תומך בשני זרימות OAuth 2.0 המקובלות בתחום, התהליכים המשתמעים וההרשאות.
בתהליך הקוד המשתמע, Google פותחת את נקודת הקצה של ההרשאות בדפדפן של המשתמש. לאחר שנכנסתם לחשבון בהצלחה, תחזירו ל-Google אסימון גישה לטווח ארוך. אסימון הגישה הזה נכלל עכשיו בכל בקשה שנשלחת מ-Assistant לפעולה.
בתהליך קוד ההרשאה צריכות להיות שתי נקודות קצה:
- נקודת הקצה ההרשאה, שאחראית להצגת ממשק המשתמש של הכניסה למשתמשים, שעדיין לא נכנסו לחשבון, ולתעד הסכמה לגישה המבוקשת בצורה של קוד הרשאה לטווח קצר.
- נקודת הקצה החלפה באסימונים שאחראית לשני סוגים של החלפות:
- ממירה קוד הרשאה לאסימון רענון לטווח ארוך ולאסימון גישה לטווח קצר. ההחלפה הזו מתרחשת כשהמשתמש מסיים את התהליך של קישור החשבונות.
- העברה של אסימון רענון לטווח ארוך לאסימון גישה לטווח קצר. ההחלפה הזו מתרחשת כש-Google צריכה אסימון גישה חדש כי פג תוקפו של האסימון שפג תוקפו.
אמנם קל יותר להטמיע את תהליך הקוד המשתמע, אבל Google ממליצה שאף אחד מהאסימונים לגישה שיונפקו באמצעות התהליך המשתמע לא יפוג לעולם, כי שימוש בתפוגת אסימון עם הזרימה המשתמעת מאלץ את המשתמש לקשר שוב את החשבון שלו. אם אתם זקוקים לתפוגת אסימון עבור מטעמי אבטחה, כדאי לכם לשקול להשתמש בתהליך אימות הקוד במקום זאת.
הטמעה של קישור לחשבון OAuth
הגדרת הפרויקט
כדי להגדיר את הפרויקט לשימוש בקישור OAuth, מבצעים את הפעולות הבאות:
- פותחים את Actions Console ובוחרים את הפרויקט שבו רוצים להשתמש.
- לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות קישור חשבונות.
- מפעילים את המתג שלצד האפשרות קישור חשבון.
- בקטע יצירת חשבון, בוחרים באפשרות לא, אני רוצה לאפשר את יצירת החשבון רק באתר שלי.
בקטעים סוג קישור, בוחרים באפשרות OAuth ומרומז.
בקטע פרטי הלקוח:
- מקצים ערך ל-Client ID שמונפק על ידי Google Actions כדי לזהות בקשות מ-Google.
- יש להזין את כתובות ה-URL של נקודות הקצה של Authorization ו- Token Exchange.
- לוחצים על שמירה.
הטמעה של שרת ה-OAuth
כדי לתמוך בתהליך המשתמע של OAuth 2.0, השירות שלכם מאפשר נקודת קצה להרשאה ב-HTTPS. נקודת הקצה הזו אחראית לאימות של משתמשים ולקבלת גישה אליהם. נקודת הקצה להרשאה מציגה למשתמשים ממשק משתמש שעדיין לא נכנסו לחשבון, והיא מתעדת את בקשת הגישה.
כשהפעולה שלכם צריכה לבצע קריאה לאחד מממשקי ה-API המורשים של השירות, Google משתמשת בנקודת הקצה הזו כדי לקבל מהמשתמשים הרשאה לקרוא לממשקי ה-API האלה בעצמם.
זהו תהליך גמיש משתמע של OAuth 2.0 ש-Google מפעילה, בתהליך הזה:
- Google פותחת את נקודת הקצה של ההרשאות בדפדפן של המשתמש. המשתמש נכנס לחשבון אם לא נכנס עדיין, ומעניק ל-Google הרשאה לגשת לנתונים באמצעות ה-API אם הוא לא נתן עדיין הרשאה.
- השירות שלכם יוצר אסימון גישה ומחזיר אותו ל-Google על ידי הפניה אוטומטית של דפדפן המשתמש חזרה ל-Google עם אסימון הגישה המצורף לבקשה.
- Google קוראת לממשקי ה-API של השירות, ומצרפת את אסימון הגישה לכל בקשה. השירות מאמת שאסימון הגישה מעניק ל-Google הרשאה לגשת ל-API, ולאחר מכן משלים את קריאת ה-API.
טיפול בבקשות הרשאה
כשהפעולה צריכה לבצע קישור חשבונות באמצעות תהליך משתמע של OAuth 2.0, Google שולחת את המשתמש לנקודת הקצה להרשאה עם בקשה שכוללת את הפרמטרים הבאים:
פרמטרים של נקודות קצה להרשאה | |
---|---|
client_id |
מספר הלקוח שהקצית ל-Google. |
redirect_uri |
כתובת ה-URL שאליה נשלחת התגובה לבקשה הזו. |
state |
ערך של הנהלת דומיין שמועבר חזרה ל-Google ללא שינוי ב-URI של ההפניה האוטומטית. |
response_type |
סוג הערך שיש להחזיר בתגובה. בתהליך המשתמע של OAuth 2.0, סוג התגובה הוא תמיד token . |
לדוגמה, אם נקודת הקצה להרשאה זמינה ב-https://myservice.example.com/auth
, הבקשה עשויה להיראות כך:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token
כדי שנקודת הקצה להרשאה תטפל בבקשות לכניסה, יש לבצע את השלבים הבאים:
מאמתים את הערכים
client_id
ו-redirect_uri
כדי למנוע הענקת גישה לאפליקציות של לקוחות שלא הוגדרו או שיש להן הגדרה שגויה:- ודאו שהמספר
client_id
תואם למספר הלקוח שהוקצה ל-Google. - מוודאים שכתובת ה-URL שצוינה בפרמטר
redirect_uri
כוללת את הטופס הבא:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID הוא המזהה שנמצא בדף הגדרות הפרויקט ב-Actions Console.
- ודאו שהמספר
בודקים אם המשתמש מחובר לשירות שלכם. אם המשתמש לא מחובר לחשבון, עליך להשלים את תהליך הכניסה או ההרשמה לשירות.
יצירת אסימון גישה שישמש את Google לגישה אל ה-API שלך. אסימון הגישה יכול להיות כל ערך של מחרוזת, אבל הוא צריך לייצג באופן ייחודי את המשתמש ואת הלקוח שעבורו אסימון זה חייב להיות, ולא ניתן לנחש אותו.
יש לשלוח תגובת HTTP שמפנה את דפדפן המשתמש לכתובת ה-URL שצוינה בפרמטר
redirect_uri
. בכל קטע URL יש לכלול את כל הפרמטרים הבאים:access_token
: אסימון הגישה שיצרת עכשיוtoken_type
: המחרוזתbearer
state
: ערך המצב שלא השתנה מהבקשה המקורית הדוגמה בדוגמה לכתובת URL שהתקבלה:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
הגורם המפנה ב-OAuth 2.0 של Google יקבל את אסימון הגישה ויאשר שהערך של state
לא השתנה. אחרי ש-Google תקבל אסימון גישה לשירות שלכם, Google תצמיד את האסימון לקריאות הבאות לפעולה כחלק מ-AppRequest.
תכנון ממשק המשתמש של הקול לתהליך האימות
בודקים אם המשתמש מאומת ומתחילים בתהליך קישור החשבונות
- פותחים את פרויקט Actions Builder בקונסולה ל-Actions.
- יוצרים סצנה חדשה כדי להתחיל בקישור החשבונות בפעולה:
- לוחצים על תרחישים.
- לוחצים על סמל ההוספה (+) כדי להוסיף סצנה חדשה.
- בסצנה החדשה שנוצרה, לחצו על סמל ההוספה add עבור תנאים.
- הוסיפו תנאי שיבדוק אם המשתמש שמשויך לשיחה הוא משתמש מאומת. אם הבדיקה נכשלה, לא ניתן לבצע את קישור החשבון במהלך השיחה, ויש לחזור אליה כדי לקבל גישה לפעולות שלא דורשות קישור לחשבון.
- בשדה
Enter new expression
בקטע תנאי, מזינים את הלוגיקה הבאה:user.verificationStatus != "VERIFIED"
- בקטע מעבר, בוחרים סצנה שלא מצריכה קישור לחשבון או סצינה שהיא נקודת הכניסה לפונקציונליות של אורחים בלבד.
- בשדה
- לוחצים על סמל ההוספה add לצד תנאים.
- הוסיפו תנאי להפעלת תהליך קישור חשבונות, אם אין למשתמש זהות משויכת.
- בשדה
Enter new expression
בקטע תנאי, מזינים את הלוגיקה הבאה:user.verificationStatus == "VERIFIED"
- בקטע מעבר, בוחרים בסצינת המערכת קישור חשבונות.
- לוחצים על שמירה.
- בשדה
בסיום השמירה, תתווסף לפרויקט שלכם סצינת מערכת חדשה לקישור חשבונות בשם <SceneName>_AccountLinking
.
התאמה אישית של סצנת קישור החשבונות
- בקטע תרחישים, בוחרים בסצינת המערכת לקישור חשבונות.
- לוחצים על שליחת בקשה ומוסיפים משפט קצר כדי לתאר למשתמש למה הפעולה צריכה לגשת לזהות שלו (לדוגמה, כדי "לשמור את ההעדפות שלכם").
- לוחצים על שמירה.
- בקטע תנאים, לוחצים על אם המשתמש ישלים בהצלחה את קישור החשבון.
- צריך להגדיר את המשך התהליך אם המשתמש מסכים לקשר את החשבון שלו. לדוגמה, אפשר לקרוא ל-webhook כדי לעבד את הלוגיקה העסקית המותאמת אישית ולחזור לסביבת המקור.
- לוחצים על שמירה.
- בקטע תנאים, לוחצים על אם המשתמש מבטל או מבטל את הקישור לחשבון.
- ניתן להגדיר את המשך התהליך אם המשתמש לא מסכים לקשר את החשבון שלו. לדוגמה, ניסוח של הודעת אישור והפניה אוטומטית לסצנות שלא מצריכות קישור לחשבון.
- לוחצים על שמירה.
- בקטע תנאים, לוחצים על אם מתרחשת שגיאת מערכת או רשת.
- תוכלו להגדיר את המשך התהליך אם לא ניתן להשלים את תהליך קישור החשבון עקב שגיאות ברשת או ברשת. לדוגמה, ניסוח של הודעת אישור והפניה אוטומטית לסצנות שלא מצריכות קישור לחשבון.
- לוחצים על שמירה.
טיפול בבקשות גישה לנתונים
אם הבקשה ל-Assistant מכילה אסימון גישה, קודם צריך לבדוק שאסימון הגישה תקין (ולא פג תוקף) ואז לאחזר את חשבון המשתמש המשויך ממסד הנתונים שלכם.