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

Nest API ใช้โปรโตคอล OAuth 2.0 สำหรับการตรวจสอบและการอนุญาต

ก่อนที่ผลิตภัณฑ์ของคุณจะสามารถเข้าถึงข้อมูลส่วนตัวโดยใช้ Nest API ต้องได้รับโทเค็นการเข้าถึงที่ให้สิทธิ์การเข้าถึง API นั้น โทเค็นการเข้าถึงเดียวสามารถให้สิทธิ์การเข้าถึงที่หลากหลายไปยังส่วนต่างๆของ API

ลำดับการอนุญาตเริ่มต้นเมื่อผลิตภัณฑ์ของคุณเปลี่ยนเส้นทางเบราว์เซอร์ไปยัง Nest URL พร้อมพารามิเตอร์การสืบค้นที่ระบุถึงการเข้าถึงที่ร้องขอ Nest จัดการกับการตรวจสอบผู้ใช้การเลือกเซสชันและการยินยอมของผู้ใช้ ผลลัพธ์คือรหัสการอนุญาตที่ผลิตภัณฑ์ของคุณสามารถแลกเปลี่ยนเป็นโทเค็นการเข้าถึง ผลิตภัณฑ์ของคุณสามารถใช้โทเค็นการเข้าถึงเพื่อโทรหา Nest API

OAuth 2.0 flow
OAuth 2.0 flow

กำหนดค่าการทำงานกับไคลเอนต์ Nest

ในการค้นหาข้อมูลรับรอง OAuth 2.0 สำหรับลูกค้าของคุณให้ตรวจสอบแท็บภาพรวมของหน้าลูกค้า

เปลี่ยนเส้นทาง URI หรือการให้สิทธิ์โดยใช้ PIN หรือไม่

เมื่อคุณกำหนดค่าไคลเอนต์ของคุณคุณจะได้รับพร้อมท์ให้ป้อน URI การเปลี่ยนเส้นทางหรือปล่อยให้ฟิลด์ URI การเปลี่ยนเส้นทางว่างเปล่าเพื่อใช้การอนุญาตตาม PIN

หากผลิตภัณฑ์ของคุณเป็นอุปกรณ์ที่ไม่มีแอพหรือหน้าเว็บที่เกี่ยวข้อง (ตัวอย่างเช่นตัวติดตามฟิตเนส, อุปกรณ์หรือแผงความปลอดภัย) ให้ปล่อยฟิลด์ Redirect URI ว่างไว้

หากผลิตภัณฑ์ของคุณมีองค์ประกอบของเบราว์เซอร์แนวทางปฏิบัติที่ดีที่สุดคือการรวม URI การเปลี่ยนเส้นทาง

ขอสิทธิ์

การกำหนดค่าไคลเอนต์รวมถึงชุดของสิทธิ์ (เรียกอีกอย่างว่าขอบเขต) การอนุญาตคือพารามิเตอร์ตัวแปรที่ควบคุมชุดของทรัพยากรและการดำเนินการที่โทเค็นการเข้าถึงอนุญาต โดยทั่วไปแล้วเป็นวิธีปฏิบัติที่ดีที่สุดในการขอสิทธิ์แบบเพิ่มเติมในเวลาที่จำเป็นต้องมีการเข้าถึงมากกว่าล่วงหน้า

ผลลัพธ์

เมื่อคุณบันทึกการกำหนดค่าไคลเอนต์ของคุณจะได้รับรหัสลูกค้าที่ไม่ซ้ำกันและความลับของลูกค้า นอกจากนี้ลูกค้าของคุณได้รับการกำหนด URL การอนุญาต

URL การอนุญาตประกอบด้วยพารามิเตอร์สถานะที่คุณสามารถใช้ทดสอบการโจมตีการปลอมแปลงคำขอข้ามไซต์ (CSRF) ที่เป็นไปได้ ดู การทดสอบการโจมตี CSRF

รายละเอียดของ OAuth

ขอรหัสอนุญาต

หลังจากกำหนดค่าไคลเอนต์ของคุณแล้วคุณสามารถขอรหัสอนุญาต (บางครั้งเรียกว่ารหัส PIN) รหัสการอนุญาตไม่ใช่โทเค็นสุดท้ายที่คุณใช้ในการโทรหา Nest มันถูกใช้ในขั้นตอนถัดไปของโฟลว์ OAuth 2.0 เพื่อแลกเปลี่ยนโทเค็นการเข้าถึงจริง ขั้นตอนนี้ให้การรับรองโดยตรงจาก Nest แก่ผู้ใช้ว่าได้รับอนุญาตให้ใช้ผลิตภัณฑ์ที่ถูกต้องพร้อมการเข้าถึงที่ตกลง

ประสบการณ์การใช้งาน

เรานำเสนอหน้าทำงานร่วมกับ Nest ซึ่งขอให้ผู้ใช้ให้สิทธิ์การเข้าถึงผลิตภัณฑ์ของคุณ สิ่งนี้จะระบุผลิตภัณฑ์ของคุณและแสดงสิทธิ์ผู้ใช้เฉพาะ (ขอบเขต) ที่ผลิตภัณฑ์ของคุณร้องขอ คำบนหน้าจอมาจากการกำหนดค่าไคลเอ็นต์ของคุณ

