Notice: We're retiring Works with Nest. See the home page for more information.
Google is committed to advancing racial equity for Black communities. See how.
דף זה תורגם על ידי Cloud Translation API.
Switch to English

אימות OAuth 2.0 ואישור

ממשק API של Nest משתמש בפרוטוקול OAuth 2.0 לצורך אימות ואישור.

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

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

זרימת OAuth 2.0
זרימת OAuth 2.0

קבע את התצורה של עבודות עם לקוח Nest

כדי למצוא את אישורי ה- OAuth 2.0 עבור הלקוח שלך, עיין בכרטיסייה סקירה כללית של דף הלקוח.

להפנות מחדש URI או הרשאה מבוססת PIN?

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

אם המוצר שלך הוא מכשיר שאין לו אפליקציה או דף אינטרנט משויכים (לדוגמה, גשש כושר, מכשיר או לוח אבטחה), השאר את שדות ה- URI להפנות מחדש ריקים.

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

בקש הרשאות

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

תוֹצָאָה

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

כתובת האתר להרשאה כוללת פרמטר מצב בו תוכלו להשתמש כדי לבדוק התקפות אפשריות לזיוף בקשות בין אתרים (CSRF). ראה מבחן להתקפות CSRF .

פרטי OAuth

בקש קוד הרשאה

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

חווית המשתמש

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

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

עובד עם קן

קדימה לחץ על [קבל] עצמך כדי לראות מה המשתמש רואה. על ידי לחיצה על כפתור [ACCEPT], המשתמש מאשר את בקשת המוצר שלך לגשת לנתונים שלו.

ניסיון PIN

אם אתה משאיר את שדות ה- URI להפנות ריקים בתצורת הלקוח שלך, המשתמש מופנה לדף Nest שמציג קוד PIN (קוד הרשאה). לאחר מכן, ממשק המשתמש של המכשיר צריך לבקש מהמשתמש להזין את ה- PIN באופן ידני.

קוד סודי

הפנה מחדש את חוויית ה- URI

אם אתה כולל תצורת URI להפניה מחדש בתצורת הלקוח שלך, המשתמש מנותב לדף בענן שלך (או localhost), ו- Nest שולח אוטומטית את קוד ההרשאה למכשיר המשתמש.

מבחן להתקפות CSRF

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

התקפת CSRF היא התקפה שמאלצת את משתמש הקצה לבצע פעולות לא רצויות ביישום אינטרנט בו הם מאומתים כעת.

התקפת CSRF
התקפת CSRF

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

באופן זה, שילוב ה- Works with Nest שלך יכול לאמת שקודי הגישה המתקבלים מענן Nest הם בתגובה לבקשות שהמוצר שלך לא מכין, ולא מוצר אחר.

דוגמא:

נניח בתצורת הלקוח שלך אתה מציין את ה- URI להפניה מחדש:

 http://localhost:5000/callback
 

בואו נגיד שהלקוח שלך שולח את מצב 7tvPJiv8StrAqo9IQE9xsJaDso4 בכתובת האתר להרשאה:

 https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
 

המשתמש מסכים לבקשה.

ענן הקן מחזיר את פרמטר המצב כחלק מ- URI להפניה מחדש:

 127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
 

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

ישנן מספר דרכים ליצור פרמטר מצב שאי אפשר לנחש. אתה יכול לספק ערכי מצב אקראיים ממילון שנשמר בזיכרון או מערך מחושב. אתה יכול להשתמש במפתח פרטי עם כמה משתנים שניתן לאמת בקלות - לדוגמה, מזהה הלקוח ועוגיית הפעלה - כדי לחשב ערך hashed. התוצאה היא ערך בתים שקשה לנחש ללא המפתח הפרטי. הצעה נוספת היא חשיפת התאריך והשעה הנוכחיים. בגישה זו, על היישום שלך לחסוך את זמן ההעברה כדי לאמת אותה או לאפשר תקופת החלקה של תוקף (לדוגמה, באמצעות אלגוריתם סיסמא חד-פעמי מבוסס זמן [TOTP]).

