הטמעה של שרת OAuth 2.0

כל שילוב של Cloud-to-cloud חייב לכלול מנגנון לאימות משתמשים.

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

בדף הזה מוסבר איך להגדיר את שרת OAuth 2.0 כך שיפעל עם השילוב של Cloud-to-cloud.

קישור של חשבון Google באמצעות OAuth

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

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

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

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

הנחיות עיצוב

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

דרישות

1. אתם צריכים להבהיר למשתמש שהחשבון שלו יקושר ל-Google, ולא למוצר ספציפי של Google כמו Google Home או Google Assistant.
2. צריך להציג הצהרת הרשאה של Google, כמו "הכניסה לחשבון מאשרת ל-Google לשלוט במכשירים שלך". אפשר לעיין בקטע הרשאת שליטה במכשיר Google במדיניות למפתחים של Google Home.
3. צריך לפתוח את דף הקישור של OAuth באינטרנט ולוודא שלמשתמשים יש שיטה ברורה להתחברות לחשבון Google שלהם, כמו שדות לשם המשתמש ולסיסמה. אל תשתמשו בשיטת הכניסה באמצעות חשבון Google ‏ (GSI) שמאפשרת למשתמשים לקשר חשבונות בלי שהם מועברים לדף קישור חשבונות באמצעות OAuth באינטרנט. זו הפרה של מדיניות Google.
4. כדי לציין את השילוב שאליו המשתמש מקשר את החשבון, צריך לכלול לפחות אחד מהפריטים הבאים בדף הקישור של OAuth:
   • לוגו של החברה
   • שם החברה
   • שם השילוב
   • סמל האפליקציה

המלצות

מה אתם יכולים לעשות?

1. הצגת מדיניות הפרטיות של Google במסך ההסכמה, צריך לכלול קישור למדיניות הפרטיות של Google.

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

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

4. אפשרות ביטול. אפשר לספק למשתמשים אפשרות לחזור אחורה או לבטל את הקישור, אם הם לא רוצים לקשר את החשבון.

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

6. אפשרות לבטל את הקישור. מציעים למשתמשים מנגנון לביטול הקישור, כמו כתובת URL להגדרות החשבון שלהם בפלטפורמה שלכם. אפשרות אחרת היא לכלול קישור לחשבון Google שבו המשתמשים יכולים לנהל את החשבון המקושר שלהם. אם משתמש מבטל את הקישור לשילוב שלכם, צריך להשתמש ב-agentUsers.delete כדי להודיע ל-Google על השינוי.

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

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

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

הרשאה באמצעות קוד

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

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

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

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

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

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

לדוגמה, אם נקודת הקצה להרשאה זמינה בכתובת 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, ושהערך של 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
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

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

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

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

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

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

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

הגדרת האופן שבו Google שולחת פרטי כניסה לשרת שלכם

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

כברירת מחדל, Google שולחת את פרטי הכניסה בגוף הבקשה. אם שרת ההרשאות דורש שפרטי הכניסה של הלקוח יהיו בכותרת הבקשה, צריך להגדיר את השילוב של Cloud-to-cloud בהתאם:

נכנסים ל-Play Console

1. ברשימת הפרויקטים, לוחצים על Open ליד הפרויקט שרוצים לעבוד איתו.

2. בקטע Cloud-to-Cloud, בוחרים באפשרות Develop.

3. לוחצים על פתיחה לצד השילוב.

4. גוללים למטה לקטע Permissions (optional) ובוחרים את תיבת הסימון Have Google transmit Client ID and secret via HTTP basic auth header.

5. לוחצים על שמירה כדי לשמור את השינויים.

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

אחרי שהמשתמש נכנס לחשבון ונקודת הקצה לאימות מחזירה ל-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. מוודאים שקוד ההרשאה תקין ובתוקף, ושמזהה הלקוח שצוין בבקשה תואם למזהה הלקוח שמשויך לקוד ההרשאה.
3. מוודאים שכתובת ה-URL שצוינה בפרמטר redirect_uri זהה לערך שנעשה בו שימוש בבקשת ההרשאה הראשונית.
4. אם אי אפשר לאמת את כל הקריטריונים שלמעלה, צריך להחזיר שגיאת HTTP‏ 400 Bad Request עם {"error": "invalid_grant"} כגוף.
5. אחרת, משתמשים במזהה המשתמש מקוד ההרשאה כדי ליצור טוקן רענון וטוקן גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם חייבים לייצג באופן ייחודי את המשתמש ואת הלקוח שהאסימון מיועד לו, ואי אפשר לנחש אותם. בטוקני גישה, צריך לתעד גם את זמן התפוגה של הטוקן, שבדרך כלל חל שעה אחרי הנפקת הטוקן. התוקף של טוקני רענון לא פג.
6. מחזירים את אובייקט ה-JSON הבא בגוף של תגובת ה-HTTPS:

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

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

החלפת טוקני רענון בטוקני גישה

כשתוקף אסימון הגישה פג, 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

כדי להחליף טוקן רענון בטוקן גישה, נקודת הקצה להחלפת טוקנים מגיבה לבקשות 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
   }

טיפול בבקשות למידע על משתמשים

נקודת הקצה של userinfo היא משאב מוגן ב-OAuth 2.0 שמחזיר תלונות לגבי המשתמש המקושר. ההטמעה והאירוח של נקודת הקצה של userinfo הם אופציונליים, חוץ מאשר בתרחישים הבאים לדוגמה:

• כניסה לחשבון המקושר באמצעות Google One Tap.
• מינוי פשוט וקל ב-AndroidTV.

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

לדוגמה, אם נקודת הקצה של Userinfo זמינה https://myservice.example.com/userinfo, בקשה עשויה להיראות כך:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

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

1. מחלצים את אסימון הגישה מהכותרת Authorization ומחזירים מידע עבור המשתמש שמשויך לאסימון הגישה.
2. אם אסימון הגישה לא חוקי, צריך להחזיר שגיאה מסוג HTTP 401 מאושר עם שימוש בכותרת התגובה WWW-Authenticate. דוגמה לתגובה עם שגיאה של userinfo:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

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

3. אם אסימון הגישה תקין, מוחזר ותגובת HTTP 200 עם אובייקט ה-JSON הבא בגוף ה-HTTPS תגובה:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

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

   תגובה של נקודת הקצה של userinfo
   sub	מזהה ייחודי שמזהה את המשתמש במערכת שלכם.
   email	כתובת האימייל של המשתמש.
   given_name	אופציונלי: השם הפרטי של המשתמש.
   family_name	אופציונלי: שם המשפחה של המשתמש.
   name	אופציונלי: השם המלא של המשתמש.
   picture	אופציונלי: תמונת פרופיל של המשתמש.