Google cam kết thúc đẩy công bằng chủng tộc cho các cộng đồng Đen. Xem thế nào.
Trang này được dịch bởi Cloud Translation API.
Switch to English

Xác thực và ủy quyền OAuth 2.0

API Nest sử dụng giao thức OAuth 2.0 để xác thực và ủy quyền.

Trước khi sản phẩm của bạn có thể truy cập dữ liệu riêng tư bằng API Nest, nó phải có được mã thông báo truy cập cấp quyền truy cập vào API đó. Một mã thông báo truy cập duy nhất có thể cấp các mức độ truy cập khác nhau cho nhiều phần của API.

Trình tự ủy quyền bắt đầu khi sản phẩm của bạn chuyển hướng trình duyệt đến URL Nest với các tham số truy vấn cho biết quyền truy cập được yêu cầu. Nest xử lý xác thực người dùng, lựa chọn phiên và sự đồng ý của người dùng. Kết quả là một mã ủy quyền mà sản phẩm của bạn có thể đổi lấy mã thông báo truy cập. Sau đó, sản phẩm của bạn có thể sử dụng mã thông báo truy cập để thực hiện các cuộc gọi đến Nest API.

Luồng OAuth 2.0
Luồng OAuth 2.0

Định cấu hình Tác phẩm của bạn với máy khách Nest

Để tìm thông tin đăng nhập OAuth 2.0 cho khách hàng của bạn, hãy kiểm tra tab Tổng quan của trang khách.

Chuyển hướng URI hoặc ủy quyền dựa trên mã PIN?

Khi bạn định cấu hình ứng dụng khách của mình, bạn được nhắc nhập URI chuyển hướng hoặc để trống các trường URI chuyển hướng để sử dụng ủy quyền dựa trên mã PIN.

Nếu sản phẩm của bạn là thiết bị không có ứng dụng hoặc trang web được liên kết (ví dụ: bộ theo dõi thể dục, thiết bị hoặc bảng bảo mật), hãy để trống các trường URI chuyển hướng.

Nếu sản phẩm của bạn có thành phần trình duyệt, cách tốt nhất là bao gồm URI chuyển hướng.

Yêu cầu quyền

Cấu hình máy khách bao gồm một tập các quyền (còn được gọi là phạm vi). Quyền là một tham số biến điều khiển tập hợp các tài nguyên và hoạt động mà mã thông báo truy cập cho phép. Nói chung, đó là cách tốt nhất để yêu cầu cấp phép tăng dần, tại thời điểm yêu cầu truy cập, thay vì lên phía trước.

Kết quả

Khi bạn lưu cấu hình, ứng dụng khách của bạn được gán ID khách hàng và Bí mật khách hàng duy nhất. Ngoài ra, khách hàng của bạn được chỉ định một URL ủy quyền.

URL ủy quyền bao gồm một tham số trạng thái mà bạn có thể sử dụng để kiểm tra các cuộc tấn công giả mạo yêu cầu chéo trang web (CSRF) có thể. Xem Kiểm tra các cuộc tấn công CSRF .

Chi tiết OAuth

Yêu cầu mã ủy quyền

Sau khi khách hàng của bạn được định cấu hình, bạn có thể yêu cầu mã ủy quyền (đôi khi được gọi là mã PIN). Mã ủy quyền không phải là mã thông báo cuối cùng mà bạn sử dụng để thực hiện cuộc gọi đến Nest. Nó được sử dụng trong bước tiếp theo của luồng OAuth 2.0 để đổi lấy mã thông báo truy cập thực tế. Bước này cung cấp sự đảm bảo trực tiếp từ Nest cho người dùng rằng quyền được cấp cho sản phẩm chính xác, với quyền truy cập theo thỏa thuận.

Trải nghiệm người dùng

Chúng tôi trình bày trang Hoạt động với Nest yêu cầu người dùng cấp quyền truy cập vào sản phẩm của bạn. Điều này xác định sản phẩm của bạn và phác thảo các quyền (phạm vi) cụ thể mà sản phẩm của bạn đã yêu cầu. Các từ trên màn hình đến từ cấu hình máy khách của bạn.

