Notice: We're retiring Works with Nest. See the home page for more information.
Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.
Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Autenticación y autorización de OAuth 2.0

Nest API usa el protocolo OAuth 2.0 para autenticación y autorización.

Antes de que su producto pueda acceder a datos privados utilizando la API de Nest, debe obtener un token de acceso que le otorgue acceso a esa API. Un único token de acceso puede otorgar diversos 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 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. Su producto puede usar el token de acceso para realizar llamadas a la API de Nest.

Flujo OAuth 2.0
Flujo OAuth 2.0

Configure sus trabajos con el cliente 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 URI o autorización basada en PIN?

Cuando configura su cliente, se le solicita que ingrese un URI de redireccionamiento o deje los campos de 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 en blanco los campos Redirigir URI.

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. En general, es una buena práctica solicitar permisos de forma incremental, en el momento en que se requiere acceso, en lugar de hacerlo por adelantado.

Resultado

Cuando guarda la configuración, a su cliente se le asigna una 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 de ataques CSRF .

Detalles de OAuth

Solicitar un código de autorización

Después de configurar 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 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 garantiza directamente al usuario Nest que se le está otorgando permiso al producto correcto, con el acceso acordado.

La experiencia del usuario

Presentamos una página de Works with Nest que le pide al usuario que otorgue acceso a su producto. Esto identifica su producto y describe los permisos de usuario particulares (ámbitos) 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 de Works with Nest:

Trabaja con nido

Continúe y haga clic en [ACEPTAR] para ver lo que ve el usuario. Al hacer clic en el botón [ACEPTAR], el usuario aprueba 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 debe solicitar al usuario que ingrese el PIN manualmente.

Código PIN

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 de estado no coinciden, debe arrojar un código de error HTTP 401 no autorizado en 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.

Ataque CSRF
Ataque CSRF

Para ayudar a prevenir ataques CSRF, le recomendamos que siempre envíe un state pueda controlar cuando solicite autorización.

De esta manera, su integración de Works with Nest puede verificar que los códigos de acceso obtenidos de la nube de Nest responden a las solicitudes realizadas por su producto, no por otro producto.

Ejemplo:

Digamos que en la configuración de su cliente, usted 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 acepta 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 redirecciones con un estado verificable.

Hay varias formas de generar un parámetro de estado no adivinable. 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, la ID del 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 hacer un hash de 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 variable (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 mensaje de hash con clave (HMAC), codifíquelo en base 64 y páselo 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 paso final 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 realiza 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 La identificación del 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
tipo de concesión 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 del code POST 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 manera fácil de probar las solicitudes de OAuth.

En la pestaña Encabezados , asegúrese de Content-Type = application/x-www-form-urlencoded .

POST encabezado para obtener token de acceso

En la pestaña Cuerpo , incluya la siguiente clave: pares de valores.

POST cuerpo para obtener token de acceso

Respuesta de 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 restantes, desde el momento en que se solicitó, antes de que caduque 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 prevenirlos, consulte la Referencia de autorización .

Hacer 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 cadena de consulta de URI, pero no lo recomendamos, porque los parámetros de 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 de tokens. Por ejemplo, si se emite un token de acceso para la API de Nest Thermostat, no otorga acceso a la API de Nest Camera.

Ejemplos de código (lectura / escritura)

Ejemplo de cartero (lectura / escritura)

Postman proporciona una manera fácil de probar las llamadas API utilizando Content-Type = application/json .

OBTENER para leer datos

Fichas inválidas

Si realiza una llamada API utilizando un token no válido, recibirá una respuesta no autorizada 401 del servidor. Un token podría ser inválido y necesitar regeneración porque:

  • Ha expirado
  • El usuario ha revocado el permiso que inicialmente otorgó a su producto.

Es importante que codifique su producto para manejar adecuadamente un error no autorizado 401 redirigiendo al usuario nuevamente al inicio del flujo de trabajo de autorización.

Funciona con la conexión Nest cerrada

Si un usuario elimina una conexión de Works with Nest , su producto recibe un evento auth_revoked y la conexión se cierra.