Autenticación y autorización en el protocolo de datos de Google

Advertencia: Esta página trata sobre las APIs anteriores de Google, las APIs de Google Data, y solo es pertinente para las APIs que se enumeran en el directorio de las APIs de Google Data, muchas de las cuales se reemplazaron por APIs más nuevas. Para obtener información sobre una API nueva específica, consulta su documentación. Para obtener información sobre cómo autorizar solicitudes con una API más reciente, consulta Autenticación y autorización de Cuentas de Google.

Las aplicaciones de terceros suelen requerir acceso limitado a la Cuenta de Google de un usuario para ciertos tipos de actividad. Para garantizar que no se abuse de los datos del usuario, el titular de la cuenta debe aprobar todas las solicitudes de acceso. El control de acceso tiene dos componentes: autenticación y autorización.

Los servicios de autenticación permiten que los usuarios accedan a tu aplicación con una Cuenta de Google.

Los servicios de autorización permiten que los usuarios le proporcionen a tu aplicación acceso a los datos que almacenan en las aplicaciones de Google. Google se toma la privacidad en serio, y cualquier aplicación que requiera acceso a los datos de un usuario debe estar autorizada por él.

Los servicios de autenticación y autorización suelen denominarse en conjunto auth.

La autenticación y la autorización para las APIs de Google permiten que las aplicaciones de terceros obtengan acceso limitado a la Cuenta de Google de un usuario para ciertos tipos de actividades. En este documento, se presentan los mecanismos de autenticación disponibles y se describe lo que cada uno proporciona a tu aplicación.

  • El Acceso con Google ofrece una forma sencilla de permitir que las personas usen sus credenciales de Google para acceder a tu sitio. Incluye un conjunto de herramientas que son fáciles de integrar en diferentes dispositivos.
  • OAuth 2.0 es un protocolo de autorización para todas las APIs de Google. Para la seguridad, OAuth 2.0 se basa en SSL, en lugar de exigir que tu aplicación realice la firma criptográfica directamente. Este protocolo permite que tu aplicación solicite acceso a los datos asociados con la Cuenta de Google de un usuario.
  • Acceder con OAuth 2.0 (OpenID Connect) autentica a los usuarios haciéndolos acceder con sus Cuentas de Google. Esta es una alternativa a OpenID, y los usuarios de OpenID deben planificar la migración a Acceder con OAuth 2.0.

Si tu aplicación es un gadget (para usar en iGoogle o en otros contenedores de OpenSocial), consulta la sección Autenticación para gadgets.

Nota: El objetivo de este documento es proporcionar una descripción general de cada método de autenticación. Para obtener información detallada sobre cada método, consulta la documentación completa de las APIs de autenticación de la Cuenta de Google.

También puedes consultar el Grupo de la API de Cuentas de Google para debatir sobre el uso de las APIs de Cuentas de Google.

OAuth: Autorización para aplicaciones web y aplicaciones instaladas

Muchos servicios de Google permiten el acceso de terceros a los datos generados por los usuarios, como los datos de Calendar o Documentos, siempre y cuando el usuario autorice el acceso. Esta función permite que los usuarios compartan e intercambien datos entre sus aplicaciones de Google y aplicaciones de terceros para diversos fines.

Google admite dos versiones de OAuth para obtener acceso autorizado a los datos de un usuario de Google: OAuth 1.0 y OAuth 2.0, que ofrecen acceso a aplicaciones web y aplicaciones instaladas.

OAuth 2.0 para aplicaciones web y aplicaciones instaladas

Las aplicaciones web o instaladas pueden usar el nuevo y simplificado protocolo OAuth 2.0 para autorizar el acceso a los datos asociados con una Cuenta de Google. Para obtener detalles y ejemplos sobre cómo implementar OAuth 2.0 con Google, consulta nuestra documentación sobre OAuth 2.0.

OAuth 1.0 para aplicaciones web

Las aplicaciones web que necesitan acceso autorizado a los datos asociados con una Cuenta de Google o una cuenta de Google Apps pueden usar la implementación de Google de la API de OAuth. Para obtener información completa sobre la implementación de OAuth para aplicaciones basadas en la Web, incluidos ejemplos, consulta la guía de OAuth para aplicaciones web o la descripción general en este documento.

OAuth 1.0 para aplicaciones instaladas

Las aplicaciones instaladas en las computadoras y los dispositivos móviles de los usuarios pueden usar OAuth para autorizar el acceso a los datos asociados con una Cuenta de Google. Para obtener información completa sobre la implementación de OAuth para aplicaciones instaladas, consulta la guía OAuth para aplicaciones instaladas o la descripción general en este documento.

Cómo usar OAuth con aplicaciones web

Todas las APIs de datos de Google admiten OAuth, un estándar abierto para autorizar el uso de datos en aplicaciones web. Todas las aplicaciones web que realizan solicitudes de OAuth deben subir un certificado de seguridad y registrarse en Google. Consulta Registro de aplicaciones basadas en la Web para obtener más información.

Las bibliotecas cliente de las APIs de datos de Google proporcionan métodos para ayudarte a usar OAuth en tu aplicación web. Específicamente, existen métodos para construir el token de solicitud, autorizar el token de solicitud y cambiar el token de solicitud autorizado por un token de acceso. Las bibliotecas también controlan los algoritmos de firma necesarios cuando se realizan solicitudes a un servicio de Google Data. Para obtener ejemplos detallados sobre cómo usar OAuth con las bibliotecas cliente de las APIs de datos de Google,consulta Cómo usar OAuth con las bibliotecas cliente de las APIs de datos de Google.

