Notice: We're retiring Works with Nest. See the home page for more information.
Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.
Halaman ini diterjemahkan oleh Cloud Translation API.
Switch to English

OAuth 2.0 Otentikasi dan Otorisasi

Nest API menggunakan protokol OAuth 2.0 untuk otentikasi dan otorisasi.

Sebelum produk Anda dapat mengakses data pribadi menggunakan API Nest, ia harus memperoleh token akses yang memberikan akses ke API itu. Token akses tunggal dapat memberikan berbagai tingkat akses ke berbagai bagian API.

Urutan otorisasi dimulai ketika produk Anda mengalihkan browser ke URL Nest dengan parameter kueri yang menunjukkan akses yang diminta. Nest menangani otentikasi pengguna, pemilihan sesi, dan persetujuan pengguna. Hasilnya adalah kode otorisasi, yang dapat ditukar dengan produk Anda dengan token akses. Produk Anda kemudian dapat menggunakan token akses untuk melakukan panggilan ke Nest API.

OAuth 2.0 mengalir
OAuth 2.0 mengalir

Konfigurasikan Pekerjaan Anda dengan klien Nest

Untuk menemukan kredensial OAuth 2.0 untuk klien Anda, periksa tab Ikhtisar dari halaman klien.

Redirect URI atau otorisasi berbasis PIN?

Saat Anda mengonfigurasi klien Anda, Anda diminta untuk memasukkan URI redirect atau membiarkan bidang URI redirect kosong untuk menggunakan otorisasi berbasis PIN.

Jika produk Anda adalah perangkat yang tidak memiliki aplikasi atau halaman web terkait (misalnya, pelacak kebugaran, alat, atau panel keamanan), biarkan bidang Pengalihan URI kosong.

Jika produk Anda memiliki komponen browser, praktik terbaik adalah memasukkan URI redirect.

Minta izin

Konfigurasi klien mencakup seperangkat izin (juga disebut cakupan). Izin adalah parameter variabel yang mengontrol rangkaian sumber daya dan operasi yang diizinkan oleh token akses. Biasanya merupakan praktik terbaik untuk meminta izin secara bertahap, pada saat akses diperlukan, bukan di muka.

Hasil

Saat Anda menyimpan konfigurasi, klien Anda diberikan ID Klien dan Rahasia Klien yang unik. Selain itu, klien Anda diberi URL otorisasi.

URL otorisasi mencakup parameter status yang dapat Anda gunakan untuk menguji kemungkinan serangan pemalsuan permintaan lintas situs (CSRF). Lihat Uji untuk serangan CSRF .

Rincian OAuth

Minta kode otorisasi

Setelah klien Anda dikonfigurasi, Anda dapat meminta kode otorisasi (kadang-kadang disebut kode PIN). Kode otorisasi bukan token terakhir yang Anda gunakan untuk melakukan panggilan ke Nest. Ini digunakan pada langkah selanjutnya dari aliran OAuth 2.0 untuk bertukar dengan token akses aktual. Langkah ini memberikan jaminan langsung dari Nest kepada pengguna bahwa izin diberikan kepada produk yang benar, dengan akses yang disepakati.

Pengalaman pengguna

Kami menyajikan halaman Works with Nest yang meminta pengguna untuk memberikan akses ke produk Anda. Ini mengidentifikasi produk Anda dan menguraikan izin pengguna tertentu (cakupan) yang diminta produk Anda. Kata-kata di layar berasal dari konfigurasi klien Anda.

Untuk mengujinya sendiri, muat URL otorisasi dari Langkah 1 ke dalam browser. Anda akan melihat halaman permintaan akses Bekerja dengan Sarang:

Bekerja dengan Nest

Silakan dan klik [MENERIMA] diri Anda untuk melihat apa yang dilihat pengguna. Dengan mengklik tombol [MENERIMA], pengguna menyetujui permintaan produk Anda untuk mengakses data mereka.

Pengalaman PIN

Jika Anda membiarkan bidang Pengalihan URI kosong di konfigurasi klien Anda, pengguna diarahkan ke halaman Nest yang menampilkan PIN (kode otorisasi). UI perangkat Anda kemudian akan meminta pengguna untuk memasukkan PIN secara manual.

Kode PIN

Arahkan pengalaman URI

Jika Anda menyertakan redirect URI dalam konfigurasi klien Anda, pengguna diarahkan ke halaman di cloud Anda (atau localhost), dan Nest secara otomatis mengirim kode otorisasi ke perangkat pengguna.

Tes untuk serangan CSRF

Sebelum menerima kode otorisasi, produk Anda harus memastikan bahwa nilai yang dikembalikan pada parameter status cocok dengan nilai status dari permintaan otorisasi asli Anda. Ini memastikan bahwa Anda berurusan dengan pengguna yang sebenarnya dan bukan skrip berbahaya. Jika nilai status tidak cocok, Anda harus memberikan kode kesalahan HTTP 401 yang tidak sah sebagai tanggapan.

Serangan CSRF adalah serangan yang memaksa pengguna akhir untuk melakukan tindakan yang tidak diinginkan pada aplikasi web di mana mereka saat ini diautentikasi.

Serangan CSRF
Serangan CSRF

Untuk membantu mencegah serangan CSRF, kami sarankan Anda selalu mengirimkan state ditembus saat meminta otorisasi.

