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

כל פעולה ב-smart home חייבת לכלול מנגנון לאימות משתמשים.

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

בדף הזה מוסבר איך להגדיר את שרת OAuth 2.0 כך שיעבוד עם הפעולה smart home שלכם.

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

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

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

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

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

הנחיות עיצוב

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

הדרישות

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

המלצות

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

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

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

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

4. היכולת לבטל את המינוי. תנו למשתמשים אפשרות לחזור או לבטל את המינוי אם הם יבחרו לא לקשר.

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

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

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

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

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

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

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

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

אחרי שהמשתמש נכנס לחשבון, ונקודת הקצה להרשאה מחזירה את קוד ההרשאה לטווח קצר ל-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 בגוף ההודעה.
5. אחרת, השתמשו במזהה המשתמש מקוד ההרשאה כדי ליצור אסימון רענון ואסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם חייבים לייצג את המשתמש והלקוח באופן ייחודי, ואסור לנחש אותם. באסימוני הגישה, יש לתעד גם את מועד התפוגה של האסימון, בדרך כלל שעה לאחר הנפקת האסימון. התוקף של אסימונים חדשים פג.
6. מחזירים את אובייקט JSON הבא בגוף התגובה של HTTPS:

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

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

אסימוני רענון של Exchange עבור אסימוני גישה

כשפג התוקף של אסימון הגישה, 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 בגוף ההודעה.
4. אחרת, השתמשו במזהה המשתמש מאסימון הרענון כדי ליצור אסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם צריכים לייצג את המשתמש והלקוח באופן ייחודי, והם לא יכולים להיות ניתנים לניחוש. עבור אסימוני גישה, יש לתעד גם את מועד התפוגה של האסימון, בדרך כלל שעה לאחר הנפקת האסימון.
5. מחזירים את אובייקט JSON הבא בגוף התגובה ל-HTTPS:

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

ניהול בקשות למידע על משתמשים

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

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

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

כותרות של בקשות לנקודות קצה (endpoint) של משתמשים
Authorization header	אסימון הגישה מסוג Bearer.

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

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

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

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

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

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

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

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

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

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