Notice: We're retiring Works with Nest. See the home page for more information.
O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.
Esta página foi traduzida pela API Cloud Translation.
Switch to English

Autenticação e autorização do OAuth 2.0

A API do Nest usa o protocolo OAuth 2.0 para autenticação e autorização.

Para que seu produto possa acessar dados particulares usando a API do Nest, é necessário 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 o produto redireciona um navegador para um URL do Nest com parâmetros de consulta indicando o acesso solicitado. O Nest lida com a 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 usar o token de acesso para fazer chamadas para a API do Nest.

Fluxo OAuth 2.0
Fluxo OAuth 2.0

Configure o 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 URI ou autorização baseada em 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 condicionamento físico, um dispositivo ou um painel de segurança), deixe em branco os campos URI de redirecionamento.

Se o seu produto tiver um componente do navegador, a melhor prática é 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 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 e um Segredo do 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 para ataques CSRF .

Detalhes do OAuth

Solicitar um código de autorização

Após a configuração do seu cliente, 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 o Nest. Ele é usado na próxima etapa do fluxo do OAuth 2.0 para trocar por um token de acesso real. Esta etapa fornece garantia diretamente da Nest ao usuário 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 solicita que o usuário conceda 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 ao Works with Nest:

Funciona com o 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 com PIN

Se você deixar os campos 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). A interface do usuário do dispositivo deve solicitar ao usuário que insira o PIN manualmente.

Pincode

Redirecionar experiência 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 host local) 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 state corresponda ao valor do estado da 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 do estado não corresponderem, você deverá lançar um código de erro 401 Não autorizado 401.

Um ataque CSRF é um ataque que força um usuário final a executar ações indesejadas em um aplicativo Web no qual ele está atualmente autenticado.

Ataque CSRF
Ataque CSRF

Para ajudar a impedir ataques de CSRF, recomendamos que você sempre envie um state suspeitável ao solicitar autorização.

Dessa forma, sua integração do Works com Nest pode verificar se os códigos de acesso obtidos da nuvem Nest estão em resposta às solicitações feitas pelo seu produto, e não a algum outro produto.

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 Nest retorna o parâmetro state 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 impossível de adivinhar. Você pode fornecer valores de estado aleatórios a partir 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 de hash. Isso resulta em um valor de byte difícil de adivinhar sem a chave privada. Outra sugestão é o 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 de validade deslizante (por exemplo, usando o algoritmo de senha de uso único baseado em tempo [TOTP]).

Depois de calcular o código de autenticação de mensagem de hash com chave (HMAC), a base-64 codifica-o e passa-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 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 obter mais informações sobre essas mensagens e como evitá-las, consulte a Referência da autorização .

Trocar código de autorização para um token de acesso

A etapa final na obtenção de um token de acesso é solicitar ao seu produto um usando o código de autorização que acabou de adquirir. Isso é feito com uma solicitação HTTP POST "x-www-form-urlencoded".

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 na etapa 1
código O código de autorização recebido na Etapa 2
grant_type O valor desse campo deve sempre ser: authorization_code

Antes de cada chamada POST, obtenha um novo código de autorização. Para fazer isso, recarregue seu URL de autorização. 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 fornece uma maneira fácil de testar solicitações de OAuth.

Na guia Cabeçalhos , verifique se Content-Type = application/x-www-form-urlencoded .

Cabeçalho POST para obter o token de acesso

Na guia Corpo , inclua a seguinte chave: pares de valores.

Corpo do POST para obter o token de acesso

Resposta do token de acesso

Uma solicitação bem-sucedida retorna um objeto JSON que contém 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 solicitado, antes que o token expire.

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 obter mais informações sobre esses erros e como evitá-los, consulte a Referência da autorização .

Faça pedidos autenticados

Depois que um produto obtém um token de acesso, ele o envia para uma API do Nest em um cabeçalho de autorização HTTP. É possível enviar tokens como parâmetros de cadeia de consulta do URI, mas não o recomendamos, porque os parâmetros do URI podem terminar 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)

O Postman fornece uma maneira fácil de testar chamadas de API usando Content-Type = application/json .

GET para ler dados

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 precisa ser regenerado porque:

  • Expirou
  • O usuário revogou a permissão que concedeu 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 a 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.