קישור חשבונות ל-OAuth

הסוג קישור OAuth תומך בשני זרימות רגילות של OAuth 2.0 בתחום – רצף המשתמע וההרשאה.

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

בתהליך הקוד של ההרשאה, נדרשות שתי נקודות קצה:

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

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

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

קוד אימות תהליך משתמע

הטמעה של קישור חשבונות OAuth

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

הגדרת הפרויקט

כך מגדירים את הפרויקט באמצעות קישור OAuth:

1. פותחים את Actions Console ובוחרים את הפרויקט שבו רוצים להשתמש.
2. לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות קישור חשבון.
3. מעבירים את המתג שלצד האפשרות קישור חשבון למצב מופעל.
4. בקטע יצירת חשבון, בוחרים באפשרות לא, אני רוצה לאפשר רק יצירת חשבונות באתר שלי.

5. בקטע סוג קישור, בוחרים באפשרות OAuth וקוד הרשאה.

   

6. בפרטי הלקוח:

   • יש להקצות ערך למזהה לקוח שהונפק על ידי 'פעולות' ל-Google כדי לזהות בקשות שמקורן ב-Google.
   • חשוב לשים לב לערך של Client ID ש-Google מנפיקה לפעולות;
   • מוסיפים את כתובות ה-URL של נקודות הקצה (endpoint) של ההרשאה ושל האסימון.

