Uso de OAuth con las API de datos de Google

Eric Bidelman, equipo de API de datos de Google
Septiembre de 2008

Introducción

Es un momento emocionante para los desarrolladores. Estamos empezando a ver una serie de estándares abiertos en toda la Web y, como sabes, Google siempre ha sido un gran fanático de los estándares y fomentando la comunidad de código abierto.

Recientemente, todas las API 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 manera 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 asume que estás familiarizado con una o más de las API de datos de Google, pero no necesariamente con los conceptos detrás de OAuth. Si recién comienza o le interesa OAuth, no busque más. En este artículo, se proporcionan una base básica de los conceptos. También analizaré los detalles de la implementación de OAuth de Google.

Este documento también está dirigido a programadores que están familiarizados con el uso de AuthSub, especialmente en el modo registrado con modo de seguridad mejorada. Mientras lo hacemos, trataremos de destacar las similitudes y las diferencias entre ambos 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

La comprensión de OAuth se trata de comprender su terminología. La especificación OAuth y la documentación Autenticación OAuth para aplicaciones web de Google dependen en gran medida de ciertas definiciones, por lo que aclaramos qué significa cada uno en el contexto de la implementación de OAuth de Google.

  1. "Danza de OAuth"

    Mi término no oficial para describir el proceso completo de autenticación o autorización de OAuth

  2. (OAuth) Token de solicitud

    Un token inicial que informa a Google que tu aplicación solicita acceso a una de las API de datos de Google. El segundo paso de la danza OAuth es que el usuario otorgue acceso a sus datos de forma manual. Si este paso tiene éxito, se autoriza el token de solicitud.

  3. (OAuth) Token de acceso

    El último paso del baile es intercambiar el token de solicitud autorizado por un token de acceso. Una vez que la aplicación tenga este token, el usuario no tendrá que volver a pasar por el baile de OAuth, a menos que se revoque.

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

  4. (OAuth) Extremos

    Estos son URI 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:
    Intercambiar un token de solicitud autorizado por un token de acceso es análogo a actualizar un token de AuthSub de uso único 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 de token desde la página de autorización de AuthSubRequestToken.

  5. Proveedor de servicios (OAuth)

    En el caso de las API 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 un proveedor de servicios de OAuth es MySpace.

  6. Consumidor (OAuth)

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

Nota: Aunque el protocolo OAuth admite el caso de uso de la aplicación instalada o de escritorio, Google solo admite OAuth para las aplicaciones web.

Cómo comenzar

Registro

Hay una pequeña configuración para poder comenzar a usar OAuth con las API de datos de Google. Debido a que todas las solicitudes de OAuth deben estar firmadas digitalmente, primero debes registrar tu dominio y subir un certificado público a Google. Consulta Registro para aplicaciones basadas en la Web y Genera claves y certificados para usar con el modo registrado a fin de obtener más información sobre cómo hacerlo.

Solicitudes de firmas

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

Solicitud de ejemplo

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

Formato de string base base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Ejemplo de string base GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Ejemplo de solicitud HTTP 
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 solo se considera una representación. Tu oauth_signature será mucho más largo.

Notas sobre la string base:

  • El parámetro de consulta orderby=starttime se ordena junto con el resto de los parámetros oauth_* en el orden de valores de bytes lexicográficos.
  • Esta string también no contiene un carácter "?".
  • La parte base-http-request-url solo contiene la URL base codificada de URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • La oauth_token está codificada en dos URL.

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 la string 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 mediante OAuth, consulta Cómo firmar solicitudes de OAuth.

Diferencia de AuthSub:
Como comparación, este es el mismo ejemplo que usa AuthSub seguro:

Formato de string base base_string = http-method http-request-URL timestamp nonce
Ejemplo de string base 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Ejemplo de solicitud HTTP 
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 Playground de OAuth

Objetivo

Algunos usuarios han sugerido que OAuth tiene una curva de aprendizaje alta. En comparación con las otras API de autenticación de Google, estaría de acuerdo. La ventaja de OAuth será evidente cuando expandas tu app para usar otros servicios (distintos de Google). Me parece que escribir un único código de autenticación que funciona entre diferentes proveedores de servicios y sus API. Más tarde se agradecerá por aprender el protocolo.

OAuth Playground es una herramienta que creé para ayudar a los desarrolladores a curar los problemas de OAuth. Puedes usar Playground para depurar problemas, verificar tu propia implementación o experimentar con las API de datos de Google.

¿Cómo funciona?

  1. Ilustra el flujo de autenticación de OAuth: obtención de un token de solicitud, autorización del token y actualización a un token de acceso.
  2. Muestra la string base de firma correcta para cada solicitud.
  3. Muestra el encabezado Authorization correcto para cada solicitud.
  4. Demuestra cómo usar un oauth_token para interactuar con un feed de datos de Google autenticado. Puedes usar los datos de GET, POST, PUT o DELETE.
  5. Consulte un feed autenticado directamente en su navegador.
  6. Te permite probar tu propia oauth_consumer_key (tu dominio registrado) y tu clave privada.
  7. Descubre qué servicios de feed de datos de Google están disponibles para tu oauth_token.