El proceso de autorización de OAuth

El proceso de autorización de OAuth implica una serie de interacciones entre tu aplicación web, los servidores de autorización de Google y el usuario final.

En un nivel básico, el proceso es el siguiente:

  1. Tu aplicación solicita acceso y obtiene un token de solicitud no autorizado del servidor de autorización de Google.
  2. Google le pide al usuario que te otorgue acceso a los datos requeridos.
  3. Tu aplicación obtiene un token de solicitud autorizado del servidor de autorización.
  4. Intercambias el token de solicitud autorizado por un token de acceso.
  5. Usas el token de acceso para solicitar datos de los servidores de acceso a servicios de Google.

Cuando tu aplicación solicita acceso a los datos de un usuario por primera vez, Google emite un token de solicitud no autorizado para tu aplicación.

Si el usuario aún no accedió, Google le solicitará que lo haga. Luego, Google muestra una página de autorización que permite al usuario ver a qué datos de los servicios de Google solicita acceso tu aplicación.

Si el usuario aprueba la solicitud de acceso de tu aplicación, Google emitirá un token de solicitud autorizado. Cada token de solicitud solo es válido durante una hora. Solo se puede intercambiar un token de solicitud autorizado por un token de acceso, y este intercambio solo se puede realizar una vez por cada token de solicitud autorizado.

De forma predeterminada, los tokens de acceso tienen una duración prolongada. Cada token de acceso es específico para la cuenta de usuario especificada en la solicitud original de autorización y otorga acceso solo a los servicios especificados en esa solicitud. Tu aplicación debe almacenar el token de acceso de forma segura, ya que se requiere para acceder a los datos del usuario.

Preparación para OAuth

Antes de configurar tu aplicación para que use el servicio de autorización de Google con OAuth, debes completar las siguientes tareas.

Cómo decidir si registrar tu aplicación web

Para brindarles a tus usuarios garantías adicionales sobre la seguridad de sus datos, puedes registrar tu aplicación web en Google y firmar tus solicitudes con el certificado de seguridad registrado. Algunos feeds de las APIs de datos de Google solo están disponibles para las aplicaciones registradas. Consulta la documentación de la API de Google Data que te interese para determinar si solo funciona con aplicaciones registradas.

Tu aplicación debe firmar cada solicitud de OAuth que realice. Si eliges usar una firma RSA-SHA1 para firmar tus solicitudes, debes subir un certificado de seguridad como parte del proceso de registro.

Como alternativa, puedes usar una firma HMAC-SHA1 para firmar tus solicitudes. No se requiere ningún certificado para las firmas HMAC-SHA1. En cambio, Google genera un valor de consumer secret de OAuth, que se muestra en la página de registro de tu dominio después de que te registres.

Para obtener más información sobre el proceso de registro, consulta Registro de aplicaciones web.

Cómo determinar el alcance de los datos a los que accederá tu aplicación

Cada servicio de Google establece límites en el acceso que permite a través de las APIs de datos de Google. Este acceso se expresa como un valor de alcance. Algunos servicios proporcionan una variedad de valores de alcance para permitir que el usuario elija qué aplicaciones deben tener acceso a qué datos. Para obtener información sobre los valores de alcance disponibles para el servicio de Google al que deseas acceder, consulta la documentación de ese servicio.

En general, debes solicitar un token para el alcance más reducido que incluya los datos que necesitas. Por ejemplo, si tu aplicación requiere acceso al feed "Todos los calendarios" del usuario, debes solicitar un token para el alcance http://www.google.com/calendar/feeds/default/allcalendars/full.

Configurar un mecanismo para administrar tokens de OAuth

Cuando obtienes un token de acceso de OAuth para los datos de un usuario, debes usar ese token de acceso para todas las interacciones futuras con el servicio de Google especificado en nombre del usuario.

Tu aplicación debe administrar el almacenamiento de tokens de forma segura, lo que incluye hacer un seguimiento del servicio de Google para el que es válido cada token. Si necesitas acceder a más de un servicio de Google, puedes obtener varios tokens de acceso, pero no más de diez por usuario y aplicación en cualquier momento.

Si tu aplicación admite varias cuentas de usuario, debes hacer un seguimiento de la cuenta con la que se asocia cada token. Cada token de OAuth es específico del usuario que autorizó el acceso. Tu aplicación debe poder asociar un token con el usuario correcto. Una forma de administrar esto es emitir una cookie para el usuario antes de realizar la solicitud de token. Después de que el usuario otorga acceso a los datos solicitados, Google envía un token de solicitud autorizado y lo redirecciona a tu aplicación. Luego, puedes usar la cookie de tu aplicación para asociar el token con el usuario correcto.

Cómo configurar un mecanismo para solicitar acceso a un servicio de Google

Cada solicitud a un servicio de Google debe estar firmada y debe incluir un token de acceso de OAuth válido. En general, cada solicitud se realiza en forma de una solicitud HTTP GET, con el token de acceso y la firma incluidos en el encabezado. Las solicitudes que escriben datos nuevos deben usar HTTP POST.

Para obtener más información sobre el formato de solicitud adecuado para cada API de datos de Google, consulta la documentación de esa API.

Implementa OpenID (opcional)

