A API Nest usa o protocolo OAuth 2.0 para autenticação e autorização.
Antes que seu produto possa acessar dados privados usando a API Nest, ele deve obter um token de acesso que conceda acesso a essa API. Um único token de acesso pode conceder vários graus de acesso a várias seções da API.
A sequência de autorização começa quando seu produto redireciona um navegador para um URL Nest com parâmetros de consulta indicando o acesso solicitado. A Nest trata da autenticação do usuário, seleção de sessão e consentimento do usuário. O resultado é um código de autorização, que seu produto pode trocar por um token de acesso. Seu produto pode então usar o token de acesso para fazer chamadas para a API Nest.
Configure seu cliente Works with Nest
Para encontrar as credenciais do OAuth 2.0 para seu cliente, verifique a guia Visão geral da página do cliente.
Redirecionar autorização baseada em URI ou PIN?
Ao configurar seu cliente, você é solicitado a inserir um URI de redirecionamento ou deixar os campos de URI de redirecionamento em branco para usar a autorização baseada em PIN.
Se o seu produto for um dispositivo que não possui um aplicativo ou página da web associada (por exemplo, um rastreador de fitness, um aparelho ou um painel de segurança), deixe os campos URI de redirecionamento em branco.
Se o seu produto tiver um componente de navegador, a prática recomendada é incluir um URI de redirecionamento.
Solicitar permissões
A configuração do cliente inclui um conjunto de permissões (também chamado de escopos). Uma permissão é um parâmetro variável que controla o conjunto de recursos e operações que um token de acesso permite. Geralmente, é uma prática recomendada solicitar permissões de forma incremental, no momento em que o acesso é necessário, e não antecipadamente.
Resultado
Quando você salva a configuração, seu cliente recebe uma ID de cliente e um segredo de cliente exclusivos. Além disso, seu cliente recebe um URL de autorização.
A URL de autorização inclui um parâmetro de estado que você pode usar para testar possíveis ataques de falsificação de solicitação entre sites (CSRF). Consulte Teste de ataques CSRF .
Solicite um código de autorização
Depois que seu cliente for configurado, você pode solicitar um código de autorização (às vezes chamado de código PIN). O código de autorização não é o token final que você usa para fazer chamadas para a Nest. Ele é usado na próxima etapa do fluxo OAuth 2.0 para trocar por um token de acesso real. Esta etapa fornece garantia diretamente da Nest para o usuário de que a permissão está sendo concedida ao produto correto, com o acesso acordado.
A experiência do usuário
Apresentamos uma página Works with Nest que pede ao usuário para conceder acesso ao seu produto. Isso identifica seu produto e descreve as permissões de usuário específicas (escopos) que seu produto solicitou. As palavras na tela vêm da configuração do seu cliente.
Para testar você mesmo, carregue o URL de autorização da Etapa 1 em um navegador. Você deverá ver uma página de solicitação de acesso Works with Nest:
Vá em frente e clique em [ACEITAR] para ver o que o usuário vê. Ao clicar no botão [ACEITAR], o usuário está aprovando a solicitação do seu produto para acessar seus dados.
Experiência de PIN
Se você deixar os campos Redirect URI em branco na configuração do cliente, o usuário será redirecionado para uma página Nest que exibe um PIN (código de autorização). A IU do dispositivo deve então solicitar que o usuário insira o PIN manualmente.
Experiência de redirecionamento de URI
Se você incluir um URI de redirecionamento na configuração do cliente, o usuário será redirecionado para uma página em sua nuvem (ou localhost) e o Nest enviará automaticamente o código de autorização ao dispositivo do usuário.
Teste para ataques CSRF
Antes de aceitar o código de autorização, seu produto deve garantir que o valor retornado no parâmetro de estado corresponda ao valor de estado de sua solicitação de autorização original. Isso garante que você esteja lidando com o usuário real e não com um script malicioso. Se os valores de estado não corresponderem, você deve lançar um código de erro HTTP não autorizado 401 em resposta.
Um ataque CSRF é um ataque que força um usuário final a executar ações indesejadas em um aplicativo da web no qual está autenticado no momento.
Para ajudar a prevenir ataques de CSRF, recomendamos que você sempre envie um state suspeito ao solicitar autorização.
Dessa forma, sua integração com o Works with Nest pode verificar se os códigos de acesso obtidos na nuvem Nest atendem às solicitações feitas por seu produto, e não por algum outro produto.
Exemplo:
Digamos que na configuração do seu cliente você especifique o URI de redirecionamento:
http://localhost:5000/callback
Digamos também que seu cliente envie o estado 7tvPJiv8StrAqo9IQE9xsJaDso4 no URL de autorização:
https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
O usuário concorda com a solicitação.
A nuvem Nest retorna o parâmetro de estado como parte do URI de redirecionamento:
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 esse valor de 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 adivinhado. Você pode fornecer valores de estado aleatórios de um dicionário mantido na memória ou um valor recomputável. Você pode usar uma chave privada com algumas variáveis facilmente verificáveis - por exemplo, o ID do cliente e um cookie de sessão - para calcular um valor hash. Isso resulta em um valor de byte difícil de adivinhar sem a chave privada. Outra sugestão é fazer um hash da data e hora atuais. Com essa abordagem, seu aplicativo deve economizar o tempo de transmissão para verificá-lo ou permitir um período variável de validade (por exemplo, usando o algoritmo de senha única baseada em tempo [TOTP]).
Depois de calcular o código de autenticação de mensagem hash com chave (HMAC), codifique-o na base 64 e passe-o para a nuvem Nest como um parâmetro de estado.
Aqui está um exemplo de 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 de código de autorização
Se a solicitação do código de autorização falhar, os usuários verão uma mensagem de erro. Para obter mais informações sobre essas mensagens e como evitá-las, consulte a Referência de Autorização .
Código de autorização de troca por um token de acesso
A etapa final para obter um token de acesso é seu produto solicitar um usando o código de autorização que acabou de adquirir. Isso é feito fazendo uma solicitação HTTP POST "x-www-form-urlencoded".
Inclua os parâmetros abaixo na solicitação. Todos os quatro parâmetros são obrigatórios.
| Parâmetro | Descrição |
|---|---|
| ID do Cliente | O ID do cliente na etapa 1 |
| client_secret | O segredo do cliente na etapa 1 |
| código | O código de autorização recebido na Etapa 2 |
| grant_type | O valor deste campo deve ser sempre: authorization_code |
Antes de cada chamada POST, obtenha um novo código de autorização. Para fazer isso, recarregue seu URL de autorização. Em seguida, altere o parâmetro de code do POST para incluir o novo código de autorização.
Exemplos de código (autenticação)
Veja exemplos em vários idiomas .
Exemplo de carteiro (auth)
O Postman oferece uma maneira fácil de testar solicitações OAuth.
Na guia Cabeçalhos , certifique-se de Content-Type = application/x-www-form-urlencoded .
Na guia Corpo , inclua a seguinte chave: pares de valor. 
Resposta de token de acesso
Uma solicitação bem-sucedida retorna um objeto 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, desde o momento em que foi solicitado, antes que o token expire.
Mensagens de erro de token de acesso
Se a solicitação falhar, você receberá um erro na forma de um Código de status HTTP. Para obter mais informações sobre esses erros e como evitá-los, consulte a Referência de autorização .
Faça solicitações autenticadas
Depois que 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 tokens como parâmetros de string de consulta de URI, mas não recomendamos, porque os parâmetros de URI podem acabar em arquivos de log que não são completamente seguros.
Os tokens de acesso são válidos apenas para o conjunto de operações e recursos descritos no escopo da solicitação de token. Por exemplo, se um token de acesso for emitido para a API Nest Thermostat, ele não concederá acesso à API Nest Camera.
Exemplos de código (leitura / gravação)
Exemplo de carteiro (leitura / gravação)
Postman oferece uma maneira fácil de testar chamadas de API usando Content-Type = application/json .
Tokens inválidos
Se você fizer uma chamada de API usando um token inválido, receberá uma resposta 401 Não Autorizada do servidor. Um token pode ser inválido e precisar de regeneração porque:
- Expirou
- O usuário revogou a permissão concedida inicialmente ao seu produto
É importante que você codifique seu produto para lidar adequadamente com um erro 401 não autorizado, redirecionando o usuário de volta ao início do fluxo de trabalho de autorização.
Funciona com conexão Nest fechada
Se um usuário remover uma conexão Works with Nest , seu produto receberá um evento auth_revoked e a conexão será fechada.