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

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

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

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

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

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

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

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

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

הנחיות עיצוב

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

דרישות

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

המלצות

מומלץ לבצע את הפעולות הבאות:

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

2. נתונים לשיתוף. משתמשים בשפה ברורה ותמציתית כדי להסביר למשתמשים אילו נתונים Google דורשת מהם ולמה.

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

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

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

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

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

תהליך קוד ההרשאה

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

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

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

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

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

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

פרמטרים של נקודת קצה להרשאה
client_id	מזהה הלקוח שהקצית ל-Google.
redirect_uri	כתובת ה-URL שאליה שולחים את התשובה לבקשה הזו.
state	ערך חשבונאי שמוחזר ל-Google ללא שינוי ב-URI של ההפניה האוטומטית.
scope	אופציונלי: קבוצה של מחרוזות היקף מופרדות באמצעות רווחים, שמציינות את הנתונים ש-Google מבקשת הרשאה לגביהם.
response_type	סוג הערך להחזרה בתגובה. בתהליך של קוד ההרשאה של OAuth 2.0, סוג התגובה הוא תמיד code.
user_locale	הגדרת השפה בחשבון Google בפורמט RFC5646, שמשמשת ללוקליזציה של התוכן בשפה המועדפת על המשתמש.

לדוגמה, אם נקודת הקצה להרשאה זמינה בכתובת 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&user_locale=LOCALE

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

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

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

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

• המרת קודי הרשאה באסימוני גישה ובאסימוני רענון
• המרת אסימוני רענון לאסימוני גישה

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

הפרמטרים של נקודת הקצה להחלפת אסימונים
client_id	מחרוזת שמזהה את מקור הבקשה כ-Google. המחרוזת הזו צריכה להיות רשומה במערכת שלכם כמזהה הייחודי של Google.
client_secret	מחרוזת סודית שרשומה ב-Google לשירות שלכם.
grant_type	סוג הטוקן שמתבצעת בו המרה. הערך יכול להיות authorization_code או refresh_token.
code	כשהערך של grant_type=authorization_code הוא 1, הפרמטר הזה הוא הקוד ש-Google קיבלה מנקודת הקצה (endpoint) של הכניסה או של המרת האסימון.
redirect_uri	כשהערך הוא grant_type=authorization_code, הפרמטר הזה הוא כתובת ה-URL ששימשה בבקשת ההרשאה הראשונית.
refresh_token	כשהערך הוא grant_type=refresh_token, הפרמטר הזה הוא אסימון הרענון ש-Google קיבלה מנקודת הקצה של החלפת האסימונים.

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

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

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

כניסה למסוף הפיתוח

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

2. בקטע מענן לענן, בוחרים באפשרות פיתוח.

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

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
Authorization header	אסימון הגישה מסוג נושא.

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