Si implementas OpenID para la autenticación de usuarios, considera usar el protocolo híbrido para combinar los dos procesos. Con OpenID+OAuth, las tareas de obtener un token de solicitud y autorizarlo se controlan como parte de la solicitud de OpenID con extensiones de OAuth. Al igual que con OAuthGetRequestToken, estas extensiones se usan para identificar los servicios de Google a los que se accederá. Una respuesta correcta a la solicitud de OpenID contiene un token de solicitud autorizado. Una vez que se recibe este token, usa OAuthGetAccessToken para intercambiarlo por un token de acceso.

Trabaja con tokens de OAuth

Para usar OAuth, tu aplicación debe generar llamadas de solicitud de tokens firmadas y bien formadas, y controlar las respuestas, para la siguiente secuencia:

  1. Obtén un token de solicitud no autorizado (OAuthGetRequestToken)
  2. Autoriza el token de solicitud (OAuthAuthorizeToken).
  3. Intercambia el token de solicitud autorizado por un token de acceso (OAuthGetAccessToken)

Todas las solicitudes de OAuth deben estar firmadas, independientemente de si tu aplicación está registrada. Para obtener más información, consulta Cómo firmar solicitudes de OAuth.

Puedes experimentar con la solicitud y recepción de tokens de autorización en OAuth Playground.

Para obtener documentación detallada, consulta la referencia de la API de OAuth.

Cómo configurar una URL de devolución de llamada

Puedes especificar un valor para oauth_callback en una solicitud de OAuthGetRequestToken para determinar a dónde Google redirecciona al usuario después de que autoriza tu solicitud de acceso. La URL de devolución de llamada puede incluir parámetros de consulta. El redireccionamiento incluirá los mismos parámetros de consulta, así como el token de solicitud autorizado, que tu aplicación debe poder analizar.

Por ejemplo, cuando admites varios idiomas, puedes incluir un parámetro de búsqueda que identifique la versión de la aplicación que está viendo un usuario. Un valor oauth_callback de "http://www.yoursite.com/Retrievetoken?Lang=de" generaría el redireccionamiento "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Analizar el token y el parámetro de idioma garantiza que se redireccione al usuario a la versión correcta del sitio.

Si no se incluye el parámetro oauth_callback, Google dirigirá al usuario a una página web que muestre un número de verificación (consulta el ejemplo) después de autorizar tu solicitud de acceso. El usuario debe volver manualmente a tu aplicación y, luego, ingresar el número de verificación para que puedas obtener un token de solicitud autorizado.

Cómo identificar tu aplicación para los usuarios

Normalmente, Google muestra el nombre de una aplicación cuando solicita el consentimiento de acceso al usuario (consulta el ejemplo).

Si tu aplicación no está registrada, usa el parámetro xoauth_displayname en tu solicitud OAuthGetRequestToken para especificar el nombre de tu aplicación. Si no se especifica ese parámetro, Google muestra el nombre de dominio de la URL proporcionada por el parámetro oauth_callback. Si no se proporciona una URL de devolución de llamada, Google muestra la cadena "anónimo".

No establezcas este parámetro si tu aplicación está registrada. De forma predeterminada, Google muestra el nombre visible especificado durante el registro. Si estableces un nombre visible en tu solicitud de OAuthGetRequestToken, Google usará este en lugar de tu nombre visible registrado y mostrará un mensaje que indica que no se puede verificar la identidad de tu aplicación.

Nota: Para establecer el parámetro xoauth_displayname en OAuth Playground, marca la casilla "Avanzado" antes de recuperar el token de solicitud.

Trabaja con dominios de Google Apps

Si tu aplicación está diseñada para usuarios de un dominio de Cuentas de Google alojadas, considera usar el parámetro hd cuando autorices un token. Para obtener más información sobre el parámetro hd, consulta Cómo controlar usuarios con varias cuentas.

Más información sobre OAuth

Para obtener información detallada sobre la implementación de OAuth por parte de Google, incluido cómo registrar tu aplicación y crear los parámetros de OAuth necesarios, consulta estos recursos adicionales:

Volver al principio

Uso de OAuth con aplicaciones instaladas

Todas las APIs de datos de Google admiten OAuth, un estándar abierto para autorizar el uso de datos en aplicaciones. Las aplicaciones instaladas no necesitan registrarse en Google para usar OAuth.

El proceso de autorización de OAuth

El proceso de autorización de OAuth implica una serie de interacciones entre tu aplicación, los servidores de autorización de Google y el usuario final.

En un nivel básico, el proceso es el siguiente:

  1. Tu aplicación solicita acceso y obtiene un token de solicitud no autorizado del servidor de autorización de Google.
  2. Google le pide al usuario que te otorgue acceso a los datos requeridos.
  3. Tu aplicación obtiene un token de solicitud autorizado del servidor de autorización.
  4. Intercambias el token de solicitud autorizado por un token de acceso.
  5. Usas el token de acceso para solicitar datos de los servidores de acceso a servicios de Google.

Cuando tu aplicación solicita acceso a los datos de un usuario por primera vez, Google emite un token de solicitud no autorizado para tu aplicación.

Si el usuario aún no accedió, Google le solicitará que lo haga. Luego, Google muestra una página de autorización que permite al usuario ver a qué datos de los servicios de Google solicita acceso tu aplicación.

Si el usuario aprueba la solicitud de acceso de tu aplicación, Google emitirá un token de solicitud autorizado. Cada token de solicitud solo es válido durante una hora. Solo se puede intercambiar un token de solicitud autorizado por un token de acceso, y este intercambio solo se puede realizar una vez por cada token de solicitud autorizado.

OAuth admite aplicaciones instaladas que usan el modo no registrado. Dado que existen varios métodos para obtener un token de solicitud autorizado, tu app puede usar OAuth para autorizar una aplicación incluso si el dispositivo en el que está instalada no tiene un navegador web.