לאחר חישוב קוד אימות ההודעה המוקלט-חשיש (HMAC), base-64 קידד אותו והעביר אותו לענן Nest כפרמטר מצב.

הנה דוגמה Python המשתמשת datetime :

 import base64
import datetime
import hmac
import hashlib

def generate_state_parameter(client_id, private_key):
    date = datetime.datetime.today()
    raw_state = str(date) + client_id
    hashed = hmac.new(private_key, raw_state, hashlib.sha1)
    state = base64.b64encode(hashed.digest())
    return (state, date)
 

הודעות שגיאה בקוד הרשאה

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

החלף קוד הרשאה עבור אסימון גישה

השלב האחרון בהשגת אסימון גישה הוא שהמוצר שלך יבקש אחד מהם באמצעות קוד ההרשאה שזה עתה רכש. זה נעשה על ידי בקשת HTTP POST "x-www-form-urlencoded".

כלול את הפרמטרים שלהלן בבקשה. כל ארבעת הפרמטרים נדרשים.

פָּרָמֶטֶר תיאור
client_id זיהוי הלקוח בשלב 1
client_secret סוד הלקוח בשלב 1
קוד קוד ההרשאה שהתקבל בשלב 2
סוג המענק הערך של שדה זה צריך להיות תמיד: authorization_code

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

דוגמאות קוד (הרשאה)

ראו דוגמאות בשפות שונות .

דוגמא לדוור (הרשאה)

הדוור מספק דרך קלה לבדוק בקשות OAuth.

בכרטיסייה כותרות , ודא Content-Type = application/x-www-form-urlencoded .

כותרת POST כדי לקבל אסימון גישה

בכרטיסייה גוף , כלול את המפתח הבא: זוגות ערכים.

גוף פוסט כדי לקבל אסימון גישה

תגובת אסימון גישה

בקשה מוצלחת מחזירה אובייקט JSON המכיל את השדות הבאים:

  • access_token - אסימון הגישה למשתמש. יש לשמור על ערך זה מאובטח.
  • expires_in - מספר השניות שנותרו, מרגע שהתבקש, לפני פקיעת האסימון.

גש להודעות שגיאה באסימון

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

בצע בקשות מאומתות

לאחר שמוצר מקבל אסימון גישה, הוא שולח את האסימון לממשק API של Nest בכותרת הרשאת HTTP. אפשר לשלוח אסימונים כפרמטרים של מחרוזת שאילתת URI, אך איננו ממליצים על כך, מכיוון שפרמטרי URI יכולים להסתיים בקבצי יומן שאינם מאובטחים לחלוטין.

אסימוני גישה תקפים רק עבור מערך הפעולות והמשאבים המתוארים במסגרת בקשת האסימון. לדוגמה, אם מונפק אסימון גישה עבור ממשק ה- API של Nest Thermostat, הוא אינו מעניק גישה לממשק ה- API של מצלמת Nest.

דוגמאות קוד (לקרוא / לכתוב)

דוגמא לדוור (לקרוא / לכתוב)

הדוור מספק דרך קלה לבדוק שיחות API באמצעות Content-Type = application/json .

קבל לקרוא נתונים

אסימונים לא חוקיים

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

  • התוקף פג
  • המשתמש ביטל את ההרשאה שהעניקו בתחילה למוצר שלך

חשוב שתקודד את המוצר שלך כדי לטפל כראוי בשגיאה לא מורשית 401 על ידי הפניית המשתמש חזרה לתחילת זרימת העבודה של ההרשאה.

עובד עם חיבור קן סגור

אם משתמש מסיר חיבור Works with Nest , המוצר שלך מקבל אירוע auth_revoked והחיבור נסגר.