ในการทดสอบด้วยตนเองโหลด URL การอนุญาตจากขั้นตอนที่ 1 ลงในเบราว์เซอร์ คุณควรเห็นหน้าคำขอเข้าถึงการทำงานกับ Nest:

ทำงานร่วมกับ Nest

ไปข้างหน้าและคลิก [ยอมรับ] ตัวคุณเองเพื่อดูว่าผู้ใช้เห็นอะไร โดยการคลิกปุ่ม [ยอมรับ] ผู้ใช้กำลังอนุมัติคำขอของผลิตภัณฑ์ของคุณเพื่อเข้าถึงข้อมูล

ประสบการณ์ PIN

หากคุณปล่อยให้ฟิลด์ Redirect URI ว่างในการกำหนดค่าไคลเอนต์ของคุณผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังหน้า Nest ที่แสดง PIN (รหัสการอนุญาต) UI อุปกรณ์ของคุณควรแจ้งให้ผู้ใช้ป้อน PIN ด้วยตนเอง

Pincode

เปลี่ยนเส้นทาง URI

หากคุณรวม URI การเปลี่ยนเส้นทางในการกำหนดค่าไคลเอนต์ของคุณผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังหน้าเว็บในคลาวด์ของคุณ (หรือ localhost) และ Nest จะส่งรหัสการอนุญาตไปยังอุปกรณ์ของผู้ใช้โดยอัตโนมัติ

ทดสอบการโจมตี CSRF

ก่อนที่จะยอมรับรหัสการอนุญาตผลิตภัณฑ์ของคุณควรตรวจสอบให้แน่ใจว่าค่าที่ส่งคืนในพารามิเตอร์รัฐตรงกับค่าสถานะจากคำขอการให้สิทธิ์ดั้งเดิมของคุณ สิ่งนี้ทำให้มั่นใจได้ว่าคุณกำลังติดต่อกับผู้ใช้จริงไม่ใช่สคริปต์ที่เป็นอันตราย หากค่าสถานะไม่ตรงกันคุณควรโยนรหัสข้อผิดพลาด HTTP Unauthorized HTTP 401 เพื่อตอบกลับ

การโจมตี CSRF เป็นการโจมตีที่บังคับให้ผู้ใช้ปลายทางดำเนินการกระทำที่ไม่พึงประสงค์บนเว็บแอปพลิเคชันที่พวกเขากำลังตรวจสอบความถูกต้องในปัจจุบัน

การโจมตี CSRF
การโจมตี CSRF

เพื่อช่วยป้องกันการโจมตี CSRF เราขอแนะนำให้คุณส่ง state เมื่อร้องขอการอนุญาต

ด้วยวิธีนี้การรวมทำงานร่วมกับ Nest ของคุณสามารถตรวจสอบได้ว่ารหัสการเข้าถึงที่ได้รับจาก Nest cloud นั้นเป็นการตอบสนองต่อคำขอที่ทำโดยผลิตภัณฑ์ของคุณไม่ใช่ผลิตภัณฑ์อื่น

ตัวอย่าง:

สมมติว่าในการกำหนดค่าไคลเอนต์ของคุณคุณระบุ URI เปลี่ยนเส้นทาง:

 http://localhost:5000/callback
 

สมมติว่าลูกค้าของคุณส่งสถานะ 7tvPJiv8StrAqo9IQE9xsJaDso4 ใน URL การอนุญาต:

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

ผู้ใช้ยินยอมให้มีการร้องขอ

Nest cloud ส่งคืนพารามิเตอร์ state โดยเป็นส่วนหนึ่งของ 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 -
 

ผลิตภัณฑ์ของคุณได้รับค่าสถานะนี้และควรตั้งโปรแกรมให้ยอมรับการเปลี่ยนเส้นทางด้วยสถานะที่ตรวจสอบได้เท่านั้น

มีหลายวิธีในการสร้างพารามิเตอร์สถานะที่ไม่สามารถคาดเดาได้ คุณสามารถระบุค่าสถานะแบบสุ่มจากพจนานุกรมที่เก็บไว้ในหน่วยความจำหรือค่าที่คำนวณได้ คุณสามารถใช้ไพรเวตคีย์กับตัวแปรที่ตรวจสอบได้ง่ายเช่นรหัสลูกค้าและคุกกี้เซสชันเพื่อคำนวณค่าที่แฮช ส่งผลให้มีค่าไบต์ที่ยากต่อการคาดเดาโดยไม่มีคีย์ส่วนตัว ข้อเสนอแนะอีกประการหนึ่งคือการแฮชวันที่และเวลาปัจจุบัน ด้วยวิธีนี้แอปพลิเคชันของคุณจะต้องประหยัดเวลาในการส่งเพื่อตรวจสอบหรืออนุญาตให้มีช่วงเวลาที่เลื่อนได้ (ตัวอย่างเช่นการใช้อัลกอริทึมรหัสผ่านแบบใช้ครั้งเดียวตามเวลา [TOTP])