De forma predeterminada, los tokens de acceso tienen una duración prolongada. Cada token de acceso es específico para la cuenta de usuario especificada en la solicitud original de autorización y otorga acceso solo a los servicios especificados en esa solicitud. Tu aplicación debe almacenar el token de acceso de forma segura, ya que se requiere para acceder a los datos del usuario.

Preparación para OAuth

Antes de configurar tu aplicación para que use el servicio de autorización de Google con OAuth, debes completar las siguientes tareas.

Cómo determinar el alcance de los datos a los que accederá tu aplicación

Cada servicio de Google establece límites en el acceso que permite a través de las APIs de datos de Google. Este acceso se expresa como un valor de alcance. Algunos servicios proporcionan una variedad de valores de alcance para permitir que el usuario elija qué aplicaciones deben tener acceso a qué datos. Para obtener información sobre los valores de alcance disponibles para el servicio de Google al que deseas acceder, consulta la documentación de ese servicio.

En general, debes solicitar un token para el alcance más reducido que incluya los datos que necesitas. Por ejemplo, si tu aplicación requiere acceso al feed "Todos los calendarios" del usuario, debes solicitar un token para el alcance http://www.google.com/calendar/feeds/default/allcalendars/full.

Configurar un mecanismo para administrar tokens de OAuth

Cuando obtienes un token de acceso de OAuth para los datos de un usuario, debes usar ese token de acceso para todas las interacciones futuras con el servicio de Google especificado en nombre del usuario.

Tu aplicación debe administrar el almacenamiento de tokens de forma segura, lo que incluye hacer un seguimiento del servicio de Google para el que es válido cada token.

Si tu aplicación admite varias cuentas de usuario, debes hacer un seguimiento de la cuenta con la que se asocia cada token.

Cómo configurar un mecanismo para solicitar acceso a un servicio de Google

Cada solicitud a un servicio de Google debe estar firmada y debe incluir un token de acceso de OAuth válido. En general, cada solicitud se realiza en forma de una solicitud HTTP GET, con el token de acceso y la firma incluidos en el encabezado. Las solicitudes que escriben datos nuevos deben usar HTTP POST.

Para obtener más información sobre el formato de solicitud adecuado para cada API de datos de Google, consulta la documentación de esa API.

Trabaja con tokens de OAuth

Para usar OAuth, tu aplicación debe generar llamadas de solicitud de tokens firmadas y bien formadas, y controlar las respuestas, para la siguiente secuencia:

  1. Obtén un token de solicitud no autorizado (OAuthGetRequestToken)
  2. Autoriza el token de solicitud (OAuthAuthorizeToken).
  3. Intercambia el token de solicitud autorizado por un token de acceso (OAuthGetAccessToken)

Todas las solicitudes de OAuth deben estar firmadas, independientemente de si tu aplicación está registrada. Para obtener más información, consulta Cómo firmar solicitudes de OAuth. Las aplicaciones instaladas deben seguir las instrucciones de una aplicación no registrada.

Puedes experimentar con la solicitud y recepción de tokens de autorización en OAuth Playground.

Para obtener documentación detallada, consulta la referencia de la API de OAuth.

Cómo identificar tu aplicación para los usuarios

Normalmente, Google muestra el nombre de una aplicación cuando solicita el consentimiento de acceso al usuario (consulta el ejemplo).

Usa el parámetro xoauth_displayname en tu solicitud OAuthGetRequestToken para especificar el nombre de tu aplicación. Si no se especifica ese parámetro, Google muestra el nombre de dominio de la URL proporcionada por el parámetro oauth_callback. Si no se proporciona una URL de devolución de llamada, Google muestra la cadena "anónimo".

Nota: Para establecer el parámetro xoauth_displayname en OAuth Playground, marca la casilla "Avanzado" antes de recuperar el token de solicitud.

Cómo iniciar un navegador web

Como parte del proceso de autorización de OAuth, tu aplicación debe realizar una solicitud OAuthAuthorizeToken. Luego, el usuario debe acceder a una página web de Google y autorizar la solicitud de acceso de tu aplicación.

  • El modo AutoDetect se debe usar para la mayoría de las aplicaciones.
  • El modo de dispositivo se debe usar para las aplicaciones que no pueden iniciar un navegador web completo.
  • El modo de desarrollo solo se debe usar durante las primeras etapas del desarrollo.

Modo AutoDetect

Si es posible, tu aplicación debe iniciar una ventana del navegador y realizar una solicitud OAuthAuthorizeToken para abrir la página de Google. Cuando Google devuelve el token autorizado, tu aplicación debe detectar esto y recuperar el enfoque del navegador web.

Este modo requiere que proporciones una URL de devolución de llamada a la que se redirecciona al usuario después de que autoriza tu solicitud de acceso. Esta URL se debe proporcionar como el parámetro oauth_callback de la solicitud OAuthGetRequestToken y como el parámetro verifier de la solicitud OAuthGetAccessToken.

Para mejorar la experiencia del usuario, tu aplicación debe intentar detectar automáticamente cuando se redirecciona al usuario a esta URL y, de inmediato, pasar a primer plano y realizar una solicitud de OAuthGetAccessToken para completar el proceso de OAuth.

Para obtener más información y conocer las prácticas recomendadas, consulta Aprobación con detección automática.

