La API de Nest utiliza el protocolo OAuth 2.0 para autenticación y autorización.
Antes de que su producto pueda acceder a datos privados mediante la API de Nest, debe obtener un token de acceso que le otorgue acceso a esa API. Un solo token de acceso puede otorgar distintos grados de acceso a múltiples secciones de la API.
La secuencia de autorización comienza cuando su producto redirige un navegador a una URL de Nest con parámetros de consulta que indican el acceso solicitado. Nest maneja la autenticación del usuario, la selección de la sesión y el consentimiento del usuario. El resultado es un código de autorización, que su producto puede intercambiar por un token de acceso. Luego, su producto puede usar el token de acceso para realizar llamadas a la API de Nest.
Configura tu cliente Works with Nest
Para encontrar las credenciales de OAuth 2.0 para su cliente, consulte la pestaña Descripción general de la página del cliente.
¿Redirigir autorización basada en URI o PIN?
Cuando esté configurando su cliente, se le pedirá que ingrese un URI de redireccionamiento o deje los campos del URI de redireccionamiento en blanco para usar la autorización basada en PIN.
Si su producto es un dispositivo que no tiene una aplicación o página web asociada (por ejemplo, un rastreador de actividad física, un dispositivo o un panel de seguridad), deje los campos Redirect URI en blanco.
Si su producto tiene un componente de navegador, la mejor práctica es incluir un URI de redireccionamiento.
Solicitar permisos
La configuración del cliente incluye un conjunto de permisos (también llamados ámbitos). Un permiso es un parámetro variable que controla el conjunto de recursos y operaciones que permite un token de acceso. Por lo general, es una buena práctica solicitar permisos de forma incremental, en el momento en que se requiere el acceso, en lugar de hacerlo por adelantado.
Resultado
Cuando guarda la configuración, a su cliente se le asigna un ID de cliente y un secreto de cliente únicos. Además, a su cliente se le asigna una URL de autorización.
La URL de autorización incluye un parámetro de estado que puede usar para probar posibles ataques de falsificación de solicitudes entre sitios (CSRF). Ver prueba para los ataques CSRF .
Solicita un código de autorización
Una vez configurado su cliente, puede solicitar un código de autorización (a veces llamado código PIN). El código de autorización no es el token final que usa para hacer llamadas a Nest. Se utiliza en el siguiente paso del flujo de OAuth 2.0 para intercambiar por un token de acceso real. Este paso proporciona la garantía directamente de Nest al usuario de que se está otorgando permiso para el producto correcto, con el acceso acordado.
La experiencia del usuario
Presentamos una página Works with Nest que solicita al usuario que otorgue acceso a su producto. Esto identifica su producto y describe los permisos de usuario particulares (alcances) que su producto ha solicitado. Las palabras en la pantalla provienen de la configuración de su cliente.
Para probar esto usted mismo, cargue la URL de autorización del Paso 1 en un navegador. Debería ver una página de solicitud de acceso Works with Nest:
Continúe y haga clic en [ACEPTAR] usted mismo para ver lo que ve el usuario. 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 deja los campos Redirigir URI en blanco en la configuración de su cliente, el usuario es redirigido a una página de Nest que muestra un PIN (código de autorización). La interfaz de usuario de su dispositivo debería pedirle al usuario que ingrese el PIN manualmente.
Redirigir la experiencia de URI
Si incluye un URI de redireccionamiento en la configuración de su cliente, el usuario es redirigido a una página en su nube (o localhost) y Nest 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, su producto debe asegurarse de que el valor devuelto en el parámetro de estado coincida con el valor de estado de su solicitud de autorización original. Esto asegura que está tratando con el usuario real y no con un script malicioso. Si los valores del estado no coinciden, debe lanzar un código de error HTTP no autorizado 401 como respuesta.
Un ataque CSRF es un ataque que obliga a un usuario final a ejecutar acciones no deseadas en una aplicación web en la que está autenticado actualmente.
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 integración Works with Nest puede verificar que los códigos de acceso obtenidos de la nube de Nest respondan a las solicitudes realizadas por su producto, no a algún otro producto.
Ejemplo:
Digamos que en la configuración de su cliente, 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 da su consentimiento a la solicitud.
La nube de Nest devuelve el parámetro de estado como parte del URI de redireccionamiento:
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 programarse para aceptar solo redireccionamientos con un estado verificable.
Hay varias formas de generar un parámetro de estado que no se puede adivinar. Puede proporcionar valores de estado aleatorios de un diccionario guardado en la memoria o un valor recalculable. Puede usar una clave privada con algunas variables fácilmente verificables, por ejemplo, el ID de cliente y una cookie de sesión, para calcular un valor hash. Esto da como resultado un valor de byte que es difícil de adivinar sin la clave privada. Otra sugerencia es aplicar un hash a la fecha y hora actuales. Con este enfoque, su aplicación debe ahorrar el tiempo de transmisión para verificarla o permitir un período deslizante de validez (por ejemplo, utilizando el algoritmo de contraseña de un solo uso basado en el tiempo [TOTP]).
Después de calcular el código de autenticación de mensajes hash con clave (HMAC), codifíquelo en base 64 y páselo a la nube Nest como 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 del 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 intercambio para un token de acceso
El último paso para obtener un token de acceso es que su producto solicite uno utilizando el código de autorización que acaba de adquirir. Esto se hace mediante una solicitud HTTP POST "x-www-form-urlencoded".
Incluya los siguientes parámetros en la solicitud. Los cuatro parámetros son obligatorios.
| Parámetro | Descripción |
|---|---|
| Identificación del cliente | El ID de cliente en el paso 1 |
| client_secret | El secreto del cliente en el paso 1 |
| código | El código de autorización recibido en el paso 2 |
| grant_type | El valor de este campo debe ser siempre: authorization_code |
Antes de cada llamada POST, obtenga un nuevo código de autorización. Para hacer esto, vuelva a cargar su URL de autorización. A continuación, cambiar el POST del code parámetro para incluir el nuevo código de autorización.
Ejemplos de código (auth)
Ver ejemplos en varios idiomas .
Ejemplo de cartero (auth)
Postman proporciona una forma sencilla de probar las solicitudes de OAuth.
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. 
Respuesta del token 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 seguro. -
expires_in- El número de segundos en el reloj, desde el momento en que fue solicitada, antes de que expire el token.
Mensajes de error de token de acceso
Si la solicitud falla, recibirá un error en forma de código de estado HTTP. Para obtener más información sobre estos errores y cómo prevenirlas, consulte la autorización de referencia .
Realizar solicitudes autenticadas
Una vez que un producto obtiene un token de acceso, envía el token a una API de Nest en un encabezado de autorización HTTP. Es posible enviar tokens como parámetros de cadena de consulta URI, pero no lo recomendamos, porque los parámetros URI pueden terminar en archivos de registro que no son completamente seguros.
Los tokens de acceso son válidos solo para el conjunto de operaciones y recursos descritos en el alcance de la solicitud del token. Por ejemplo, si se emite un token de acceso para la API del termostato Nest, no otorga acceso a la API de la cámara Nest.
Ejemplos de código (lectura / escritura)
Ejemplo de cartero (lectura / escritura)
Cartero proporciona una manera fácil de llamadas a la API de prueba utilizando Content-Type = application/json .
Tokens inválidos
Si realiza una llamada a la API con un token no válido, recibirá una respuesta 401 no autorizada del servidor. Un token podría no ser válido y necesitar regeneración porque:
- Ha expirado
- El usuario ha revocado el permiso que inicialmente le otorgó a su producto.
Es importante que codifique su producto para manejar correctamente un error 401 no autorizado al redirigir al usuario al inicio del flujo de trabajo de autorización.
Funciona con la conexión Nest cerrada
Si un usuario elimina una Funciona con conexión Nido , el producto recibe un auth_revoked evento y se cierra la conexión.