หลังจากคำนวณรหัสการพิสูจน์ตัวตนข้อความแฮ็ชคีย์ (HMAC) แล้วเบส -64 จะเข้ารหัสและส่งไปยัง Nest cloud เป็นพารามิเตอร์สถานะ

นี่คือตัวอย่างของ 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
grant_type ค่าของฟิลด์นี้ควรเป็น: authorization_code

ก่อนการเรียก POST แต่ละครั้งจะได้รับรหัสอนุญาตใหม่ ในการดำเนินการนี้ให้โหลด URL การอนุญาตของคุณอีกครั้ง จากนั้นเปลี่ยนพารามิเตอร์ code ของ POST เพื่อรวมรหัสการอนุญาตใหม่

ตัวอย่างรหัส (รับรองความถูกต้อง)

ดูตัวอย่างในภาษาต่างๆ

ตัวอย่างบุรุษไปรษณีย์ (รับรองความถูกต้อง)

บุรุษไปรษณีย์จัดเตรียมวิธีง่ายๆในการทดสอบคำขอ OAuth

บนแท็บ ส่วนหัว ตรวจสอบให้แน่ใจว่า Content-Type = application/x-www-form-urlencoded

ส่วนหัว POST เพื่อรับโทเค็นการเข้าถึง

บนแท็บ Body ให้ใส่รหัสต่อไปนี้: คู่ของค่า

POST body เพื่อรับโทเค็นการเข้าถึง

การตอบสนองโทเค็นการเข้าถึง

คำขอสำเร็จจะส่งคืนออบเจกต์ JSON ที่มีฟิลด์ต่อไปนี้:

  • access_token - โทเค็นการเข้าถึงสำหรับผู้ใช้ ค่านี้จะต้องรักษาความปลอดภัย
  • expires_in - จำนวนวินาทีที่เหลือจากเวลาที่ร้องขอก่อนที่โทเค็นจะหมดอายุ

เข้าถึงข้อความแสดงข้อผิดพลาดของโทเค็น

หากคำขอล้มเหลวคุณจะได้รับข้อผิดพลาดในรูปแบบของรหัสสถานะ HTTP สำหรับข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดเหล่านี้และวิธีการป้องกันให้ดูการ อ้างอิงการอนุญาต

ขอการรับรองความถูกต้อง

หลังจากผลิตภัณฑ์ได้รับโทเค็นการเข้าถึงแล้วจะส่งโทเค็นไปยัง Nest API ในส่วนหัวการอนุญาต HTTP เป็นไปได้ที่จะส่งโทเค็นเป็นพารามิเตอร์สตริงแบบสอบถาม URI แต่เราไม่แนะนำเพราะพารามิเตอร์ URI สามารถจบลงในไฟล์บันทึกที่ไม่ปลอดภัยอย่างสมบูรณ์

โทเค็นการเข้าถึงจะใช้ได้เฉพาะกับชุดของการดำเนินการและทรัพยากรที่อธิบายไว้ในขอบเขตของการร้องขอโทเค็น ตัวอย่างเช่นหากมีการออกโทเค็นการเข้าถึงสำหรับ Nest Thermostat API จะไม่อนุญาตให้เข้าถึง Nest Camera API

ตัวอย่างโค้ด (อ่าน / เขียน)

ตัวอย่างบุรุษไปรษณีย์ (อ่าน / เขียน)

บุรุษไปรษณีย์จัดให้มีวิธีทดสอบการเรียก API โดยง่ายโดยใช้ Content-Type = application/json

รับอ่านข้อมูล

โทเค็นไม่ถูกต้อง

หากคุณทำการเรียก API โดยใช้โทเค็นที่ไม่ถูกต้องคุณจะได้รับการตอบกลับที่ไม่ได้รับอนุญาต 401 จากเซิร์ฟเวอร์ โทเค็นอาจไม่ถูกต้องและต้องการการฟื้นฟูเนื่องจาก:

  • มันหมดอายุแล้ว
  • ผู้ใช้ได้เพิกถอนการอนุญาตที่พวกเขาให้กับผลิตภัณฑ์ของคุณในตอนแรก

เป็นสิ่งสำคัญที่คุณต้องใช้รหัสผลิตภัณฑ์ของคุณเพื่อจัดการข้อผิดพลาด 401 ที่ไม่ได้รับอนุญาตอย่างถูกต้องโดยการเปลี่ยนเส้นทางผู้ใช้กลับไปที่จุดเริ่มต้นของขั้นตอนการอนุญาต

ทำงานกับการปิดการเชื่อมต่อ Nest

หากผู้ใช้ลบ การเชื่อมต่อทำงานร่วมกับ Nest ผลิตภัณฑ์ของคุณจะได้รับเหตุการณ์ auth_revoked และการเชื่อมต่อจะปิดลง