Uso de OAuth con las APIs de Google Data

Introducción

Es un momento emocionante para los desarrolladores. Comenzamos a ver que se adoptan varios estándares abiertos en la Web y, como sabes, Google siempre ha sido un gran fan de los estándares y de fomentar la comunidad de código abierto.

Recientemente, todas las APIs de datos de Google adoptaron la compatibilidad con OAuth, un protocolo abierto que tiene como objetivo estandarizar la forma en que las aplicaciones web y de escritorio acceden a los datos privados de un usuario. OAuth proporciona un medio para realizar la autenticación de la API de forma estándar y segura. Como programadores, se nos enseña a reutilizar el código siempre que sea posible. OAuth ayudará a los desarrolladores a reducir la cantidad de código duplicado que escriben y facilitará la creación de herramientas que funcionen con varios servicios de una variedad de proveedores diferentes.

Público

En este artículo, se supone que conoces una o más de las APIs de datos de Google, pero no necesariamente los conceptos detrás de OAuth. Si estás comenzando o simplemente sientes curiosidad por OAuth, no busques más. En este artículo, se te proporcionará una base de los conceptos. También analizaré los detalles de la implementación de OAuth de Google.

Este documento también está dirigido a los desarrolladores que saben cómo usar AuthSub, en especial en el modo registrado con seguridad mejorada. A medida que avancemos, intentaré destacar las similitudes y las diferencias entre los dos protocolos. Si tienes aplicaciones que usan AuthSub, puedes usar esta información para migrar a OAuth, que es un protocolo más abierto y moderno.

Un poco de terminología

Comprender OAuth se trata de entender su terminología. La especificación de OAuth y la documentación de Autenticación de OAuth para aplicaciones web de Google se basan en gran medida en ciertas definiciones, por lo que aclararemos qué significa cada una en el contexto de la implementación de OAuth de Google.

1. "OAuth dance"

   Término no oficial que uso para describir el proceso completo de autenticación y autorización de OAuth.

2. Token de solicitud (OAuth)

   Es un token inicial que le permite a Google saber que tu aplicación solicita acceso a una de las APIs de Google Data. El segundo paso del proceso de OAuth es que el usuario otorgue acceso manualmente a sus datos. Si este paso se realiza correctamente, el token de solicitud se autoriza.

3. Token de acceso (OAuth)

   El último paso del intercambio es cambiar el token de solicitud autorizado por un token de acceso. Una vez que tu aplicación tenga este token, el usuario no necesitará volver a realizar el proceso de OAuth, a menos que se revoque el token.

   Similitud con AuthSub:
   Un token de acceso de OAuth es lo mismo que un token de sesión de AuthSub seguro.

4. Extremos (OAuth)

   Son los URIs necesarios para autenticar una aplicación y obtener un token de acceso. Hay tres en total, una para cada paso del proceso de OAuth. Los extremos de OAuth de Google son los siguientes:

   Obtén un token de solicitud:	https://www.google.com/accounts/OAuthGetRequestToken
   Autoriza el token de solicitud:	https://www.google.com/accounts/OAuthAuthorizeToken
   Actualiza a un token de acceso:	https://www.google.com/accounts/OAuthGetAccessToken

   Similitud con AuthSub:
   El intercambio de un token de solicitud autorizado por un token de acceso es análogo a la actualización de un token de AuthSub de un solo uso a un token de sesión de larga duración en https://www.google.com/accounts/AuthSubRequestToken y https://www.google.com/accounts/AuthSubSessionToken, respectivamente. La diferencia es que AuthSub no tiene el concepto de un token de solicitud inicial. En su lugar, el usuario inicia el proceso del token desde la página de autorización AuthSubRequestToken.

5. Proveedor de servicios (OAuth)

   En el caso de las APIs de datos de Google, este proveedor es Google. En general, el proveedor de servicios se usa para describir el sitio web o el servicio web que proporciona los extremos de OAuth. Otro ejemplo de proveedor de servicios de OAuth es MySpace.

6. Consumidor (OAuth)

   Es el programa que solicita permiso para acceder a los datos de un usuario (es decir, tu aplicación). El protocolo de OAuth es flexible, ya que permite una amplia variedad de tipos de clientes diferentes (web, instalados, de escritorio, móviles).

Nota: Si bien el protocolo de OAuth admite el caso de uso de aplicaciones instaladas o de escritorio, Google solo admite OAuth para aplicaciones web.

Comenzar

Registro

Antes de comenzar a usar OAuth con las APIs de datos de Google, debes realizar una pequeña configuración. Dado que todas las solicitudes de OAuth deben firmarse digitalmente, primero debes registrar tu dominio y subir un certificado público a Google. Consulta Registro para aplicaciones basadas en la Web y Cómo generar claves y certificados para usar con el modo registrado para obtener más información sobre cómo hacerlo.