Để tự kiểm tra điều này, hãy tải URL ủy quyền từ Bước 1 vào trình duyệt. Bạn sẽ thấy trang yêu cầu truy cập Công trình với Nest:

Làm việc với Nest

Hãy tiếp tục và nhấp vào [CHẤP NHẬN] để xem người dùng thấy gì. Bằng cách nhấp vào nút [CHẤP NHẬN], người dùng sẽ phê duyệt yêu cầu sản phẩm của bạn để truy cập dữ liệu của họ.

Trải nghiệm mã PIN

Nếu bạn để trống các trường URI chuyển hướng trong cấu hình máy khách của mình, người dùng sẽ được chuyển hướng đến trang Nest hiển thị mã PIN (mã ủy quyền). Giao diện người dùng thiết bị của bạn sau đó sẽ nhắc người dùng nhập mã PIN theo cách thủ công.

Mã PIN

Chuyển hướng trải nghiệm URI

Nếu bạn bao gồm URI chuyển hướng trong cấu hình máy khách của mình, người dùng sẽ được chuyển hướng đến một trang trong đám mây của bạn (hoặc localhost) và Nest sẽ tự động gửi mã ủy quyền đến thiết bị của người dùng.

Kiểm tra các cuộc tấn công CSRF

Trước khi chấp nhận mã ủy quyền, sản phẩm của bạn phải đảm bảo rằng giá trị được trả về trong tham số trạng thái khớp với giá trị trạng thái từ yêu cầu ủy quyền ban đầu của bạn. Điều này đảm bảo rằng bạn đang giao dịch với người dùng thực tế chứ không phải là một tập lệnh độc hại. Nếu các giá trị trạng thái không khớp, bạn nên phản hồi mã lỗi HTTP trái phép 401.

Tấn công CSRF là một cuộc tấn công buộc người dùng cuối phải thực hiện các hành động không mong muốn trên ứng dụng web hiện đang được xác thực.

Tấn công CSRF
Tấn công CSRF

Để giúp ngăn chặn các cuộc tấn công CSRF, chúng tôi khuyên bạn luôn gửi state khi yêu cầu ủy quyền.

Bằng cách này, tích hợp Công trình với Nest có thể xác minh rằng các mã truy cập thu được từ đám mây Nest phù hợp với các yêu cầu được tạo bởi sản phẩm của bạn chứ không phải một số sản phẩm khác.

Thí dụ:

Giả sử trong cấu hình máy khách của bạn, bạn chỉ định URI chuyển hướng:

 http://localhost:5000/callback
 

Giả sử khách hàng của bạn gửi trạng thái 7tvPJiv8StrAqo9IQE9xsJaDso4 trong URL ủy quyền:

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

Người dùng đồng ý với yêu cầu.

Đám mây Nest trả về tham số trạng thái như một phần của URI chuyển hướng:

 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 -
 

Sản phẩm của bạn nhận được giá trị trạng thái này và phải được lập trình để chỉ chấp nhận chuyển hướng với trạng thái có thể kiểm chứng.

Có nhiều cách để tạo một tham số trạng thái không thể đoán được. Bạn có thể cung cấp các giá trị trạng thái ngẫu nhiên từ một từ điển được lưu trong bộ nhớ hoặc giá trị tính toán lại. Bạn có thể sử dụng khóa riêng với một số biến có thể xác minh dễ dàng, ví dụ, ID khách và cookie phiên phiên để tính toán giá trị băm. Điều này dẫn đến một giá trị byte rất khó đoán nếu không có khóa riêng. Một đề nghị khác là băm ngày giờ hiện tại. Với phương pháp này, ứng dụng của bạn phải tiết kiệm thời gian truyền để xác minh hoặc cho phép thời gian hiệu lực trượt (ví dụ: sử dụng thuật toán Mật khẩu một lần dựa trên thời gian [TOTP]).

Sau khi tính toán mã xác thực tin nhắn băm (HMAC), cơ sở 64 mã hóa nó và chuyển nó đến đám mây Nest dưới dạng tham số trạng thái.

Đây là một ví dụ Python sử dụng 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)
 

Thông báo lỗi mã ủy quyền

