קישור חשבונות באמצעות OAuth וכניסה באמצעות חשבון Google (Dialogflow)

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

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

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

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

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

איור 2. ייצוג חזותי של OAuth ו-Google תהליך הכניסה כאשר פרטי המשתמש לא נמצאו במערכת.

תמיכה ביצירת חשבון באמצעות הקול

אם מאפשרים יצירה של חשבון משתמש באמצעות הקול, Assistant שואלת את המשתמש אם הוא רוצה לבצע את הפעולות הבאות:

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

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

אי אפשר ליצור חשבונות באמצעות פקודות קוליות

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

מומלץ למנוע את האפשרות ליצור אם:

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

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

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

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

הטמעת קישור לחשבון OAuth ולכניסה באמצעות חשבון Google

החשבונות מקושרים לתהליכי OAuth 2.0 המקובלים בתחום. ב-Actions on Google יש תמיכה בתהליכים של קוד ההרשאה המרומז.

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

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 OAuth2 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

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

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

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

5. בקטע Linking type (סוג הקישור), בוחרים באפשרות OAuth & כניסה באמצעות חשבון Google ומרומז.

   

6. ב-Client Information, מבצעים את הפעולות הבאות:

   • מקצים ערך ל-Client-ID שהונפק על ידי הפעולות שלכם ל-Google כדי לזהות בקשות מ-Google.
   • מוסיפים את כתובות ה-URL של נקודות הקצה ב-Authorization וב-Token Exchange.

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

הטמעה של שרת OAuth

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

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

בסשן זרם הענקת גישה משתמע ב-OAuth 2.0 ש-Google יזמה, התהליך הבא:

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

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

כשהפעולה צריכה לבצע קישור חשבונות באמצעות זרם הענקת גישה משתמע ב-OAuth2, Google שולחת את המשתמש לנקודת הקצה (endpoint) של ההרשאה עם בקשה שכוללת את הפרמטרים הבאים:

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

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

1. צריך לאמת את הערכים client_id ו-redirect_uri כדי למנוע הענקת גישה לאפליקציות לקוח לא מכוונות או שהוגדרו באופן שגוי:

   • צריך לוודא שה-client_id תואם למזהה הלקוח שהוקצו ל-Google.
   • מוודאים שכתובת ה-URL שצוינה ב-redirect_uri נראה כך:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID הוא המזהה שמופיע בדף הגדרות הפרויקט של 'מסוף הפעולות'.

2. לבדוק אם המשתמש נכנס לשירות. אם המשתמש לא חתום להשלים את תהליך הכניסה או ההרשמה לשירות.

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

4. לשלוח תגובת 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

ה-handler של Google להפניה אוטומטית ב-OAuth 2.0 יקבל את אסימון הגישה ויאשר שהערך של state לא השתנה. לאחר ש-Google קיבלה אסימון הגישה לשירות שלך, Google תצרף את האסימון לשיחות הבאות לפעולה כחלק מה-AppRequest.

איך מטפלים בקישור האוטומטי

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

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

הבקשה מוצגת בפורמט הבא:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&consent_code=CONSENT_CODE&scope=SCOPES

נקודת הקצה (endpoint) של המרת האסימונים חייבת להיות מסוגלת לטפל בפרמטרים הבאים:

פרמטרים של נקודת קצה של אסימון
grant_type	סוג האסימון המוחלף. בבקשות האלה, מכיל את הערך urn:ietf:params:oauth:grant-type:jwt-bearer.
intent	בבקשות האלה, הערך של הפרמטר הזה הוא 'get'.
assertion	אסימון רשת מבוסס JSON (JWT) שמספק טענת נכוֹנוּת (assertion) חתומה של זהות המשתמש. ה-JWT מכיל מידע שכולל את סמל Google של המשתמש מספר חשבון, שם וכתובת אימייל.
consent_code	אופציונלי: כשהוא קיים, קוד חד-פעמי שמציין המשתמש נתן את הסכמתו לפעולה כדי לגשת להיקפי ההרשאות שצוינו.
scope	אופציונלי: היקפי הרשאות שהגדרתם ש-Google תבקש ממשתמשים.

כשנקודת הקצה של המרת אסימונים מקבלת את בקשת הקישור, היא צריכה לבצע את הבאים:

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys (available in JWK or PEM format) to verify the token's signature.

Note: The keys should not be hardcoded. Instead, follow OpenID connect discovery protocol and check the cache-control header to decide how long the key should be cached.

When decoded, the JWT assertion looks like the following example:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com and that the audience (aud field) is the client ID assigned to your Action.

בודקים אם חשבון Google כבר קיים במערכת האימות

בודקים אם אחד מהתנאים הבאים מתקיים:

• מספר חשבון Google, שמופיע בשדה sub של טענת הנכוֹנוּת (assertion), קיים במסד הנתונים של המשתמשים.
• כתובת האימייל בטענת הנכונות (assertion) תואמת למשתמש במסד הנתונים של המשתמשים.

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

אם מספר חשבון Google או כתובת האימייל לא צוינו בטענת הנכונות (assertion) תואם למשתמש במסד הנתונים שלכם, המשתמש עדיין לא נרשם. במקרה הזה, נקודת הקצה (endpoint) של המרת אסימון צריכה להשיב עם שגיאת HTTP 401 שמציינת error=user_not_found, כמו בדוגמה הבאה:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"user_not_found",
}

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

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

כשמשתמש צריך ליצור חשבון בשירות שלך, Google יוצרת בקשה לנקודת הקצה של המרת האסימון שמציינת intent=create, כמו בדוגמה הבאה:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]

הפרמטר assertion מכיל אסימון רשת מבוסס JSON (JWT) שמספק טענת נכוֹנוּת (assertion) חתומה על זהות המשתמש ב-Google. ה-JWT מכיל מידע שכוללות את מספר חשבון Google, השם וכתובת האימייל של המשתמש, שבהם אפשר להשתמש כדי ליצור חשבון חדש בשירות.

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

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys (available in JWK or PEM format) to verify the token's signature.

Note: The keys should not be hardcoded. Instead, follow OpenID connect discovery protocol and check the cache-control header to decide how long the key should be cached.

When decoded, the JWT assertion looks like the following example:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com and that the audience (aud field) is the client ID assigned to your Action.

אימות פרטי המשתמש ויצירת חשבון חדש

בודקים אם אחד מהתנאים הבאים מתקיים:

• מספר חשבון Google, שמופיע בשדה sub של טענת הנכוֹנוּת (assertion), קיים במסד הנתונים של המשתמשים.
• כתובת האימייל בטענת הנכונות (assertion) תואמת למשתמש במסד הנתונים של המשתמשים.

אם אחד מהתנאים מתקיים, מבקשים מהמשתמש לקשר את החשבון הקיים עם לחשבון Google שלהם, על ידי שליחת תגובה לבקשה עם שגיאת HTTP 401, וציון error=linking_error וכתובת האימייל של המשתמש כ-login_hint, כמו ב- בדוגמה הבאה:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

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

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

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

התחלת תהליך האימות

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

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

להשתמש בכוונת העזר לכניסה לחשבון כדי להתחיל את תהליך האימות.

Dialogflow (Node.js)

const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
})

// Intent that starts the account linking flow.
app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Dialogflow (Java)

private String clientId = "<your_client_id>";

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

Actions SDK (Node.js)

const app = actionssdk({
  clientId: CLIENT_ID,
})

app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Actions SDK (Java)

private String clientId = "<your_client_id>";

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

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

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