Solicitudes de firmas

Una vez que se registre tu dominio, podrás comenzar a firmar solicitudes. Uno de los conceptos más difíciles de OAuth es cómo construir correctamente el oauth_signature y la noción de la cadena base de la firma. La cadena base son los datos que firmas con tu clave privada (con RSA_SHA1). El resultado es el valor que estableces para oauth_signature.

Ejemplo de solicitud

GET una lista de los Calendarios de Google de un usuario en http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Nota: Esto es solo una representación. Tu oauth_signature será mucho más largo.

Notas sobre la cadena base:

• El parámetro de búsqueda orderby=starttime se ordena junto con el resto de los parámetros oauth_* en orden lexicográfico de valor de byte.
• Esta cadena tampoco contiene el carácter "?".
• La parte base-http-request-url solo contiene la URL base codificada en formato de URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
• El parámetro oauth_token está codificado como URL doble.

Notas sobre el encabezado Authorization:

• El orden de los parámetros oauth_* no importa en el encabezado Authorization.
• El encabezado no incluye orderby=starttime como lo hizo la cadena base. Ese parámetro de consulta se mantiene como parte de la URL de la solicitud.

Para obtener más información sobre cómo firmar solicitudes con OAuth, consulta Cómo firmar solicitudes de OAuth.

Diferencia con AuthSub:
A modo de comparación, aquí se muestra el mismo ejemplo con AuthSub seguro:

GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Para obtener más información sobre cómo firmar solicitudes con AuthSub, consulta Cómo firmar solicitudes de AuthSub.

Herramienta de OAuth Playground

Pruébalo

Objetivo

Algunos usuarios sugirieron que OAuth tiene una curva de aprendizaje pronunciada. En comparación con otras APIs de autenticación de Google, estaría de acuerdo. La ventaja de OAuth será evidente cuando expandas tu app para usar otros servicios (que no sean de Google). Escribir un solo fragmento de código de autenticación que funcione en diferentes proveedores de servicios y sus APIs me parece una buena idea. Más adelante, te agradecerás por aprender el protocolo ahora.

El OAuth Playground es una herramienta que creé para ayudar a los desarrolladores a solucionar sus problemas relacionados con OAuth. Puedes usar Playground para depurar problemas, verificar tu propia implementación o experimentar con las APIs de Google Data.

¿Qué hace?

1. Ilustra el flujo de autenticación de OAuth: cómo recuperar un token de solicitud, autorizar el token y actualizarlo a un token de acceso.
2. Muestra la cadena base de firma correcta para cada solicitud.
3. Muestra el encabezado Authorization correcto para cada solicitud.
4. Muestra cómo usar un objeto oauth_token para interactuar con un feed de datos de Google autenticado. Puedes GET/POST/PUT/DELETE datos.
5. Visualiza un feed autenticado directamente en tu navegador.
6. Te permite probar tu propio oauth_consumer_key (tu dominio registrado) y tu clave privada.
7. Descubre qué servicios de feeds de datos de Google están disponibles para tu oauth_token.

Ejecución de demostración

