La API de Nest usa el protocolo de OAuth 2.0 para la autenticación y la autorización.
Antes de que tu producto pueda acceder a los datos privados con la API de Nest, debe obtener un token de acceso que le otorgue acceso a esa API. Un solo token de acceso puede otorgar diversos niveles de acceso a varias secciones de la API.
La secuencia de autorización comienza cuando tu producto redirecciona un navegador a una URL de Nest con parámetros de búsqueda que indican el acceso solicitado. Nest controla 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 tu producto puede intercambiar por un token de acceso. Luego, tu 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 de tu cliente, consulta la pestaña Overview de la página del cliente.
¿Quieres redireccionar el URI o la autorización basada en PIN?
Cuando configures tu cliente, se te solicitará que ingreses un URI de redireccionamiento o de que dejes en blanco los campos de URI de redireccionamiento para usar la autorización basada en PIN.
Si tu producto es un dispositivo que no tiene una app o página web asociada (por ejemplo, un rastreador de actividad física, un dispositivo o un panel de seguridad), deja en blanco los campos de URI de redireccionamiento.
Si tu producto tiene un componente de navegador, la práctica recomendada es incluir un URI de redireccionamiento.
Solicitará permisos
La configuración del cliente incluye un conjunto de permisos (también llamados permisos). Un permiso es un parámetro de variable que controla el conjunto de recursos y operaciones que permite un token de acceso. Por lo general, se recomienda solicitar permisos de forma incremental, en el momento en que se requiere acceso, en lugar de hacerlo por adelantado.
Resultado
Cuando guardas la configuración, a tu cliente se le asigna un ID de cliente y un secreto de cliente únicos. Además, se le asigna una URL de autorización.
La URL de autorización incluye un parámetro de estado que puedes usar para probar posibles ataques de falsificación de solicitudes entre sitios (CSRF). Consulta Prueba de ataques de CSRF.
Solicite un código de autorización
Después de configurar tu cliente, puedes 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 usas 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 una garantía directa de Nest al usuario de que se otorga el permiso al producto correcto, con el acceso acordado.
La experiencia del usuario
Presentamos una página Works with Nest que le solicita al usuario que otorgue acceso a tu producto. Esto identifica tu producto y describe los permisos de usuario (permisos) específicos que solicitó tu producto. Las palabras de la pantalla provienen de la configuración del cliente.
Para probarlo, carga la URL de autorización del paso 1 en un navegador. Deberías ver una página de solicitud de acceso a Works with Nest:
Haga clic en [ACEPTAR] para ver lo que el usuario ve. Si el usuario hace clic en el botón [ACEPTAR], significa que aprueba la solicitud para acceder a sus datos.
Experiencia con el PIN
Si dejas los campos del URI de redireccionamiento en blanco en la configuración de cliente, se redireccionará al usuario a una página de Nest que muestra un PIN (código de autorización). Luego, la IU del dispositivo debería solicitar al usuario que ingrese el PIN de forma manual.
Redireccionamiento de la experiencia de URI
Si incluyes un URI de redireccionamiento en la configuración del cliente, se redirecciona al usuario a una página en la nube (o localhost), y Nest envía automáticamente el código de autorización al dispositivo del usuario.
Prueba de ataques de CSRF
Antes de aceptar el código de autorización, tu producto debe asegurarse de que el valor que se muestra en el parámetro de estado coincida con el valor de estado de tu solicitud de autorización original. De esta manera, te aseguras de trabajar con el usuario real y no con una secuencia de comandos malintencionada. Si los valores de estado no coinciden, debes mostrar un código de error HTTP 401 no autorizado en respuesta.
Un ataque de CSRF es un ataque que obliga a un usuario final a ejecutar acciones no deseadas en una aplicación web en la que se encuentra autenticado actualmente.
A fin de evitar ataques de CSRF, te recomendamos que siempre envíes un state no discutible cuando solicites autorización.
De esta manera, la integración de Works with Nest puede verificar que los códigos de acceso obtenidos de la nube de Nest respondan a las solicitudes que realizó tu producto, no a otro producto.
Ejemplo:
Supongamos que especificas la URI de redireccionamiento en la configuración de tu cliente:
http://localhost:5000/callback
Supongamos también que tu 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 para la solicitud.
La nube de Nest muestra 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 -
Tu producto recibe este valor de estado y debe programarse para que solo acepte redireccionamientos con un estado verificable.
Existen varias maneras de generar un parámetro de estado no adivinable. Puedes proporcionar valores de estado aleatorios de un diccionario que se mantenga en la memoria o un valor respetable. Puedes utilizar una clave privada con algunas variables verificables fácilmente (por ejemplo, el ID de cliente y una cookie de sesión) para calcular un valor con hash. Esto da como resultado un valor de bytes que es difícil de adivinar sin la clave privada. Otra sugerencia es generar un hash para la fecha y hora actuales. Con este enfoque, tu aplicación debe ahorrar el tiempo de transmisión para verificarla o permitir un período variable de validez (por ejemplo, con el algoritmo de contraseña de un solo uso [TOTP] basada en el tiempo).
Después de calcular el código de autenticación de mensajes en clave hash (HMAC), lo codifica en Base64 y lo pasa a la nube de Nest como un parámetro de estado.
Este es 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 verán un mensaje de error. Para obtener más información sobre estos mensajes y cómo evitarlos, consulta la Referencia de autorización.
Intercambiar código de autorización por un token de acceso
El último paso para obtener un token de acceso es que el producto solicite uno con el código de autorización que acaba de adquirir. Para ello, se hace una solicitud HTTP POST.
Incluye los siguientes parámetros en la solicitud. Los cuatro parámetros son obligatorios.
| Parámetro | Descripción |
|---|---|
| client_id | 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, obtén un nuevo código de autorización. Para ello, vuelve a cargar tu URL de autorización. Luego, cambia el parámetro code de POST'para incluir el nuevo código de autorización.
Ejemplos de código (autenticación)
Consulta ejemplos en varios lenguajes.
Ejemplo de Postman (autenticación)
Postman proporciona una forma fácil de probar las solicitudes de OAuth.
En la pestaña Headers, asegúrate de que Content-Type = application/x-www-form-urlencoded.
En la pestaña Cuerpo, incluye los siguientes pares clave-valor.
Respuesta del token de acceso
Una solicitud correcta muestra un objeto JSON que contiene los siguientes campos:
access_token: El token de acceso para el usuario. Este valor se debe mantener seguro.expires_in: es la cantidad de segundos restantes desde el momento en que se solicita antes de que venza 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 evitarlos, consulta la Referencia de autorización.
Realiza solicitudes autenticadas
Después de que un producto obtiene un token de acceso, lo envía a una API de Nest en un encabezado de autorización HTTP. Es posible enviar tokens como parámetros de string de consulta de URI, pero no lo recomendamos, ya que los parámetros de URI pueden terminar en archivos de registro que no son del todo seguros.
Los tokens de acceso solo son válidos para el conjunto de operaciones y recursos descritos en el alcance de la solicitud de token. Por ejemplo, si se emite un token de acceso para la API del Nest Thermostat, no otorga acceso a la API de Nest Camera.
Ejemplos de código (lectura/escritura)
Ejemplo de Postman (lectura/escritura)
Postman proporciona una forma fácil de probar las llamadas a la API mediante Content-Type = application/json.
Tokens no válidos
Si realizas una llamada a la API con un token no válido, recibirás una respuesta 401 no autorizada del servidor. Es posible que un token no sea válido y necesite regeneración debido a lo siguiente:
- Venció
- El usuario revocó el permiso que otorgó inicialmente a su producto
Es importante que codifiques tu producto para manejar correctamente un error 401 no autorizado mediante el redireccionamiento del usuario al inicio del flujo de trabajo de autorización.
Se cerró la conexión Works with Nest
Si un usuario quita una conexión Works with Nest, tu producto recibirá un evento auth_revoked y se cerrará la conexión.