Dengan cara ini, integrasi Works with Nest Anda dapat memverifikasi bahwa kode akses yang diperoleh dari cloud Nest menanggapi permintaan yang dibuat oleh produk Anda, bukan produk lain.

Contoh:

Katakanlah di konfigurasi klien Anda, Anda menentukan URI redirect:

 http://localhost:5000/callback
 

Katakan juga klien Anda mengirimkan status 7tvPJiv8StrAqo9IQE9xsJaDso4 di URL otorisasi:

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

Pengguna menyetujui permintaan tersebut.

Nest cloud mengembalikan parameter status sebagai bagian dari redirect 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 -
 

Produk Anda menerima nilai status ini dan harus diprogram untuk hanya menerima arahan ulang dengan status yang dapat diverifikasi.

Ada beberapa cara untuk menghasilkan parameter status yang tidak dapat ditebak. Anda dapat memberikan nilai status acak dari kamus yang disimpan dalam memori atau nilai yang dapat dihitung ulang. Anda dapat menggunakan kunci pribadi dengan beberapa variabel yang mudah diverifikasi — misalnya, ID klien dan cookie sesi — untuk menghitung nilai hash. Ini menghasilkan nilai byte yang sulit ditebak tanpa kunci pribadi. Saran lain adalah hash tanggal dan waktu saat ini. Dengan pendekatan ini, aplikasi Anda harus menghemat waktu pengiriman untuk memverifikasinya atau memungkinkan masa geser validitas (misalnya, menggunakan algoritme Sandi Satu Kali Berbasis Waktu [TOTP]).

Setelah menghitung kode otentikasi pesan kunci-hash (HMAC), base-64 mengkodekannya dan meneruskannya ke Nest cloud sebagai parameter keadaan.

Berikut adalah contoh Python yang menggunakan 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)
 

Pesan kesalahan kode otorisasi

Jika permintaan kode otorisasi gagal, pengguna melihat pesan kesalahan. Untuk informasi lebih lanjut tentang pesan-pesan ini dan cara mencegahnya, lihat Referensi Otorisasi .

Pertukarkan kode otorisasi untuk token akses

Langkah terakhir dalam memperoleh token akses adalah untuk produk Anda meminta satu dengan menggunakan kode otorisasi yang baru saja diperoleh. Ini dilakukan dengan membuat permintaan HTTP POST "x-www-form-urlencoded".

Sertakan parameter di bawah ini dalam permintaan. Keempat parameter diperlukan.

Parameter Deskripsi
client_id ID Klien pada Langkah 1
client_secret Rahasia Klien pada Langkah 1
kode Kode otorisasi diterima pada Langkah 2
grant_type Nilai bidang ini harus selalu: authorization_code

Sebelum setiap panggilan POST, dapatkan kode otorisasi baru. Untuk melakukan ini, muat ulang URL otorisasi Anda. Kemudian ubah parameter code POST untuk memasukkan kode otorisasi baru.

Contoh kode (auth)

Lihat contoh dalam berbagai bahasa .

Contoh tukang pos (auth)

Tukang pos menyediakan cara mudah untuk menguji permintaan OAuth.

Pada tab Header , pastikan Content-Type = application/x-www-form-urlencoded .

Header POST untuk mendapatkan token akses

Pada tab Tubuh , sertakan kunci berikut: pasangan nilai.

Badan POST untuk mendapatkan token akses

Akses token response

Permintaan yang berhasil mengembalikan objek JSON yang berisi bidang-bidang berikut:

  • access_token - Token akses untuk pengguna. Nilai ini harus dijaga agar tetap aman.
  • expires_in - Jumlah detik yang tersisa, dari saat diminta, sebelum token berakhir.

Akses pesan kesalahan token

Jika permintaan gagal, Anda menerima kesalahan dalam bentuk Kode Status HTTP. Untuk informasi lebih lanjut tentang kesalahan ini dan cara mencegahnya, lihat Referensi Otorisasi .

Buat permintaan yang diautentikasi

Setelah suatu produk memperoleh token akses, ia mengirimkan token tersebut ke Nest API di header otorisasi HTTP. Dimungkinkan untuk mengirim token sebagai parameter string-string URI, tetapi kami tidak merekomendasikannya, karena parameter URI dapat berakhir di file log yang tidak sepenuhnya aman.

Token akses hanya valid untuk sekumpulan operasi dan sumber daya yang dijelaskan dalam lingkup permintaan token. Misalnya, jika token akses dikeluarkan untuk Nest Thermostat API, itu tidak memberikan akses ke Nest Camera API.

Contoh kode (baca / tulis)

Contoh tukang pos (baca / tulis)

Tukang pos menyediakan cara mudah untuk menguji panggilan API menggunakan Content-Type = application/json .

DAPATKAN membaca data

Token tidak valid

Jika Anda membuat panggilan API menggunakan token yang tidak valid, Anda menerima 401 respons tidak sah kembali dari server. Token bisa tidak valid dan membutuhkan regenerasi karena:

  • Sudah kedaluwarsa
  • Pengguna telah mencabut izin yang awalnya mereka berikan untuk produk Anda

Penting bagi Anda untuk membuat kode produk Anda agar dapat menangani kesalahan 401 Tidak Sah dengan mengarahkan pengguna kembali ke awal alur kerja otorisasi.

Bekerja dengan koneksi Nest ditutup

Jika pengguna menghapus koneksi Works with Nest , produk Anda menerima acara auth_revoked dan koneksi ditutup.