Paso 1: Elige tus alcances Primero, elige uno o más permisos para decidir qué APIs quieres usar. En esta demostración, solicitaré un token que funcionará con Blogger y con Google Contacts. Similitud con AuthSub: AuthSub también requiere el parámetro scope para controlar el rango de datos a los que puede acceder un token. Google implementó este parámetro como se sugiere en la especificación de OAuth.
Paso 2: Modifica los parámetros y la configuración de OAuth Por el momento, no modifiques ningún parámetro de configuración en el cuadro "Modify the OAuth Parameters". Más adelante, puedes realizar pruebas con tu propia clave privada. Para ello, cambia oauth_consumer_key a tu dominio registrado y haz clic en "Usar tu propia clave privada" para ingresar tu clave privada. Usa solo una clave privada de PRUEBA. Nota: oauth_signature_method y oauth_consumer_key son los únicos campos que se pueden editar aquí. Las opciones oauth_timestamp, oauth_nonce y oauth_token se generarán automáticamente. Además de RSA-SHA1, puedes usar HMAC-SHA1 para oauth_signature_method. En ese caso, Playground mostrará cuadros adicionales en los que deberás ingresar tu propio oauth_consumer_key y secreto del consumidor. Puedes encontrar estos valores en la página https://www.google.com/accounts/ManageDomains de tu dominio registrado. Diferencia con AuthSub: En AuthSub seguro, no hay ningún parámetro para establecer explícitamente un nombre de dominio. El dominio se incluye como parte del parámetro de URL next. Existe un parámetro de este tipo en OAuth: oauth_consumer_key. Establécelo en tu dominio registrado.
Pasos 3 a 5: Obtén el token de acceso Para obtener un token de acceso de OAuth, debes seguir tres pasos. El primer paso es recuperar un token de solicitud. Esto le permite a Google saber que tu aplicación está iniciando el intercambio de OAuth. Primero, haz clic en el botón "Solicitar token" en el cuadro "Obtener el token". Algunos campos se propagarán con datos. La "Cadena base de la firma" muestra la forma correcta de la cadena base que se usa para crear el parámetro oauth_signature. El "encabezado de autorización" muestra el encabezado Authorization correspondiente para la solicitud. El cuadro "Modificar los parámetros de OAuth" completado con los valores oauth_nonce y oauth_timestamp enviados en la solicitud. La entrada oauth_token se completó con el valor correspondiente que se devolvió en el cuerpo de la respuesta. Playground también muestra qué tipo de oauth_token tenemos actualmente. Por el momento, es un token de solicitud.
A continuación, haz clic en el botón "Autorizar" en el cuadro "Obtener el token". En esta página de autorización, haz clic en el botón "Grant Access" para autorizar el token de solicitud y volver a OAuth Playground. Similitud con AuthSub: Esta página de autorización es la misma para AuthSub. Diferencia con AuthSub: El parámetro de URL next de AuthSub es análogo al parámetro oauth_callback. La diferencia es que, en OAuth, el oauth_callback es opcional. Después de que el usuario hace clic en el botón "Grant access", el token de solicitud se autoriza y la actualización del token a https://www.google.com/accounts/OAuthGetAccessToken se puede realizar de forma asíncrona. Nota: Se prefiere especificar una URL de oauth_callback si escribes una aplicación web, ya que proporciona una mejor experiencia del usuario.
Por último, haz clic en el botón “Token de acceso” en el cuadro “Obtén el token”. Esta acción actualiza el token de solicitud autorizado (como se indica en la etiqueta roja "token de acceso"). Si deseas recuperar un token nuevo, haz clic en "Volver a empezar" para reiniciar el intercambio de OAuth. Ahora podemos hacer algo interesante.

Cómo usar el token de acceso

Ahora puedes consultar feeds, insertar, actualizar o borrar datos. Ten cuidado cuando realices estos tres últimos métodos HTTP, ya que trabajarás con tus datos reales.

Nota: Para descubrir los feeds disponibles para tu token de acceso, haz clic en el botón "Feeds disponibles".

Aquí tienes un ejemplo de consulta: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

En este ejemplo, se muestran no más de tres publicaciones en un blog en particular. También puedes ver el feed o la entrada devueltos directamente en tu navegador haciendo clic en el vínculo "Ver en el navegador" que se encuentra debajo del área destacada de la sintaxis.

Ejemplo: Cómo actualizar una publicación

1. Ubica el elemento <link> con un rel="edit" en la publicación que deseas actualizar. Deberá verse de la siguiente manera:

   <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

   Pega la URL de href en la entrada "Ingresa un feed de datos de Google".

2. Para copiar el XML de la entrada existente, haz clic en "Ver texto sin formato" en la parte superior del panel con sintaxis resaltada. Solo copia el cuerpo de la respuesta, no los encabezados.
3. Cambia el menú desplegable del método HTTP a PUT.
4. Haz clic en "enter post data" debajo de ese menú desplegable y pega el XML de <entry> en la ventana emergente.
5. Haz clic en el botón "Ejecutar".

El servidor responderá con un 200 OK.

Nota: En lugar de copiar manualmente el vínculo edit, desmarca la casilla de verificación “¿Resaltado de sintaxis?”. Después de una consulta, podrás hacer clic en los vínculos dentro de los cuerpos de respuesta XML.

Conclusión

Las tecnologías como el protocolo de publicación Atom/AtomPub (protocolo subyacente de las APIs de Google Data) y OAuth ayudan a impulsar la Web. A medida que más y más sitios comiencen a adoptar estos estándares, los desarrolladores seremos los ganadores. Crear una app increíble de repente se vuelve menos intimidante.

Si tienes preguntas o comentarios sobre OAuth Playground, o sobre el uso de OAuth con las APIs de Google, visítanos en el Foro de asistencia de las APIs de G Suite y de Marketplace.

Recursos

• Autenticación de OAuth para aplicaciones web
• Lista de APIs de datos de Google
• Foro de debate sobre las APIs de Cuentas de Google
• Especificación principal de OAuth 1.0