Si tu aplicación no puede detectar automáticamente cuándo se redirecciona al usuario a la URL de devolución de llamada o no puede pasar a primer plano, la URL de devolución de llamada debe mostrar una página que explique cómo pasar tu aplicación a primer plano y cómo iniciar la solicitud OAuthGetAccessToken desde tu aplicación.

Modo del dispositivo

Si tu aplicación no puede iniciar un navegador web completo, los dispositivos de cliente enriquecido también pueden autorizar sin un navegador web.

Este modo permite que un desarrollador configure un sitio web en el que un usuario pueda autorizar la solicitud de acceso. Después de la autorización, el usuario recibe un código generado por Google y se lo redirecciona al sitio del desarrollador. En este sitio, se debe explicar al usuario cómo ingresar el código en su dispositivo para completar el proceso de autorización.

Modo de desarrollo

Se recomienda usar este modo solo durante el desarrollo inicial de una aplicación.

Al igual que en el modo AutoDetect, tu aplicación debe iniciar un navegador y el usuario debe autorizar tu solicitud. Sin embargo, en lugar de crear una página web para la URL de devolución de llamada, puedes establecer el valor del parámetro oauth_callback en "oob" (fuera de banda).

En ese caso, después de que el usuario autorice tu solicitud, Google lo dirigirá a una página de Cuentas de Google que muestra un número de verificación (consulta el ejemplo).

El usuario debe volver a tu aplicación y, luego, ingresar el número de verificación para que puedas realizar una solicitud de OAuthGetAccessToken.

Más información sobre OAuth

Para obtener información detallada sobre la implementación de OAuth por parte de Google, incluido cómo registrar tu aplicación y crear los parámetros de OAuth necesarios, consulta estos recursos adicionales:

Volver al principio

Usa AuthSub para la autorización

AuthSub es una API de autorización patentada de Google que está disponible como alternativa a OAuth para la mayoría de las APIs de Google. Si es posible, debes evitar el uso de AuthSub. Si ya tienes aplicaciones que usan AuthSub, debes migrar a OAuth o al protocolo híbrido.

El proceso de autorización de AuthSub

La autorización con AuthSub implica una secuencia de interacciones entre tres entidades: la aplicación web, los servicios de Google y el usuario. En este diagrama, se ilustra la secuencia:

Proceso de autorización

  1. Cuando la aplicación web necesita acceder a un servicio de Google del usuario, realiza una llamada a AuthSub al servicio de proxy de autorización de Google.
  2. El servicio de autorización responde con una página de solicitud de acceso. En esta página administrada por Google, se le solicita al usuario que otorgue o rechace el acceso a su servicio de Google. Es posible que primero se le solicite al usuario que acceda a su cuenta.
  3. El usuario decide si otorga o deniega el acceso a la aplicación web. Si el usuario rechaza el acceso, se lo dirige a una página de Google en lugar de volver a la aplicación web.
  4. Si el usuario otorga acceso, el servicio de autorización lo redirecciona a la aplicación web. El redireccionamiento contiene un token de autorización válido para un solo uso, que se puede intercambiar por un token de larga duración.
  5. La aplicación web se comunica con el servicio de Google con una solicitud y usa el token de autorización para actuar como agente del usuario.
  6. Si el servicio de Google reconoce el token, proporciona los datos solicitados.

Cómo trabajar con AuthSub

