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

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

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

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

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

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

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

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

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

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

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

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

    • יש להקצות ערך למזהה לקוח שהונפק על ידי 'פעולות' ל-Google כדי לזהות בקשות שמקורן ב-Google.
    • מוסיפים את כתובות ה-URL של נקודות הקצה (endpoint) של ההרשאה ושל האסימון.
  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 במסוף הפעולות.
  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 מכילה אסימון גישה, קודם צריך לבדוק שאסימון הגישה חוקי (ולא פג תוקף), ואז לאחזר את חשבון המשתמש המשויך ממסד הנתונים שלכם.