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.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Autenticazione e autorizzazione OAuth 2.0

L'API Nest utilizza il protocollo OAuth 2.0 per l'autenticazione e l'autorizzazione.

Prima che il tuo prodotto possa accedere ai dati privati ​​utilizzando l'API Nest, deve ottenere un token di accesso che conceda l'accesso a tale API. Un singolo token di accesso può garantire vari gradi di accesso a più sezioni dell'API.

La sequenza di autorizzazione inizia quando il prodotto reindirizza un browser a un URL Nest con parametri di query che indicano l'accesso richiesto. Nest gestisce l'autenticazione dell'utente, la selezione della sessione e il consenso dell'utente. Il risultato è un codice di autorizzazione che il prodotto può scambiare con un token di accesso. Il prodotto può quindi utilizzare il token di accesso per effettuare chiamate all'API Nest.

Flusso OAuth 2.0
Flusso OAuth 2.0

Configura il tuo Works con il client Nest

Per trovare le credenziali di OAuth 2.0 per il tuo client, controlla la scheda Panoramica della pagina del client.

Reindirizzare l'autorizzazione basata su URI o PIN?

Quando si configura il client, viene richiesto di immettere un URI di reindirizzamento o di lasciare vuoti i campi dell'URI di reindirizzamento per utilizzare l'autorizzazione basata su PIN.

Se il tuo prodotto è un dispositivo a cui non è associata un'app o una pagina Web (ad esempio un fitness tracker, un'appliance o un pannello di sicurezza), lascia vuoti i campi URI di reindirizzamento.

Se il tuo prodotto ha un componente browser, è consigliabile includere un URI di reindirizzamento.

Richiedi autorizzazioni

La configurazione del client include una serie di autorizzazioni (chiamate anche ambiti). Un'autorizzazione è un parametro variabile che controlla l'insieme di risorse e operazioni consentite da un token di accesso. In genere, è consigliabile richiedere le autorizzazioni in modo incrementale, al momento dell'accesso, anziché in anticipo.

Risultato

Quando si salva la configurazione, al proprio client vengono assegnati un ID client e un segreto client univoci. Inoltre, al tuo cliente viene assegnato un URL di autorizzazione.

L'URL di autorizzazione include un parametro di stato che è possibile utilizzare per verificare eventuali attacchi di contraffazione di richieste tra siti (CSRF). Vedi Test per attacchi CSRF .

Dettagli OAuth

Richiedi un codice di autorizzazione

Dopo aver configurato il client, è possibile richiedere un codice di autorizzazione (a volte chiamato codice PIN). Il codice di autorizzazione non è il token finale utilizzato per effettuare chiamate a Nest. Viene utilizzato nel passaggio successivo del flusso OAuth 2.0 per lo scambio con un token di accesso effettivo. Questo passaggio fornisce la garanzia direttamente da Nest all'utente che l'autorizzazione viene concessa al prodotto corretto, con l'accesso concordato.

L'esperienza dell'utente

Presentiamo una pagina di Works with Nest che chiede all'utente di concedere l'accesso al tuo prodotto. Questo identifica il tuo prodotto e delinea le autorizzazioni utente specifiche (ambiti) che il tuo prodotto ha richiesto. Le parole sullo schermo provengono dalla configurazione del client.

Per testarlo tu stesso, carica l'URL di autorizzazione dal passaggio 1 in un browser. Dovresti vedere una pagina di richiesta di accesso di Works con Nest:

Funziona con Nest

Vai avanti e fai clic su [ACCETTA] per vedere cosa vede l'utente. Facendo clic sul pulsante [ACCETTA], l'utente sta approvando la richiesta del prodotto di accedere ai propri dati.

Esperienza PIN

Se si lasciano vuoti i campi URI di reindirizzamento nella configurazione del client, l'utente viene reindirizzato a una pagina Nest che visualizza un PIN (codice di autorizzazione). L'interfaccia utente del dispositivo dovrebbe quindi richiedere all'utente di inserire il PIN manualmente.

Codice PIN

Reindirizza esperienza URI

Se includi un URI di reindirizzamento nella configurazione del tuo client, l'utente viene reindirizzato a una pagina nel tuo cloud (o localhost) e Nest invia automaticamente il codice di autorizzazione al dispositivo dell'utente.

Test per attacchi CSRF

Prima di accettare il codice di autorizzazione, il prodotto deve assicurarsi che il valore restituito nel parametro state corrisponda al valore dello stato dalla richiesta di autorizzazione originale. Questo assicura che tu abbia a che fare con l'utente reale e non con uno script dannoso. Se i valori dello stato non corrispondono, è necessario inviare un codice di errore HTTP non autorizzato 401 in risposta.

Un attacco CSRF è un attacco che costringe un utente finale ad eseguire azioni indesiderate su un'applicazione Web in cui è attualmente autenticato.

Attacco CSRF
Attacco CSRF

Per aiutare a prevenire gli attacchi CSRF, si consiglia di inviare sempre uno state indovinabile quando si richiede l'autorizzazione.