Para incorporar AuthSub en tu aplicación web, debes realizar las siguientes tareas:

  1. Decide si registrarás o no tu aplicación web.

    Las aplicaciones web registradas tienen la ventaja de ser reconocidas por Google, por lo que se modifica u omite la advertencia estándar que se muestra a los usuarios en la página de acceso de Google. Además, las aplicaciones web registradas se identifican con un nombre descriptivo en lugar de solo la URL de llamada. Ten en cuenta que algunos servicios de Google solo permiten un acceso limitado a las aplicaciones web no registradas. Si decides registrarte, usa este proceso de registro automatizado.

    Si te registras, también puedes proporcionar un certificado de seguridad y claves. Las aplicaciones web registradas que tienen un certificado en el archivo pueden adquirir tokens seguros para usarlos cuando solicitan datos de un servicio de Google. (También pueden usar tokens no seguros si es necesario).

  2. Decide qué tipo de tokens usar y cómo administrarlos.

    El token de autorización que se recibe de Google está diseñado para usarse en todas las interacciones futuras con el servicio de Google especificado para ese usuario. El tipo de token que elijas usar (de un solo uso o de sesión) depende del tipo de interacciones que tendrá tu aplicación web con un servicio de Google. Por ejemplo, un token de un solo uso puede ser suficiente si la interacción es un evento único o poco frecuente.

    Si decides obtener tokens de sesión y usarlos con regularidad para acceder al servicio de Google, tu aplicación web deberá administrar el almacenamiento de tokens, incluido el seguimiento del usuario y el servicio de Google para el que el token es válido. Las Cuentas de Google no están configuradas para administrar grandes cantidades de tokens y, de hecho, no permiten que haya más de diez tokens válidos (por usuario y por aplicación web) pendientes en un momento determinado. Esta limitación permite que una aplicación web obtenga varios tokens para cubrir diferentes servicios, si es necesario, pero no admite la obtención de un token nuevo cada vez que la aplicación web necesita acceder a un servicio de Google. Si decides almacenar tokens de sesión, estos deben tratarse con la misma seguridad que cualquier otra información sensible almacenada en el servidor.

    Como alternativa, puedes optar por obtener tokens nuevos de forma periódica, siempre y cuando configures un mecanismo de revocación de tokens. Tu aplicación deberá revocar el token existente antes de solicitar otro. En este caso, el usuario deberá acceder y otorgar acceso cada vez que se solicite un token nuevo.

  3. Determina el alcance que requiere el servicio de Google al que se accederá.

    Cada servicio de Google determina cuánto y qué tipo de acceso permitirá. Este acceso se expresa como un valor de alcance. El alcance de un servicio puede ser una URL simple que identifica todo el servicio o puede especificar un acceso más restringido. Algunos servicios limitan severamente el acceso, por ejemplo, permiten el acceso de solo lectura a información limitada. Para obtener los permisos permitidos para el servicio de Google al que deseas acceder, consulta la documentación de ese servicio. Debes solicitar el token con el alcance más limitado posible. Por ejemplo, si intentas acceder a la función de feeds Atom de Gmail, usa el alcance "http://www.google.com/calendar/feeds/", no "http://www.google.com/calendar/". Los servicios de Google son mucho más restrictivos con las solicitudes de gran alcance.

  4. Configura un mecanismo para solicitar y recibir un token de autorización.

    El mecanismo debe generar una llamada AuthSubRequest bien formada, lo que incluye especificar los valores de URL next y scope adecuados (determinados en el paso 3). Si usas tokens seguros o administras tokens de sesión, la solicitud también debe incluir valores para estas variables.

    La siguiente URL puede incluir parámetros de consulta. Por ejemplo, cuando se admiten varios idiomas, incluye un parámetro de consulta que identifique la versión de la aplicación web que el usuario está viendo. Un valor next de http://www.yoursite.com/Retrievetoken?Lang=de generaría el redireccionamiento http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. Analizar el token y el parámetro Lang garantiza que se redireccione al usuario a la versión correcta del sitio.

    En ciertas circunstancias, usar el parámetro hd puede ayudar a optimizar la experiencia de los usuarios cuando se les solicita que otorguen acceso en el sitio de Cuentas de Google. En la mayoría de los casos, el proceso es tan simple como acceder a la cuenta y elegir si se otorga acceso o no. Sin embargo, los usuarios que tienen más de una Cuenta de Google (una cuenta de Gmail normal o una o más cuentas alojadas de Google Apps) tal vez deban seguir el proceso adicional de "acceso universal" para identificar a qué cuenta desean acceder. Si tu aplicación está diseñada para un dominio administrado en particular, puedes eliminar estos pasos adicionales usando este parámetro para identificar ese dominio. También puedes usar el parámetro hd si tu aplicación accede a servicios que no están disponibles en cuentas alojadas. Si configuras el valor como "default", se limitará la autorización solo a las cuentas normales. Cuando se establece el valor hd, Google seleccionará automáticamente la cuenta correcta para la autorización.

    El mecanismo de tokens debe estar equipado para analizar el redireccionamiento que recibe de Google, que contiene el token de un solo uso, y tomar medidas con él. Dado que los tokens de autorización son específicos para un usuario, tu aplicación debe poder asociar un token con su usuario. La opción preferida es emitir una cookie para el usuario antes de realizar la solicitud de token. Luego, cuando Google redirecciona al usuario a tu sitio con un token agregado, tu aplicación puede leer la cookie y asociar el token con la identificación de usuario correcta.

  5. Configura mecanismos para solicitar tokens de sesión y almacenarlos o revocarlos, si es pertinente.

    Según las decisiones que hayas tomado en el paso 2 sobre la administración de tokens, es posible que debas crear mecanismos para obtener y revocar tokens de sesión (AuthSubSessionToken y AuthSubRevokeToken). Para probar los mecanismos de sesión y revocación, usa AuthSubTokenInfo, que indica si un token determinado es válido o no. Si almacena tokens, la aplicación debe hacer un seguimiento del ID del usuario y del servicio (alcance) que cubre el token.

  6. Configura un mecanismo para solicitar acceso a un servicio de Google.

    Consulta la documentación del servicio de Google para obtener información sobre el formato de solicitud adecuado. Todas las solicitudes a un servicio de Google deben incluir un token de autorización válido. En general, una solicitud a un servicio de Google se realiza en forma de una solicitud HTTP GET (o POST si se escriben datos nuevos), con el token al que se hace referencia en el encabezado de la solicitud.

    El encabezado de la solicitud debe tener el siguiente formato:

    Authorization: AuthSub token="token"

    donde token es el token de autorización, de un solo uso o de sesión, que se recibe de Google en respuesta a una solicitud de AuthSub. Si el token es seguro, debe incluir una firma digital. Consulta "Cómo firmar solicitudes" para obtener instrucciones y ejemplos.

    En el siguiente ejemplo, se ilustra un encabezado de solicitud para una llamada al servicio de feeds de Google Calendar. Esta solicitud contiene un token no seguro: 

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

Más información sobre AuthSub

Para obtener información sobre AuthSub, incluido el registro de tu aplicación en Google y una explicación detallada del intercambio de un token único por un token de sesión, consulta estos recursos adicionales:

Volver al principio

Usa ClientLogin para la autorización

ClientLogin es una API de autorización propietaria de Google, disponible como alternativa a OAuth para la mayoría de las APIs de Google. Si es posible, debes evitar el uso de ClientLogin. Si ya tienes aplicaciones que usan ClientLogin, debes migrar a OAuth o al protocolo híbrido.

Autenticación para aplicaciones instaladas: ClientLogin