Nếu yêu cầu mã ủy quyền không thành công, người dùng sẽ thấy thông báo lỗi. Để biết thêm thông tin về các tin nhắn này và cách ngăn chặn chúng, hãy xem Tài liệu tham khảo ủy quyền .

Trao đổi mã ủy quyền cho mã thông báo truy cập

Bước cuối cùng để có được mã thông báo truy cập là cho sản phẩm của bạn yêu cầu một mã sử dụng mã ủy quyền mà nó vừa có được. Điều này được thực hiện bằng cách thực hiện yêu cầu HTTP POST "x-www-form-urlencoding".

Bao gồm các tham số dưới đây trong yêu cầu. Tất cả bốn thông số được yêu cầu.

Tham số Sự miêu tả
khách hàng ID khách hàng ở Bước 1
khách hàng Bí mật khách hàng ở Bước 1
Mã ủy quyền nhận được ở Bước 2
Grant_type Giá trị của trường này phải luôn là: authorization_code

Trước mỗi cuộc gọi POST, nhận mã ủy quyền mới. Để làm điều này, tải lại URL ủy quyền của bạn. Sau đó thay đổi tham số code của POST để bao gồm mã ủy quyền mới.

Mã ví dụ (auth)

Xem các ví dụ trong các ngôn ngữ khác nhau .

Ví dụ người đưa thư (auth)

Người đưa thư cung cấp một cách dễ dàng để kiểm tra các yêu cầu OAuth.

Trên tab Tiêu đề , đảm bảo Content-Type = application/x-www-form-urlencoded .

POST tiêu đề để nhận mã thông báo truy cập

Trên tab Thân , bao gồm các cặp khóa: giá trị sau.

POST cơ thể để có được mã thông báo truy cập

Truy cập phản hồi mã thông báo

Một yêu cầu thành công trả về một đối tượng JSON chứa các trường sau:

  • access_token - Mã thông báo truy cập cho người dùng. Giá trị này phải được giữ an toàn.
  • expires_in - Số giây còn lại, kể từ thời điểm được yêu cầu, trước khi mã thông báo hết hạn.

Truy cập thông báo lỗi mã thông báo

Nếu yêu cầu không thành công, bạn sẽ nhận được lỗi dưới dạng Mã trạng thái HTTP. Để biết thêm thông tin về các lỗi này và cách phòng ngừa, hãy xem Tài liệu tham khảo ủy quyền .

Thực hiện các yêu cầu xác thực

Sau khi sản phẩm nhận được mã thông báo truy cập, nó sẽ gửi mã thông báo đến API Nest trong tiêu đề ủy quyền HTTP. Có thể gửi mã thông báo dưới dạng tham số chuỗi truy vấn URI, nhưng chúng tôi không khuyến nghị điều đó, vì các tham số URI có thể kết thúc trong các tệp nhật ký không hoàn toàn an toàn.

Mã thông báo truy cập chỉ hợp lệ cho tập hợp các hoạt động và tài nguyên được mô tả trong phạm vi yêu cầu mã thông báo. Ví dụ: nếu mã thông báo truy cập được cấp cho API Bộ điều nhiệt Nest, thì nó không cấp quyền truy cập cho API Camera của Nest.

Ví dụ mã (đọc / ghi)

Ví dụ người đưa thư (đọc / ghi)

Người đưa thư cung cấp một cách dễ dàng để kiểm tra các lệnh gọi API bằng Content-Type = application/json .

NHẬN để đọc dữ liệu

Mã thông báo không hợp lệ

Nếu bạn thực hiện cuộc gọi API bằng mã thông báo không hợp lệ, bạn sẽ nhận được phản hồi trái phép 401 từ máy chủ. Mã thông báo có thể không hợp lệ và cần được tạo lại vì:

  • Nó đã hết hạn
  • Người dùng đã thu hồi quyền ban đầu họ cấp cho sản phẩm của bạn

Điều quan trọng là bạn phải mã hóa sản phẩm của mình để xử lý đúng lỗi 401 Không được phép bằng cách chuyển hướng người dùng trở lại bắt đầu quy trình ủy quyền.

Hoạt động với kết nối Nest đóng

Nếu người dùng xóa một trình với kết nối Nest , sản phẩm của bạn nhận được một auth_revoked sự kiện và đóng cửa kết nối.