הערה: אם רוצים שמזהה הלקוח והסוד יישלחו כמחרוזת בקידוד base64, לוחצים על החץ לתפריט הנפתח שליד Configure your client (optional) (מסמנים את הלקוח (אופציונלי) ומסמנים את התיבה Google לשדר מזהה לקוח וסוד דרך כותרת אימות בסיסית של HTTP.

6. לוחצים על שמירה.

הטמעה של שרת OAuth

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

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

בסשן התהליך של קוד האימות OAuth 2.0 ש-Google יזמה:

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

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

   הערה: חובה לציין שהחשבון של המשתמש מקושר ל-Google, ולא למוצר ספציפי של Google, כמו Google Home או Google Assistant.

3. השירות שלכם יוצר קוד הרשאה ומחזיר אותו ל-Google על ידי הפניה חוזרת של דפדפן המשתמש ל-Google עם קוד ההרשאה שמצורף לבקשה.

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

5. אחרי שהמשתמש משלים את תהליך קישור החשבון, כל בקשה שמתקבלת מ-Assistant ל-webhook שלכם למילוי בקשה כוללת אסימון גישה.

טיפול בבקשות הרשאה

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

פרמטרים של נקודות קצה להרשאה
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

   זהו המזהה שנמצא בדף Project settings (הגדרות פרויקט) במסוף הפעולות.YOUR_PROJECT_ID

5. הפניית הדפדפן של המשתמש לכתובת האתר שצוינה בפרמטר redirect_uri. כששולחים לכתובת URL אחרת, צריך לכלול את קוד ההרשאה שנוצר כרגע ואת ערך המצב המקורי שלא השתנה, על ידי הוספת הפרמטרים code ו-state. לפניכם דוגמה לכתובת ה-URL שתתקבל:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

טיפול בבקשות לחילופי אסימונים

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

• החלפת קודי אישור של אסימוני גישה ואסימוני רענון
• אסימוני רענון של Exchange עבור אסימוני גישה

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

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

החלפת קודי אישור של אסימוני גישה ואסימוני רענון

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

עבור הבקשות האלה, הערך של 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

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

1. יש לוודא שהשדה client_id מזהה את מקור הבקשה כמקור מורשה, ושה-client_secret תואם לערך הצפוי.
2. מאמתים את הפרטים הבאים:
   • קוד ההרשאה תקף ולא פג, ומזהה הלקוח שצוין בבקשה תואם למספר הלקוח שמשויך לקוד ההרשאה.
   • כתובת ה-URL שצוינה בפרמטר redirect_uri זהה לערך ששימש בבקשת ההרשאה הראשונית.
3. אם אתם לא מצליחים לאמת את כל הקריטריונים שלמעלה, תוכלו להחזיר שגיאת HTTP 400 Bad Request כשהגוף הוא {"error": "invalid_grant"}.
4. תוכלו להשתמש באסימון ה-User-ID שבקוד ההרשאה, וליצור אסימון רענון ואסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם צריכים לייצג באופן ייחודי את המשתמש ואת הלקוח שעבורם האסימון נמצא, והם לא יכולים להיות ניתנים לניחוש. אסימוני הגישה מתעדים גם את זמן התפוגה של האסימון (בדרך כלל שעה אחרי הנפקת האסימון). לא פג התוקף של אסימוני הרענון.
5. מחזירים את אובייקט ה-JSON הבא בגוף תגובת ה-HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

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

אסימוני רענון של Exchange עבור אסימוני גישה

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

עבור הבקשות האלה, הערך של 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

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

1. ודאו שה-client_id מזהה את מקור הבקשה בתור Google, ושה-client_secret תואם לערך הצפוי.
2. מוודאים שאסימון הרענון תקין ושמספר הלקוח שצוין בבקשה תואם למזהה הלקוח שמשויך לאסימון הרענון.
3. אם אתם לא מצליחים לאמת את כל הקריטריונים שלמעלה, תוכלו להחזיר שגיאת HTTP 400 Bad Request כשהגוף הוא {"error": "invalid_grant"}.
4. אחרת, עליכם להשתמש במזהה המשתמש מאסימון הרענון כדי ליצור אסימון גישה. האסימונים האלה יכולים להיות כל ערך של מחרוזת, אבל הם חייבים לייצג באופן ייחודי את המשתמש ואת הלקוח שעבורם האסימון נמצא, והם לא ניתנים לניחוש. אסימוני הגישה מתעדים גם את זמן התפוגה של האסימון (בדרך כלל שעה אחרי הנפקת האסימון).
5. מחזירים את אובייקט ה-JSON הבא בגוף תגובת ה-HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

הערה: אפשר גם להחזיר refresh_token חדש בתשובה. למידע נוסף על החזרה של refresh_token חדש, קראו את המאמר עבודה עם אסימונים.

תכנון ממשק המשתמש של הקול בתהליך האימות

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

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

בדיקה אם המשתמש מאומת והתחלת תהליך קישור החשבון

1. פותחים את הפרויקט ב-Actions Builder במסוף הפעולות.
2. יוצרים סצנה חדשה כדי להתחיל לקשר חשבון בפעולה:
   1. לוחצים על סגנונות.
   2. לוחצים על סמל ההוספה (+) כדי להוסיף סצנה חדשה.
3. בסצנה החדשה שיצרתם, לחצו על סמל ההוספה עבור תנאים.
4. מוסיפים תנאי שבודק אם המשתמש שמשויך לשיחה הוא משתמש מאומת. אם הבדיקה תיכשל, לא תוכלו לבצע את קישור החשבון בזמן השיחה, ותהיה צורך בגישה לפונקציונליות שלא מחייבת קישור חשבון.
   1. בשדה Enter new expression בקטע Condition, מזינים את הלוגיקה הבאה: user.verificationStatus != "VERIFIED"
   2. בקטע מעבר, בוחרים סצנה שלא מחייבת קישור חשבון או סצנה שהיא נקודת הכניסה לפונקציונליות של אורח בלבד.

1. לוחצים על סמל ההוספה לצד תנאים.
2. מוסיפים תנאי להפעלת תהליך של קישור חשבונות אם למשתמש לא משויכת זהות.
   1. בשדה Enter new expression בקטע Condition, מזינים את הלוגיקה הבאה: user.verificationStatus == "VERIFIED"
   2. בקטע מעבר, בוחרים את סצנת המערכת קישור חשבונות.
   3. לוחצים על שמירה.

אחרי השמירה, תתווסף לסביבת הפרויקט סצנה חדשה של קישור חשבונות בשם <SceneName>_AccountLinking.

התאמה אישית של סצנת קישור החשבונות

1. בקטע תרחישים, בוחרים את סצנת המערכת לקישור חשבונות.
2. לוחצים על Send request ומוסיפים משפט קצר כדי לתאר למשתמש למה הפעולה צריכה לגשת לזהות שלו (לדוגמה, כדי לשמור את ההעדפות שלכם).
3. לוחצים על שמירה.

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

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

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

טיפול בבקשות גישה לנתונים

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