Google มุ่งมั่นที่จะพัฒนาความเท่าเทียมทางเชื้อชาติสำหรับชุมชนคนผิวดำ มาดูกันว่า
หน้านี้ได้รับการแปลโดย 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 และการเชื่อมต่อจะปิดลง