In questo modo, l'integrazione di Works with Nest può verificare che i codici di accesso ottenuti dal cloud Nest rispondano alle richieste fatte dal prodotto, non da altri prodotti.

Esempio:

Diciamo nella configurazione del tuo client, specifichi l'URI di reindirizzamento:

 http://localhost:5000/callback
 

Supponiamo inoltre che il tuo client invii lo stato 7tvPJiv8StrAqo9IQE9xsJaDso4 nell'URL di autorizzazione:

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

L'utente acconsente alla richiesta.

Il cloud Nest restituisce il parametro state come parte dell'URI di reindirizzamento:

 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 -
 

Il prodotto riceve questo valore di stato e deve essere programmato per accettare reindirizzamenti solo con uno stato verificabile.

Esistono diversi modi per generare un parametro di stato non indovinabile. È possibile fornire valori di stato randomizzati da un dizionario tenuto in memoria o da un valore calcolabile. È possibile utilizzare una chiave privata con alcune variabili facilmente verificabili, ad esempio l'ID client e un cookie di sessione, per calcolare un valore con hash. Ciò si traduce in un valore in byte difficile da indovinare senza la chiave privata. Un altro suggerimento è di eseguire l'hashing della data e dell'ora correnti. Con questo approccio, l'applicazione deve risparmiare il tempo di trasmissione per verificarlo o consentire un periodo di validità scorrevole (ad esempio, utilizzando l'algoritmo One-Time Password [TOTP] basato sul tempo).

Dopo aver calcolato il codice di autenticazione del messaggio con hash con chiave (HMAC), base-64 lo codifica e lo passa al cloud Nest come parametro di stato.

Ecco un esempio di Python che utilizza 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)
 

Messaggi di errore del codice di autorizzazione

Se la richiesta del codice di autorizzazione non riesce, gli utenti visualizzano un messaggio di errore. Per ulteriori informazioni su questi messaggi e su come prevenirli, consultare il riferimento all'autorizzazione.

Scambiare il codice di autorizzazione per un token di accesso

Il passaggio finale per ottenere un token di accesso è che il prodotto ne richieda uno utilizzando il codice di autorizzazione appena acquisito. Questo viene fatto inviando una richiesta POST HTTP "x-www-form-urlencoded".

Includi i parametri seguenti nella richiesta. Sono richiesti tutti e quattro i parametri.

Parametro Descrizione
Identificativo cliente L'ID client al passaggio 1
client_secret Il segreto del cliente al passaggio 1
codice Il codice di autorizzazione ricevuto nel passaggio 2
grant_type Il valore di questo campo deve essere sempre: authorization_code

Prima di ogni chiamata POST, ottenere un nuovo codice di autorizzazione. Per fare ciò, ricaricare l'URL di autorizzazione. Quindi modificare il parametro del code POST per includere il nuovo codice di autorizzazione.

Esempi di codice (auth)

Vedi esempi in varie lingue .

Esempio di postino (auth)

Postman offre un modo semplice per testare le richieste OAuth.

Nella scheda Intestazioni , assicurati che Content-Type = application/x-www-form-urlencoded .

Intestazione POST per ottenere il token di accesso

Nella scheda Corpo , includere la seguente chiave: coppie di valori.

Corpo POST per ottenere il token di accesso

Risposta token di accesso

Una richiesta riuscita restituisce un oggetto JSON contenente i seguenti campi:

  • access_token - Il token di accesso per l'utente. Questo valore deve essere protetto.
  • expires_in - Il numero di secondi rimanenti, dal momento in cui è stato richiesto, prima della scadenza del token.

Messaggi di errore del token di accesso

Se la richiesta fallisce, si riceve un errore sotto forma di un codice di stato HTTP. Per ulteriori informazioni su questi errori e su come prevenirli, consultare il riferimento all'autorizzazione.

Invia richieste autenticate

Dopo aver ottenuto un token di accesso, un prodotto invia il token a un'API Nest in un'intestazione di autorizzazione HTTP. È possibile inviare token come parametri della stringa di query URI, ma non è consigliabile, poiché i parametri URI possono finire in file di registro non completamente sicuri.

I token di accesso sono validi solo per l'insieme di operazioni e risorse descritte nell'ambito della richiesta token. Ad esempio, se viene emesso un token di accesso per l'API Nest Thermostat, non consente l'accesso all'API Nest Camera.

Esempi di codice (lettura / scrittura)

Esempio di postino (lettura / scrittura)

Postman offre un modo semplice per testare le chiamate API usando Content-Type = application/json .

OTTIENI per leggere i dati

Token non validi

Se si effettua una chiamata API utilizzando un token non valido, si riceve una risposta 401 non autorizzata dal server. Un token potrebbe non essere valido e necessita di rigenerazione perché:

  • È scaduto
  • L'utente ha revocato l'autorizzazione inizialmente concessa al prodotto

È importante codificare il prodotto per gestire correttamente un errore 401 non autorizzato reindirizzando l'utente all'inizio del flusso di lavoro di autorizzazione.

Funziona con la connessione Nest chiusa

Se un utente rimuove una connessione di Works con Nest , il prodotto riceve un evento auth_revoked e la connessione si chiude.