קישור חשבונות באמצעות OAuth

הסוג קישור OAuth תומך בשני תהליכי OAuth 2.0 מקובלים בתחום, התהליכים המשתמעת וההרשאה.

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

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

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

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

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

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

כדי להגדיר בפרויקט שימוש בקישור OAuth, פועלים לפי השלבים הבאים:

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

  5. בקטע Linking type (סוג הקישור), בוחרים באפשרות OAuth ו-Implicit (מרומז).

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

    • כדי לזהות בקשות שמגיעות מ-Google, מקצים ערך ל-Client-ID שהונפק על ידי Actions to Google.
    • עליך להזין את כתובות ה-URL של נקודות הקצה Authorization ו-Token Exchange.
  1. לוחצים על שמירה.

הטמעה של שרת OAuth

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authenticating and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When your Action needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

  1. Google opens your authorization endpoint in the user's browser. The user signs in if not signed in already, and grants Google permission to access their data with your API if they haven't already granted permission.
  2. Your service creates an access token and returns it to Google by redirecting the user's browser back to Google with the access token attached to the request.
  3. Google calls your service's APIs, and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When your Action needs to perform account linking via an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id The client ID you assigned to Google.
redirect_uri The URL to which you send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

For your authorization endpoint to handle sign-in requests, do the following steps:

  1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

    • Confirm that the client_id matches the client ID you assigned to Google.
    • Confirm that the URL specified by the redirect_uri parameter has the following form: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      YOUR_PROJECT_ID is the ID found on the Project settings page of the Actions Console.

  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

  3. Generate an access token that Google will use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

  4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

    • access_token: the access token you just generated
    • token_type: the string bearer
    • state: the unmodified state value from the original request The following is an example of the resulting URL: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler will receive the access token and confirm that the state value hasn't changed. After Google has obtained an access token for your service, Google will attach the token to subsequent calls to your Action as part of the AppRequest.

עיצוב ממשק המשתמש הקולי לתהליך האימות

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

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

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

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

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

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

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

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

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

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

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