ClientLogin permite que tus usuarios accedan a su Cuenta de Google desde tu aplicación. Luego, la aplicación se comunica con Google con los datos de acceso y solicita acceso a una API de datos de Google especificada. Una vez que se autentica correctamente la información de acceso, Google devuelve un token al que tu aplicación hará referencia cada vez que solicite acceso a la cuenta del usuario, por ejemplo, para obtener o publicar datos. El token sigue siendo válido durante un período determinado, que se define según el servicio de Google con el que trabajes.

Nota: Las bibliotecas cliente de las APIs de Google Data proporcionan métodos para ayudarte a usar ClientLogin en tus aplicaciones instaladas. Específicamente, existen métodos para adquirir un token de autenticación, controlar los desafíos de CAPTCHA, recuperar el token de autenticación para su uso posterior y enviar el encabezado Authorization correcto con cada solicitud. Si trabajas con una de las bibliotecas, consulta Usa ClientLogin con las bibliotecas cliente de las APIs de Google Data.

El proceso de autorización de ClientLogin

La autorización con ClientLogin implica una secuencia de interacciones entre tres entidades: la aplicación instalada, los servicios de Google y el usuario. En este diagrama, se ilustra la secuencia:

Proceso de autorización

  1. Cuando la aplicación de terceros necesita acceder a un servicio de Google del usuario, recupera el nombre de acceso y la contraseña del usuario.
  2. Luego, la aplicación de terceros realiza una llamada a ClientLogin al servicio de autorización de Google.
  3. Si el servicio de autorización de Google decide que es necesaria una verificación adicional, devuelve una respuesta de error con un token y un desafío de CAPTCHA, en forma de URL para una imagen de CAPTCHA.
  4. Si se recibe un desafío de CAPTCHA, la aplicación de terceros muestra la imagen de CAPTCHA al usuario y le solicita una respuesta.
  5. Si se solicita, el usuario envía una respuesta al desafío de CAPTCHA.
  6. La aplicación de terceros realiza una nueva llamada a ClientLogin, esta vez con la respuesta y el token de CAPTCHA (que se recibieron con la respuesta de error).
  7. En un intento de acceso exitoso (con o sin desafío CAPTCHA), el servicio de autorización de Google devuelve un token a la aplicación.
  8. La aplicación se comunica con el servicio de Google con una solicitud de acceso a los datos, haciendo referencia al token que recibió del servicio de autorización de Google.
  9. Si el servicio de Google reconoce el token, proporciona el acceso a los datos solicitado.

Cómo usar ClientLogin

Usa esta interfaz en tu aplicación instalada para acceder de forma programática a la Cuenta de Google de un usuario. Después de recopilar la información de acceso del usuario, llama a ClientLogin para solicitar acceso a su cuenta. Una vez que se autentica correctamente la información de acceso, Google devuelve un token al que tu aplicación hará referencia cada vez que solicite acceso a la cuenta del usuario. El token sigue siendo válido durante un período determinado, que se define según el servicio de Google con el que trabajes.

Para incorporar ClientLogin en tu aplicación, debes realizar las siguientes tareas:

  1. Crea un elemento de IU para capturar los datos de acceso del usuario.

    La IU debe solicitar un nombre de usuario (dirección de correo electrónico que incluya el dominio) y una contraseña. La IU también debe ser capaz de mostrar una imagen de CAPTCHA con la URL que recibe de Google, si es necesario, y solicitar una respuesta correcta del usuario. Lo ideal sería que tu IU incluyera un vínculo a la página de acceso de Cuentas de Google ("https://www.google.com/accounts/Login") en caso de que el usuario necesite registrarse en una cuenta nueva o realizar otro mantenimiento de la cuenta.

  2. Escribe código para generar una solicitud ClientLogin HTTPS POST bien formada y transmitirla.

    Este código debe contener lógica para controlar un desafío de CAPTCHA y debe incluir los parámetros logintoken y logincaptcha. La aplicación también debe poder detectar cuando el usuario omite información obligatoria o repite datos incorrectos después de un error de acceso, y mostrar un error sin enviar una solicitud superflua.

  3. Controlar las respuestas de Google

    Hay cuatro respuestas posibles a una solicitud de acceso:

    • Éxito (un HTTP 200)
    • falla (un error HTTP 403) con un código de error explicativo
    • Solicitud no válida, que generalmente se debe a una solicitud con formato incorrecto
    • falla con un desafío de CAPTCHA

    Una respuesta correcta contiene un token de autorización etiquetado como "Auth". Este token se debe incluir en todas las solicitudes posteriores al servicio de Google para esta cuenta. Los tokens de autorización deben protegerse cuidadosamente y no deben proporcionarse a ninguna otra aplicación, ya que representan el acceso a la cuenta del usuario. El límite de tiempo del token varía según el servicio que lo emitió.

    Una respuesta de error incluye uno o más códigos de error y una URL con el mensaje de error que se puede mostrar al usuario. Ten en cuenta que ClientLogin no diferencia entre una falla debido a una contraseña incorrecta y una debido a un nombre de usuario no reconocido (por ejemplo, si el usuario aún no se registró para obtener una cuenta). Tu aplicación debe controlar todos los mensajes de error posibles según corresponda.

    Una respuesta de error con un desafío de CAPTCHA significa que Google decidió, por el motivo que sea, que se deben tomar medidas de seguridad adicionales. Esta respuesta se acompaña de una URL de imagen de CAPTCHA y un token que representa el desafío de CAPTCHA específico.

  4. Controla un desafío de CAPTCHA de Google.

    Para controlar el desafío, la aplicación debe mostrar la imagen de CAPTCHA y solicitar una respuesta del usuario. Para mostrar la imagen de CAPTCHA, usa el valor de CaptchaUrl que se devolvió con la respuesta de error y agrégale el prefijo de la URL de Cuentas de Google: "http://www.google.com/accounts/". Una vez que el usuario proporciona una respuesta, la aplicación debe volver a enviar la solicitud de acceso, esta vez con el token de CAPTCHA (logintoken) y la respuesta del usuario (logincaptcha). Google valida la respuesta del usuario antes de autorizar el acceso a la cuenta.

    Existe una alternativa para los desarrolladores que no desean administrar el proceso de obtención y transmisión de una respuesta de CAPTCHA del usuario. En respuesta a un desafío CAPTCHA, la aplicación puede dirigir al usuario a la página alojada por Google: "https://www.google.com/accounts/DisplayUnlockCaptcha". Una vez que el usuario responde correctamente al desafío, el servidor de Google confía en la computadora que se está usando. Luego, la aplicación puede volver a enviar la solicitud de acceso original para obtener el token de autorización.

    5. Nota: Google no valida el intento de acceso antes de emitir un desafío de CAPTCHA. Esto significa que un intento de acceso podría fallar incluso después de un desafío CAPTCHA.

