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 solicita 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). Consulte Prueba de 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 usa en el siguiente paso del flujo de OAuth 2.0 para intercambiar por un token de acceso real. Este paso proporciona garantía directamente de Nest al usuario de que se está otorgando permiso al 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 probarlo usted mismo, cargue la URL de autorización del Paso 1 en un navegador. Debería ver una página de solicitud de acceso a 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 Redirect 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 ataques CSRF, le recomendamos que siempre envíe un state codificable cuando solicite 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 estado 7tvPJiv8StrAqo9IQE9xsJaDso4 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 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 imposible de 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 de validez deslizante (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), lo codifica en base 64 y lo pasa a la nube de Nest como parámetro de estado.
Aquí hay un ejemplo 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)
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 prevenirlos, consulte la Referencia de autorización .
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 siempre debe ser: 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. Luego, cambie el parámetro de code la POST para incluir el nuevo código de autorización.
Ejemplos de código (auth)
Vea ejemplos en varios idiomas .
Ejemplo de cartero (auth)
Postman proporciona una forma sencilla de probar las solicitudes de OAuth.
En la pestaña Encabezados , asegúrese de que Content-Type = application/x-www-form-urlencoded .
En la pestaña Cuerpo , incluya la siguiente clave: pares de valores. 
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: la cantidad de segundos restantes, desde el momento en que se solicitó, antes de que expire el token.
Mensajes de error del 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 prevenirlos, consulte la Referencia de autorización .
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)
Postman proporciona una forma sencilla de probar las llamadas a la API mediante 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 concedió 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 conexión Works with Nest , su producto recibe un evento auth_revoked y la conexión se cierra.