Ejecución de la demostración

Paso 1: Elige tus permisos

Primero, decide qué API deseas utilizar mediante la elección de uno o más alcances. En esta demostración, solicito un token que funcione con Blogger y con los Contactos de Google.

Similitud con AuthSub:
AuthSub también requiere el parámetro scope para controlar el rango de datos al 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 ahora, no modifiques ninguna configuración del cuadro "Modifica los parámetros de OAuth". Más adelante, podrás probar con tu clave privada si cambias el oauth_consumer_key al dominio registrado e ingresas la clave privada con un clic en "usar tu propia clave privada". Usa solo una clave privada TEST.

Nota: oauth_signature_method y oauth_consumer_key son los únicos campos que se pueden editar aquí. oauth_timestamp, oauth_nonce y oauth_token se generarán de forma automática para ti.

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 de consumidor. Puede consultar estos valores en la página https://www.google.com/accounts/ManageDomains de su dominio registrado.

Diferencia de AuthSub:
En AuthSub seguro, no hay parámetros para establecer un nombre de dominio de forma explícita. El dominio se incluye como parte del parámetro de URL next. Existe ese parámetro en OAuth: oauth_consumer_key. Establécelo en tu dominio registrado.

Paso 3-5: Obtén el token de acceso

Existen tres pasos para obtener un token de acceso OAuth. El primer paso es recuperar un token de solicitud. Esto le indica a Google que tu aplicación está iniciando el baile 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 "String base de firma" muestra la forma adecuada de la string base que se usó 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" con los valores oauth_nonce y oauth_timestamp enviados en la solicitud
  • La entrada oauth_token se propagó con el valor correspondiente que se mostró en el cuerpo de la respuesta. Playground también muestra el tipo de oauth_token que tenemos actualmente. Por el momento, es un token de solicitud.

Luego, haga 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 "Otorgar acceso" para autorizar el token de solicitud y volver a ir al Playground de OAuth.

Similitud con AuthSub:
Esta página de autorización es la misma para AuthSub.

Diferencia de AuthSub:
El parámetro de URL next de AuthSub es análogo al parámetro oauth_callback. La diferencia es que en OAuth oauth_callback es opcional. Después de que el usuario haga clic en el botón "Otorgar acceso", se autorizará el token de solicitud y la actualización del token a https://www.google.com/accounts/OAuthGetAccessToken se podrá realizar de forma asíncrona.

Sugerencia: Se recomienda especificar una URL oauth_callback si escribes una aplicación web, ya que brinda una mejor experiencia del usuario.

Por último, haz clic en el botón "Token de acceso" en el cuadro "Obtener el token".

Esta acción actualiza la etiqueta del token de solicitud autorizado (como indica la etiqueta roja "token de acceso").

Si deseas obtener un token nuevo, haz clic en "comenzar de nuevo" para volver a iniciar el baile OAuth.

Ahora podemos hacer algo interesante.

Usa el token de acceso

Ahora está listo para consultar feeds, insertar, actualizar o borrar datos. Tenga cuidado al realizar estos últimos tres métodos HTTP mientras trabaja con sus datos reales.

Sugerencia: A fin de descubrir los feeds disponibles para su token de acceso, haga clic en el botón “Feeds disponibles”.

A continuación, se muestra una consulta de ejemplo: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Este ejemplo no muestra más de tres entradas en un blog en particular. También puedes ver el feed o la entrada devueltos directamente en el navegador. Para ello, haz clic en el vínculo "Ver en el navegador" debajo del área destacada de la sintaxis.

Ejemplo: Cómo actualizar una publicación

  1. Localiza el elemento <link> con un rel="edit" en la publicación que deseas actualizar. Debería verse algo similar a: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

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

  2. Copia el XML de la entrada existente haciendo clic en "view plain" en la parte superior del panel destacado de la sintaxis. 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 "Ingresar datos de entrada" debajo de ese menú desplegable y pega el XML <entry> en la ventana emergente.
  5. Haz clic en el botón "ejecutar".

El servidor responderá con un 200 OK.

Sugerencia: En lugar de copiar manualmente el vínculo de edit, desmarca la casilla de verificación "Sintaxis de momentos destacados". Después de una consulta, podrás hacer clic en los vínculos que aparecen dentro del cuerpo de la respuesta XML.

Conclusión

Las tecnologías como el AtomPub/Atom Publishing Protocol (protocolo subyacente de las API de datos de Google) y OAuth ayudan a impulsar la Web. A medida que más y más sitios comienzan a adoptar estos estándares, los desarrolladores son los ganadores. La creación de una aplicación excelente se vuelve repentinamente abrumadora.

Si tienes alguna pregunta o comentario sobre el Playground de OAuth o si usas OAuth con las API de Google, visita el Foro de asistencia sobre las API de G Suite y las API de Marketplace.

Recursos