A API Nest usa o protocolo OAuth 2.0 para autenticação e autorização.
Antes que seu produto possa acessar dados particulares usando a API Nest, ele precisa receber um token de acesso que conceda acesso a essa API. Um único token de acesso pode conceder diferentes graus de acesso a várias seções da API.
A sequência de autorização começa quando o produto redireciona um navegador para um URL do Nest com parâmetros de consulta que indicam o acesso solicitado. O Nest gerencia a autenticação, a seleção da sessão e o consentimento do usuário. O resultado é um código de autorização, que o produto pode trocar por um token de acesso. Seu produto poderá usar o token de acesso para fazer chamadas à API Nest.
Configurar o cliente Works with Nest
Para encontrar as credenciais do OAuth 2.0 de seu cliente, verifique a guia "Visão geral" da página do cliente.
Redirecionar o URI ou a autorização com base no PIN?
Ao configurar seu cliente, você precisa inserir um URI de redirecionamento ou deixar os campos do URI de redirecionamento em branco para usar a autorização baseada no PIN.
Se o produto for um dispositivo que não tem um app ou página da Web associada (por exemplo, um rastreador de condicionamento físico, um dispositivo ou um painel de segurança), deixe os campos de URI de redirecionamento em branco.
Se o produto tiver um componente do 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 chamadas de escopos. Uma permissão é um parâmetro de variável que controla o conjunto de recursos e operações permitidos por um token de acesso. Geralmente, é uma prática recomendada solicitar permissões gradualmente, no momento em que o acesso é necessário, e não antecipadamente.
Resultado
Quando você salva a configuração, seu cliente recebe um ID e uma chave secreta do cliente exclusivos. Além disso, o URL de autorização é atribuído ao seu cliente.
O URL de autorização inclui um parâmetro de estado que pode ser usado para testar possíveis ataques de falsificação de solicitação entre sites (CSRF). Consulte Testar ataques de CSRF.
Solicitar um código de autorização
Depois que o cliente estiver configurado, será possível 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 usado para fazer chamadas ao Nest. Ele é usado na próxima etapa do fluxo do OAuth 2.0 para trocar por um token de acesso real. Essa etapa fornece a garantia diretamente do usuário ao Nest que a permissão está sendo concedida ao produto correto com o acesso acordado.
A experiência do usuário
Apresentamos uma página do Works with Nest que solicita ao usuário acesso ao produto. Ele identifica o produto e descreve as permissões de usuário específicas (escopos) solicitadas pelo produto. As palavras na tela são provenientes da configuração do cliente.
Para testar por conta própria, carregue o URL de autorização da Etapa 1 em um navegador. Você verá uma página de solicitação de acesso Compatível com Nest:
Clique em [ACEITAR] para ver o que o usuário vê. Ao clicar no botão [ACEITAR], o usuário aprova a solicitação do seu produto para acessar os dados dele.
Experiência com o PIN
Se você deixar os campos de URI de redirecionamento em branco na configuração do cliente, o usuário será redirecionado para uma página do Nest que exibe um PIN (código de autorização). Em seguida, a IU do dispositivo vai solicitar que o usuário insira o PIN manualmente.
Experiência de URI de redirecionamento
Se você incluir um URI de redirecionamento na configuração do cliente, o usuário será redirecionado para uma página na nuvem (ou localhost), e o Nest enviará automaticamente o código de autorização para o dispositivo do usuário.
Testar ataques de CSRF
Antes de aceitar o código de autorização, seu produto precisa garantir que o valor retornado no parâmetro de estado corresponda ao valor do estado da sua solicitação de autorização original. Isso garante que você estará lidando com o usuário real e não com um script malicioso. Se os valores de estado não corresponderem, gere um código de erro HTTP 401 Não autorizado em resposta.
Um ataque de CSRF é um ataque que força um usuário final a executar ações indesejadas em um aplicativo da Web em que ele está autenticado no momento.
Para evitar ataques de CSRF, recomendamos que você sempre envie um
state não pingável ao solicitar autorização.
Dessa forma, sua integração do Works with Nest pode verificar se os códigos de acesso recebidos da nuvem do Nest são em resposta a solicitações feitas pelo seu produto, e não outro.
Exemplo:
Digamos que, na configuração do 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 consente com a solicitação.
A nuvem do 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 -
O produto recebe esse valor de estado e precisa ser programado para aceitar redirecionamentos apenas com um estado verificável.
Há várias maneiras de gerar um parâmetro de estado não detectável. Você pode fornecer valores de estado aleatórios de um dicionário mantido na memória ou de um valor respeitável. Você pode usar uma chave privada com algumas variáveis verificáveis facilmente (por exemplo, o ID do cliente e um cookie de sessão) para calcular um valor com hash. Isso resulta em um valor de byte difícil de adivinhar sem a chave privada. Outra sugestão é gerar a hash da data e hora atuais. Com essa abordagem, seu aplicativo precisa salvar o tempo de transmissão para verificá-lo ou permitir um período de validade de deslize (por exemplo, usando o algoritmo de senha única baseado em tempo [TOTP]).
Depois de calcular o código de autenticação de mensagem de hash com chave (HMAC, na sigla em inglês), codifique-o em base64 para transmiti-lo à nuvem do Nest como um parâmetro de estado.
Veja um exemplo em 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 do 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 mais informações sobre essas mensagens e como evitá-las, consulte a Referência de autorização.
Trocar código de autorização de um token de acesso
A etapa final para conseguir um token de acesso é que o produto solicite um usando o código de autorização que acabou de adquirir. Isso é feito com uma solicitação POST HTTP "quot;x-www-form-urlencoded"".
Inclua os parâmetros abaixo na solicitação. Os quatro parâmetros são obrigatórios.
| Parâmetro | Descrição |
|---|---|
| client_id | 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 desse campo precisa ser sempre: authorization_code |
Antes de cada chamada POST, receba um novo código de autorização. Para fazer isso, atualize o URL de autorização. Em seguida, altere o parâmetro code de POST' para incluir o novo
código de autorização.
Exemplos de código (autenticação)
Veja exemplos em várias linguagens.
Exemplo de Postman (autenticação)
O Postman oferece uma maneira fácil de testar as solicitações OAuth.
Na guia Headers, verifique se Content-Type =
application/x-www-form-urlencoded.
Na guia Corpo, inclua os seguintes pares de chave-valor.
Resposta do token de acesso
Uma solicitação bem-sucedida retorna um objeto JSON contendo os seguintes campos:
access_token: o token de acesso do usuário. Esse valor precisa ser mantido em segurança.expires_in: o número de segundos restantes, a partir do momento em que foi solicitado, antes da expiração do token.
Mensagens de erro do token de acesso
Se a solicitação falhar, você receberá um erro na forma de um Código de status HTTP. Para mais informações sobre esses erros e como evitá-los, consulte a Referência de autorização.
Fazer solicitações autenticadas
Depois que um produto recebe um token de acesso, ele o envia a 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 isso não é recomendável, já que os parâmetros de URI podem acabar em arquivos de registro 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 Postman (leitura/gravação)
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 Disallowed" do servidor. Um token pode ser inválido e precisa de nova geração porque:
- Expirado
- O usuário revogou a permissão que foi concedida inicialmente ao seu produto
É importante codificar o produto para processar corretamente um erro 401 "Não autorizado" redirecionando o usuário para o início do fluxo de trabalho de autorização.
Conexão Works with 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á encerrada.