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

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

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

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

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

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

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

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

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

הנחיות עיצוב

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

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

כותרות של בקשות לנקודות קצה (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 אופציונלי: תמונת פרופיל של המשתמש.
הקודם
רשימת משימות למפתחים
הבא
יצירה של פרויקט פעולות