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

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

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth 2.0 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

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

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

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

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

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

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

   

6. בקטע Client Information:

   • מקצים ערך למזהה הלקוח שהונפק על ידי Actions on Google כדי לזהות בקשות שמגיעות מ-Google.
   • מזינים את כתובות ה-URL של נקודות הקצה של ההרשאה ושל החלפת הטוקנים.

הערה: אם רוצים שמזהה הלקוח יישלח כמחרוזת עם קידוד base64, לוחצים על החץ לתפריט הנפתח לצד הגדרת הלקוח (אופציונלי) ומסמנים את התיבה Google to transmit clientID and secret via HTTP basic auth header (שליחת מזהה הלקוח והסוד מ-Google באמצעות כותרת אימות בסיסי של HTTP).

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

הטמעת שרת 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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