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

OAuth 2.0 autenticação e autorização

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.

OAuth fluxo de 2,0
OAuth fluxo de 2,0

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 .

detalhes OAuth

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:

Funciona com ninho

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.

pincode

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.

ataque CSRF
ataque CSRF

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 .

POST cabeçalho para obter token de acesso

Na guia Corpo, incluem a seguinte chave: valor pares.

corpo POST para obter token de acesso

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 .

GET para ler dados

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.