El API Nest utiliza el protocolo OAuth 2.0 para la autenticación y autorización.
Antes de que su producto se puede acceder a los datos privados mediante la API Nido, debe obtener un token de acceso que permite el acceso a la API. Un token de acceso único puede conceder diferentes grados de acceso a múltiples sectores de la API.
La secuencia comienza cuando la autorización de su producto redirige el navegador a una dirección URL Jerarquía con los parámetros de consulta que indica el acceso solicitado. manijas del nido de autenticación de usuario, selección de sesión y consentimiento del usuario. El resultado es un código de autorización, que su producto puede cambiar por un token de acceso. Su producto se puede utilizar el token de acceso para realizar llamadas a la API de Nest.
Configurar su funciona con el cliente Nido
Para encontrar las credenciales de OAuth 2.0 para su cliente, compruebe la pestaña Resumen de la página del cliente.
autorización URI de redireccionamiento o basadas en PIN?
Cuando está configurando el cliente, se le pedirá que introduzca un URI de redireccionamiento o salir de la URI de redireccionamiento campos en blanco para utilizar la autorización basada en PIN.
Si el producto es un dispositivo que no tiene una aplicación asociada o una página web (por ejemplo, un rastreador de fitness, un aparato o un panel de seguridad), salen de la URI de redireccionamiento campos en blanco.
Si su producto tiene un componente de navegador, la mejor práctica es incluir una redirección URI.
solicitar permisos
La configuración de cliente incluye un conjunto de permisos (también llamados alcances). Un permiso es un parámetro variable que controla el conjunto de recursos y operaciones que un acceso permisos simbólicos. En general, es una buena práctica para solicitar permisos de forma incremental, por lo se requiere el acceso en tiempo, en lugar de en la delantera.
Resultado
Al guardar la configuración, su cliente se le asigna un ID de cliente única y secreta de cliente. Además, su cliente se le asigna una dirección URL de autorización.
La URL de autorización incluye un parámetro de estado que se puede utilizar para la prueba para su posible entre sitios de falsificación de petición ataques (CSRF). Ver prueba para los ataques CSRF .
Solicitar un código de autorización
Después de configurar su cliente, puede solicitar un código de autorización (a veces llamado un código PIN). El código de autorización no es la señal final que se utiliza para realizar llamadas a Nest. Se utiliza en el siguiente paso del flujo de OAuth 2.0 a cambio de un token de acceso real. Este paso proporciona una garantía directamente desde el nido al usuario que el permiso se concede al producto correcto, con el acceso acordados.
La experiencia de usuario
Presentamos funciona una página con el nido que pide al usuario para conceder acceso a su producto. Este identifica su producto y describe los particulares permisos de usuario (alcances) que su producto ha solicitado. Las palabras en la pantalla proceden de la configuración del cliente.
Para probar esto por sí mismo, cargue la URL de autorización del paso 1 en un navegador. Debería ver una página con Obras de solicitud de acceso Nido:
Vaya por delante y haga clic en [ACEPTAR] ti mismo para ver lo que el usuario ve. Al hacer clic en el botón [ACEPTAR], el usuario está aprobando la solicitud de su producto para acceder a sus datos.
experiencia PIN
Si sale de la URI de redireccionamiento campos en blanco en la configuración del cliente, el usuario es redirigido a una página de jerarquía que muestra un PIN (código de autorización). El dispositivo de interfaz de usuario a continuación, debe solicitar al usuario que introduzca el PIN de forma manual.
experiencia URI de redireccionamiento
Si se incluye una redirección URI en la configuración del cliente, el usuario es redirigido a una página en su nube (o localhost), y el Nido envía automáticamente el código de autorización al dispositivo del usuario.
Prueba de ataques CSRF
Antes de aceptar el código de autorización, el producto debe asegurarse de que el valor devuelto en el parámetro de estado coincide con el valor de estado de su solicitud de autorización original. Esto asegura que se trata de que el usuario real y no un script malicioso. Si los valores de estado no coinciden, usted debe lanzar un código de error HTTP 401 No autorizado en respuesta.
Un ataque CSRF es un ataque que las fuerzas de usuario fin de ejecutar acciones no deseadas en una aplicación web en la que actualmente están autenticados.
Para ayudar a Prevenir los ataques CSRF, se recomienda que siempre se envía una nonguessable state al solicitar autorización.
De esta manera, su funciona con la integración Nido puede verificar que los códigos de acceso obtenidos de la nube Nido son en respuesta a las solicitudes hechas por su producto, no algún otro producto.
Ejemplo:
Vamos a decir en la configuración del cliente, se especifica el URI de redireccionamiento:
http://localhost:5000/callback
Supongamos también que su cliente envía el 7tvPJiv8StrAqo9IQE9xsJaDso4 estado en la URL de autorización:
https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
El usuario consiente en la solicitud.
La nube Nest devuelve el parámetro de estado como parte de la redirección 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 -
Su producto recibe este valor de estado y debe ser programado para aceptar sólo las redirecciones con un estado verificable.
Existen múltiples maneras de generar un parámetro de estado no adivinar. Puede proporcionar valores de estado al azar de un diccionario guardado en la memoria o un valor recomputable. Puede utilizar una clave privada con algunas variables de fácil verificación, por ejemplo, el ID de cliente y una cookie de sesión, para calcular un valor hash. Esto resulta en un valor de byte que sea difícil de adivinar sin la clave privada. Otra sugerencia es para discutir la fecha y la hora actuales. Con este enfoque, la aplicación debe guardar el momento de la transmisión para verificar que ni permita un periodo de validez de deslizamiento (por ejemplo, mediante el algoritmo de contraseña basada en el tiempo de una sola vez [TOTP]).
Después de calcular el código de llave-hash de autenticación de mensajes (HMAC), base-64 codificar y pasarlo a la nube Nest como un parámetro de estado.
He aquí un ejemplo que utiliza Python 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)
mensajes de error del código de autorización
Si la solicitud de código de autorización falla, los usuarios ven un mensaje de error. Para obtener más información sobre estos mensajes y cómo prevenirlas, consulte la autorización de referencia .
código de autorización de cambio de un token de acceso
El último paso en la obtención de un token de acceso es para su producto a pedir uno utilizando el código de autorización que acaba de adquirir. Esto se realiza al hacer una petición POST "x-www-form-urlencoded" HTTP.
Incluir los parámetros siguientes en la solicitud. Se requiere que todos los cuatro parámetros.
| Parámetro | Descripción |
|---|---|
| Identificación del cliente | El ID de cliente en el Paso 1 |
| client_secret | El secreto de cliente en el Paso 1 |
| código | El código de autorización recibido en la etapa 2 |
| grant_type | El valor de este campo debe ser siempre: authorization_code |
Antes de cada llamada POST, obtener un nuevo código de autorización. Para ello, vuelva a cargar la URL de su autorización. A continuación, cambiar el POST del code parámetro para incluir el nuevo código de autorización.
Los ejemplos de código de autenticación ()
Ver ejemplos en varios idiomas .
ejemplo cartero (auth)
Cartero proporciona una manera fácil de solicitudes OAuth prueba.
En la ficha Encabezados, asegúrese de Content-Type = application/x-www-form-urlencoded .
En la ficha del cuerpo, incluyen los siguientes pares clave: valor. 
la respuesta testigo de acceso
Una solicitud exitosa devuelve un objeto JSON que contiene los siguientes campos:
-
access_token- El token de acceso para el usuario. Este valor debe mantenerse segura. -
expires_in- El número de segundos en el reloj, desde el momento en que fue solicitada, antes de que expire el token.
Token de acceso mensajes de error
Si la solicitud no, recibirá un error en la forma de un código de estado HTTP. Para obtener más información sobre estos errores y cómo prevenirlas, consulte la autorización de referencia .
Hacer peticiones autenticadas
Después de un producto obtiene un token de acceso, envía el token a una API Nido en una cabecera HTTP de autorización. Es posible enviar fichas como parámetros de cadena de consulta URI, pero no lo recomiendo, porque URI parámetros pueden terminar en los archivos de registro que no son seguras por completo.
Los tokens de acceso son válidos sólo para el conjunto de las operaciones y los recursos descritos en el ámbito de la solicitud de token. Por ejemplo, si un testigo de acceso se emite por el termostato Nest API, que no concede el acceso a la API de la cámara Nido.
Ejemplos de código (lectura / escritura)
ejemplo cartero (lectura / escritura)
Cartero proporciona una manera fácil de llamadas a la API de prueba utilizando Content-Type = application/json .
tokens no válidos
Si hace una llamada a la API mediante un token no válido, recibirá una copia no autorizada respuesta 401 del servidor. Un token podría ser inválida y con necesidad de regeneración debido a que:
- Se ha expirado
- El usuario ha revocado el permiso de que inicialmente concedidos a su producto
Es importante que se codifican su producto para manejar adecuadamente un error no autorizado 401 mediante la reorientación de la parte posterior de usuario al comienzo del flujo de trabajo de autorización.
Funciona con conexión Nido cerrados
Si un usuario elimina una Funciona con conexión Nido , el producto recibe un auth_revoked evento y se cierra la conexión.