Notice: We're retiring Works with Nest. See the home page for more information.
En Google, luchamos por la equidad racial de la comunidad negra. Más información
Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Autenticación y autorización de OAuth 2.0

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.

Flujo de OAuth 2.0
Flujo de OAuth 2.0

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 .

Detalles de OAuth

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:

Funciona con 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.

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 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.

Ataque CSRF
Ataque CSRF

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 .

Encabezado POST para obtener el token de acceso

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

POST cuerpo para obtener token de acceso

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 .

OBTENER para leer datos

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.