* CAPTCHA es una marca comercial de Carnegie Mellon University.

Volver al principio

Autenticación para gadgets

Proxy de OAuth

Si compilas un gadget con la API de Gadgets estándar, puedes aprovechar una función de la plataforma de gadgets llamada proxy de OAuth para acceder a las APIs de Google Data. OAuth (descrito anteriormente) es un estándar de autenticación que permite a los usuarios acceder a sus datos privados en un servicio de alojamiento de gadgets, como iGoogle, MySpace o Orkut, o compartir sus datos con otro sitio web o gadget. El proxy de OAuth está diseñado para facilitar el desarrollo a los desarrolladores de gadgets, ya que oculta muchos de los detalles de autenticación de OAuth. El proxy se basa en un proyecto de código abierto llamado Shindig, que es una implementación de la especificación de gadgets.

Nota: El proxy de OAuth solo se admite para los gadgets que usan la API de gadgets.* y se ejecutan en contenedores de OpenSocial. No es compatible con la API de gadgets heredados.

Flujo de autenticación

Tu gadget debe obtener un token de OAuth antes de poder acceder a los datos de un usuario. El proxy de OAuth administra el flujo de autenticación por ti. La primera vez que un usuario instala tu gadget, se lleva a cabo el siguiente proceso:

  1. Tu gadget se carga por primera vez y trata de acceder a los datos del usuario con una de las APIs de Google Data.
  2. La solicitud falla porque el usuario no otorgó acceso. El objeto de respuesta contiene una URL (en response.oauthApprovalUrl) para la página de aprobación de OAuth. Tu gadget debe proporcionar un método para iniciar una ventana nueva con esa URL.
  3. En la página de aprobación, el usuario elige otorgar o denegar el acceso a tu gadget. Si la operación se realiza correctamente, se dirigirá al usuario a la página oauth_callback que especifiques. Para obtener la mejor experiencia del usuario, usa http://oauth.gmodules.com/gadgets/oauthcallback.
  4. A continuación, el usuario cierra la ventana emergente. Para notificar a tu gadget que el usuario aprobó la acción, puedes usar un controlador de ventanas emergentes para detectar el cierre de la ventana de aprobación. Como alternativa, tu gadget puede mostrar un vínculo (p.ej., "Aprobé el acceso") para que el usuario haga clic en él después de que se cierre esta ventana.
  5. Tu gadget intenta acceder a la API de Google Data por segunda vez solicitando nuevamente los datos del usuario. Este intento se realizó correctamente.
  6. El gadget se autenticó y puede comenzar a funcionar con normalidad.

Configuración del gadget

Para acceder a una o más APIs de datos de Google, primero debes indicarle a tu gadget que use OAuth como método de autenticación. Agrega un elemento <OAuth> en la sección <ModulePrefs> del código XML de tu gadget:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

En esta sección, solo cambia los siguientes parámetros de búsqueda:

scope
Es un parámetro obligatorio en la URL de la solicitud. Tu gadget puede acceder a los datos de los scope que se usan en este parámetro. En este ejemplo, el gadget puede acceder a los datos de Blogger y Calendario. Un gadget puede solicitar datos para un solo alcance o varios, como lo hace este ejemplo.
oauth_callback
: Es un parámetro opcional en la URL de autorización. La página de aprobación de OAuth redirecciona a esta URL después de que el usuario aprueba el acceso a los datos. Debes establecer este parámetro en http://oauth.gmodules.com/gadgets/oauthcallback para brindar la mejor experiencia del usuario cuando los usuarios instalen tu gadget. Esa página proporciona un fragmento de JavaScript que cierra automáticamente la ventana emergente. También puedes configurar este parámetro para que apunte a tu propia página "aprobada" o, simplemente, dejarlo en blanco.

Cómo acceder a un feed autenticado de la API de Google Data

Una vez que tu gadget autenticó al usuario, acceder a una API de Google Data es sencillo con la biblioteca cliente de JavaScript de las APIs de Google Data. Para obtener información sobre cómo usar la biblioteca en el proxy de OAuth, consulta Usa la biblioteca cliente de JavaScript.

Más información sobre los gadgets

Para obtener información completa sobre cómo crear gadgets de las APIs de datos de Google, incluidos detalles sobre el proxy de OAuth, un artículo sobre cómo comenzar y la especificación de gadgets.*, consulta estos recursos adicionales:

Volver al principio