A API ninho utiliza o protocolo OAuth 2.0 para autenticação e autorização.
Antes de seu produto pode acessar dados privados usando a API do ninho, ele deve obter um token de acesso que concede acesso a essa API. Um token de acesso único pode conceder diferentes graus de acesso a várias seções da API.
A seqüência autorização começa quando o seu produto redireciona o navegador para uma URL Ninho com parâmetros de consulta indicando o acesso solicitado. alças ninho da autenticação de usuário, seleção sessão e consentimento do usuário. O resultado é um código de autorização, o que seu produto pode trocar por um token de acesso. O seu produto pode então usar o token de acesso para fazer chamadas para a API Nest.
Configure suas obras com o cliente Nest
Para encontrar as credenciais OAuth 2.0 para o seu cliente, verifique a guia Visão geral da página do cliente.
autorização de redirecionamento URI ou PIN-base?
Quando você estiver configurando o seu cliente, você será solicitado a inserir um redirecionamento URI ou deixar o redirecionamento URI campos em branco para usar a autorização baseada em PIN.
Se o seu produto é um dispositivo que não tem um aplicativo associado ou página da web (por exemplo, um rastreador de fitness, um aparelho ou um painel de segurança), deixe o Redirect URI campos em branco.
Se o seu produto tem um componente de navegador, a melhor prática é incluir um redirecionamento URI.
solicitar permissões
A configuração do cliente inclui um conjunto de permissões (também chamados de escopos). A permissão é um parâmetro variável que controla o conjunto de recursos e operações que um acesso licenças de tokens. Em geral, é uma boa prática para solicitar permissões de forma incremental, ao tempo de acesso é necessária, em vez de na frente.
Resultado
Quando você salvar a configuração, o cliente é atribuído um ID do cliente única e cliente secreto. Além disso, seu cliente é atribuído um URL de autorização.
O URL de autorização inclui um parâmetro de estado que você pode usar para testar a possível cross-site request forgery ataques (CSRF). Veja Teste de ataques CSRF .
Solicitar um código de autorização
Após o seu cliente está configurado, você pode solicitar um código de autorização (por vezes chamado de um código PIN). O código de autorização não é o sinal final que você usa para fazer chamadas para Nest. É utilizado no passo seguinte do fluxo OAuth 2,0 a troca de um símbolo de acesso real. Esta etapa fornece uma garantia diretamente do ninho para o usuário que a permissão está sendo concedida para o produto correto, com o acesso acordados.
A experiência do usuário
Nós apresentamos um Works com a página Nest que pede ao usuário para conceder acesso ao seu produto. Isso identifica o seu produto e descreve os particulares permissões de usuário (escopos) que seu produto tenha solicitado. As palavras na tela vir de sua configuração do cliente.
Para testar isso mesmo, carregar a URL autorização do Passo 1 em um navegador. Você deverá ver uma Funciona com página de solicitação de acesso Nest:
Vá em frente e clique em [Aceitar]-se para ver o que o usuário vê. Ao clicar no botão [ACEITAR], o usuário é aprovar o pedido do seu produto para acessar seus dados.
experiência PIN
Se você deixar o Redirect URI campos em branco na configuração do seu cliente, o usuário é redirecionado para uma página Nest que exibe um PIN (código de autorização). O dispositivo de interface do usuário deve então solicitar que o usuário digite o PIN manualmente.
experiência Redirect URI
Se você incluir um redirecionamento URI em sua configuração do cliente, o usuário é redirecionado para uma página em sua nuvem (ou localhost) e Nest envia automaticamente o código de autorização para o dispositivo do usuário.
Teste para ataques CSRF
Antes de aceitar o código de autorização, o produto deve assegurar que o valor retornado no parâmetro estado corresponde ao valor de estado do seu pedido autorização original. Isso garante que você está lidando com o usuário real e não um script malicioso. Se os valores de estado não coincidirem, você deve lançar um código de erro 401 não autorizado HTTP em resposta.
A CSRF ataque é um ataque que o usuário forças fim de executar ações indesejadas em uma aplicação web em que está autenticado atualmente.
Para ajudar a ataques prevent CSRF, recomendamos que você sempre enviar uma nonguessable state quando solicitando autorização.
Desta forma, seus trabalhos com a integração Nest pode verificar que os códigos de acesso obtidos a partir da nuvem Nest são em resposta a solicitações feitas por seu produto, e não algum outro produto.
Exemplo:
Vamos dizer na sua configuração do cliente, você especificar o redirecionamento URI:
http://localhost:5000/callback
Vamos também dizer que seu cliente envia o 7tvPJiv8StrAqo9IQE9xsJaDso4 Estado na URL de autorização:
https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
O usuário consente ao pedido.
A nuvem Nest retorna o parâmetro de estado como parte do redirecionamento 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 -
Seu produto recebe este valor estado e deve ser programado para aceitar apenas redirecionamentos com um estado verificável.
Existem várias maneiras de gerar um parâmetro de estado não-guessable. Você pode fornecer valores de estado randomizados de um dicionário mantido na memória ou um valor recomputable. Você pode usar uma chave privada com alguns facilmente verificáveis variáveis, por exemplo, o ID do cliente e uma sessão de cookie-para calcular um valor hash. Isso resulta em um valor de byte que é difícil de adivinhar sem a chave privada. Outra sugestão é para hash a data e hora atual. Com esta abordagem, a aplicação tem de economizar o tempo de transmissão para verificar-lo ou permitir um período deslizante de validade (por exemplo, usando a senha algoritmo baseado em tempo One-Time [TOTP]).
Depois de calcular o código chaveado-hash de autenticação de mensagem (HMAC), base 64 codificam lo e passá-lo para a nuvem de ninho como um parâmetro de estado.
Aqui está um exemplo Python que usa 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)
mensagens de erro código de autorização
Se o pedido do código de autorização falhar, os usuários verão uma mensagem de erro. Para mais informações sobre essas mensagens e como evitá-los, consulte a Referência de Autorização .
código de autorização troca de um token de acesso
O passo final na obtenção de um token de acesso é para o seu produto para pedir um usando o código de autorização que acaba de adquirir. Isto é feito, fazendo uma solicitação POST "x-www-form-urlencoded" HTTP.
Inclua os parâmetros abaixo na solicitação. Todos os quatro parâmetros são necessários.
| Parâmetro | Descrição |
|---|---|
| ID do Cliente | O ID do cliente na etapa 1 |
| client_secret | O segredo do cliente no Passo 1 |
| código | O código de autorização recebida no Passo 2 |
| grant_type | O valor deste campo deve ser sempre: authorization_code |
Antes de cada chamada POST, obter um novo código de autorização. Para fazer isso, recarregue o URL de autorização. Em seguida, altere o POST code parâmetro para incluir o novo código de autorização.
exemplos de código (auth)
Veja exemplos em vários idiomas .
exemplo carteiro (auth)
Postman fornece uma maneira fácil de solicitações de teste OAuth.
Na guia cabeçalhos, certifique-Content-Type = application/x-www-form-urlencoded .
Na guia Corpo, incluem a seguinte chave: valor pares. 
resposta token de acesso
Um pedido bem sucedido devolve um objecto JSON contendo os seguintes campos:
-
access_token- O token de acesso para o usuário. Este valor deve ser mantido seguro. -
expires_in- O número de segundos restantes, a partir do momento em que foi solicitada, antes de o token expirar.
Token de acesso mensagens de erro
Se a solicitação falhar, você receberá um erro na forma de um HTTP Status Código. Para mais informações sobre esses erros e como evitá-los, consulte a Referência de Autorização .
Fazer solicitações autenticadas
Depois de um produto obtém um token de acesso, ele envia o token para uma API Nest em um cabeçalho de autorização HTTP. É possível enviar fichas como parâmetros de consulta cordas URI, mas não recomendamos-lo, porque URI parâmetros pode acabar em arquivos de log que não são seguras completamente.
Os tokens de acesso só são válidas para o conjunto de operações e recursos descritos no âmbito do pedido de token. Por exemplo, se um token de acesso é emitido para o Nest Thermostat API, ele não concede acesso à API Nest Camera.
exemplos de código (leitura / gravação)
exemplo Postman (leitura / gravação)
Postman fornece uma maneira fácil de chamadas de teste API usando Content-Type = application/json .
fichas inválidos
Se você fizer uma chamada de API usando um token inválido, você receberá um 401 Unauthorized volta resposta do servidor. Um token pode ser inválido e na necessidade de regeneração, porque:
- Ele expirou
- O usuário revogou a permissão que inicialmente concedido ao seu produto
É importante que você codificar seu produto para lidar correctamente com um erro não autorizado 401, redirecionando as costas do usuário para o início do fluxo de trabalho de autorização.
Funciona com conexão ninho fechado
Se um usuário remove um Works com conexão Nest , seu produto recebe um auth_revoked evento e as fecha a conexão.