OAuth 2.0 Kimlik Doğrulaması ve Yetkilendirme
Nest API, kimlik doğrulama ve yetkilendirme için OAuth 2.0 protokolünü kullanır.
Ürününüzün Nest API kullanarak özel verilere erişebilmesi için, söz konusu API'ya erişim izni veren bir erişim belirteci edinmesi gerekir. Tek bir erişim belirteci, API'nın birden çok bölümüne değişen derecelerde erişim sağlayabilir.
Yetkilendirme sırası, ürününüz bir tarayıcıyı istenen erişimi gösteren sorgu parametreleriyle bir Nest URL'sine yönlendirdiğinde başlar. Nest, kullanıcı kimlik doğrulamasını, oturum seçimini ve kullanıcı onayını işler. Sonuç, ürününüzün bir erişim belirteci ile değiş tokuş edebileceği bir yetkilendirme kodudur. Ürününüz daha sonra Nest API'yı aramak için erişim belirtecini kullanabilir.
OAuth 2.0 akışı
Works ile Nest istemcisini yapılandırma
İstemcinizin OAuth 2.0 kimlik bilgilerini bulmak için istemci sayfasının Genel Bakış sekmesine bakın.
URI veya PIN tabanlı yetkilendirme yeniden yönlendirilsin mi?
İstemcinizi yapılandırırken, PIN tabanlı yetkilendirmeyi kullanmak için bir yönlendirme URI'sı girmeniz veya yönlendirme URI alanlarını boş bırakmanız istenir.
Ürününüz, ilişkili bir uygulaması veya web sayfası olmayan bir cihazsa (örneğin, bir fitness takip cihazı, cihaz veya güvenlik paneli), Yönlendirme URI alanlarını boş bırakın.
Ürününüzün bir tarayıcı bileşeni varsa, en iyi uygulama bir yönlendirme URI'sı eklemektir.
İstemci yapılandırması bir dizi izin içerir (kapsamlar olarak da adlandırılır). İzin, bir erişim belirtecinin izin verdiği kaynakları ve işlemleri kümesini denetleyen değişken bir parametredir. Genellikle, erişim gerektiğinde, ön tarafa değil, kademeli olarak izin istemek en iyi uygulamadır.
Yapılandırmayı kaydettiğinizde, istemcinize benzersiz bir İstemci Kimliği ve İstemci Sırrı atanır. Ayrıca, müşterinize bir yetkilendirme URL'si atanır.
Yetkilendirme URL'si, olası siteler arası istek sahtekarlığı (CSRF) saldırılarını test etmek için kullanabileceğiniz bir durum parametresi içerir. Bkz. CSRF saldırılarını test etme .
Yetkilendirme kodu isteyin
İstemciniz yapılandırıldıktan sonra bir yetkilendirme kodu isteyebilirsiniz (bazen PIN kodu da denir). Yetkilendirme kodu, Nest'i aramak için kullandığınız son simge değildir. OAuth 2.0 akışının bir sonraki adımında, gerçek bir erişim belirtecini değiştirmek için kullanılır. Bu adım, doğrudan Nest'ten kullanıcıya, üzerinde anlaşılan erişimle doğru ürüne izin verildiğini garanti eder.
Kullanıcıdan ürününüze erişim izni vermesini isteyen bir Nest with Works sayfası sunuyoruz. Bu, ürününüzü tanımlar ve ürününüzün istediği belirli kullanıcı izinlerini (kapsamları) açıklar. Ekrandaki kelimeler istemci yapılandırmanızdan gelir.
Bunu kendiniz test etmek için 1. Adımdaki yetkilendirme URL'sini bir tarayıcıya yükleyin. Nest ile Erişim erişim isteği sayfası görmelisiniz:
Kullanıcının gördüklerini görmek için devam edin ve [KABUL ET] öğesine tıklayın. [KABUL ET] düğmesini tıklayarak kullanıcı, ürününüzün verilerine erişme talebini onaylar.
İstemci yapılandırmanızda Yönlendirme URI alanlarını boş bırakırsanız kullanıcı, PIN (yetkilendirme kodu) görüntüleyen bir Yuva sayfasına yönlendirilir. Ardından cihaz kullanıcı arayüzünüz kullanıcıdan PIN kodunu manuel olarak girmesini istemelidir.
URI deneyimini yeniden yönlendir
İstemci yapılandırmanıza bir yönlendirme URI'sı eklerseniz, kullanıcı bulutunuzdaki (veya localhost) bir sayfaya yönlendirilir ve Nest, yetkilendirme kodunu kullanıcının cihazına otomatik olarak gönderir.
CSRF saldırılarını test edin
Yetkilendirme kodunu kabul etmeden önce ürününüz, state parametresinde döndürülen değerin, orijinal yetkilendirme isteğinizdeki durum değeriyle eşleştiğinden emin olmalıdır. Bu, kötü amaçlı bir komut dosyasıyla değil, gerçek kullanıcıyla ilgilenmenizi sağlar. Durum değerleri uyuşmuyorsa, yanıt olarak 401 Yetkisiz HTTP hata kodu atamalısınız.
CSRF saldırısı, son kullanıcıyı şu anda kimliği doğrulanmış oldukları bir web uygulamasında istenmeyen eylemler yürütmeye zorlayan bir saldırıdır.
CSRF saldırılarını önlemeye yardımcı olmak için, yetkilendirme isterken her zaman tahmin edilemeyen bir state göndermenizi öneririz.
Bu şekilde Nest with Works entegrasyonunuz, Nest bulutundan elde edilen erişim kodlarının, başka bir ürüne değil, ürününüz tarafından yapılan isteklere yanıt olduğunu doğrulayabilir.
Diyelim ki istemci yapılandırmanızda, yönlendirme URI'sını belirtiyorsunuz:
Diyelim ki müşteriniz yetkilendirme URL'sinde 7tvPJiv8StrAqo9IQE9xsJaDso4 durumunu gönderdi:
Kullanıcı isteği kabul eder.
Nest bulutu, yönlendirme URI'sının bir parçası olarak state parametresini döndürür:
Ürününüz bu durum değerini alır ve yalnızca doğrulanabilir durumdaki yönlendirmeleri kabul edecek şekilde programlanmalıdır.
Not: Birden fazla yönlendirme URI'si kullanıyorsanız, tüm yönlendirme URI'lerinde aynı durum parametresini kullanmayın. Artan güvenlik için devleti değiştirin.
Tahmin edilemeyen bir durum parametresi oluşturmanın birden çok yolu vardır. Bellekte tutulan bir sözlükten veya yeniden hesaplanabilir bir değerden rastgele durum değerleri sağlayabilirsiniz. Karma değeri hesaplamak için kolayca doğrulanabilir bazı değişkenlerle (örneğin, istemci kimliği ve oturum çerezi) özel bir anahtar kullanabilirsiniz. Bu, özel anahtar olmadan tahmin edilmesi zor bir bayt değeri ile sonuçlanır. Başka bir öneri, geçerli tarih ve saati hash etmektir. Bu yaklaşımla, uygulamanızın iletimi doğrulamak veya aktarma süresinin geçmesine izin vermek için iletim zamanından tasarruf etmesi gerekir (örneğin, Zamana Dayalı Tek Kullanımlık Şifre algoritmasını [TOTP] kullanarak).
Anahtarlı karma mesaj kimlik doğrulama kodunu (HMAC) hesapladıktan sonra, base-64 kodu kodlar ve bir durum parametresi olarak Nest bulutuna iletir.
datetime kullanan bir Python örneği:
Yetkilendirme kodu hata mesajları
Yetkilendirme kodu isteği başarısız olursa, kullanıcılar bir hata mesajı görür. Bu mesajlar ve bunların nasıl önleneceği hakkında daha fazla bilgi için Yetkilendirme Referansı'na bakın .
Bir erişim belirteci için Exchange yetkilendirme kodu
Bir erişim belirteci edinmenin son adımı ürününüzün yeni aldığı yetkilendirme kodunu kullanarak bir tane istemesi içindir. Bu, "x-www-form-urlencocode" HTTP POST isteği yapılarak yapılır.
Aşağıdaki parametreleri isteğe ekleyin. Dört parametrenin hepsi gereklidir.
Müşteri Kimliği 1. Adımdaki İstemci Kimliği
client_secret Adım 1 İstemci Sırrı
kod 2. Adımda alınan yetkilendirme kodu
grant_type Bu alanın değeri her zaman şöyle olmalıdır: authorization_code
Önemli Nokta: Yetkilendirme kodunuz bir POST çağrısı için geçerlidir.
Her POST çağrısından önce yeni bir yetkilendirme kodu alın. Bunu yapmak için yetkilendirme URL'nizi yeniden yükleyin. Ardından, POST code parametresini yeni yetkilendirme kodunu içerecek şekilde değiştirin.
Kod örnekleri (auth)
Çeşitli dillerdeki örneklere bakın .
Postacı örneği (auth)
Postacı, OAuth isteklerini test etmek için kolay bir yol sağlar.
Üstbilgiler sekmesinde, Content-Type = application/x-www-form-urlencoded olduğundan emin olun.
Gövde sekmesinde şu anahtarı ekleyin: değer çiftleri.
Erişim belirteci yanıtı
Başarılı bir istek, aşağıdaki alanları içeren bir JSON nesnesi döndürür:
access_token - Kullanıcı için erişim belirteci. Bu değer güvenli tutulmalıdır.
expires_in - Jetonun süresi dolmadan önce, istendiği zamandan kalan saniye sayısı.
Erişim belirteci hata iletileri
İstek başarısız olursa, HTTP Durum Kodu şeklinde bir hata alırsınız. Bu hatalar ve bunların nasıl önleneceği hakkında daha fazla bilgi için Yetkilendirme Referansı'na bakın .
Kimliği doğrulanmış isteklerde bulunma
Bir ürün bir erişim belirteci edindikten sonra, simgeyi bir HTTP yetkilendirme başlığında bir Nest API'ye gönderir. Belirteçleri URI sorgu dizesi parametreleri olarak göndermek mümkündür, ancak bunu önermiyoruz, çünkü URI parametreleri tamamen güvenli olmayan günlük dosyalarına girebilir.
Erişim belirteçleri, yalnızca belirteç isteği kapsamında açıklanan işlemler ve kaynaklar kümesi için geçerlidir. Örneğin, Nest Thermostat API'sı için bir erişim belirteci verilirse, Nest Camera API'sına erişim izni vermez.
Kod örnekleri (okuma / yazma)
API okuma kodu örnekleri
API yazma kodu örnekleri
Postacı örneği (okuma / yazma)
Postacı, Content-Type = application/json kullanarak API çağrılarını test etmek için kolay bir yol sağlar.
Geçersiz bir belirteç kullanarak bir API çağrısı yaparsanız, sunucudan 401 Yetkisiz bir yanıt alırsınız. Bir jeton geçersiz olabilir ve yenilenmesi gerekebilir, çünkü:
Kullanıcı, ürününüze başlangıçta verdiği izni iptal etti
Kullanıcıyı yetkilendirme iş akışının başlangıcına yeniden yönlendirerek 401 Yetkisiz hatayı düzgün bir şekilde işlemek için ürününüzü kodlamanız önemlidir.
Nest bağlantısı kapalıyken çalışır
Bir kullanıcı Nest ile auth_revoked bağlantısını kaldırırsa, ürününüz bir auth_revoked olayı alır ve bağlantı kapanır.