Se usó la API de Cloud Translation para traducir esta página.

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

Advertencia: Esta página trata sobre las API anteriores de Google, las API de datos de Google, y solo es relevante para las API que aparecen en el directorio de las API de datos de Google, muchas de las cuales se reemplazaron con API más nuevas. Para obtener información sobre una API nueva específica, consulta la documentación de la API nueva. 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 a menudo requieren 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: la autenticación y la 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 proporcionen a tu aplicación acceso a los datos almacenados en las aplicaciones de Google. Google se toma en serio la privacidad, y cualquier aplicación que requiera acceso a los datos del usuario debe estar autorizada por este.

A menudo, los servicios de autenticación y autorización se conocen en conjunto como auth.

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

El Acceso con Google ofrece una manera simple de permitir que las personas usen sus credenciales de Google para acceder a tu sitio. Incluye un conjunto de herramientas fáciles de integrar en diferentes dispositivos.
OAuth 2.0 es un protocolo de autorización para todas las API 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 datos asociados con la cuenta de Google de un usuario.
Acceder con OAuth 2.0 (OpenID Connect) permite a los usuarios autenticarse con sus Cuentas de Google para autenticar. Se trata de un reemplazo de OpenID y los usuarios de OpenID deberían migrar a Login con OAuth 2.0.

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

Nota: En este documento, se proporciona 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 API de autenticación de cuentas de Google.

Consulta también el Grupo de API de cuentas de Google para debatir acerca del uso de las API de cuentas de Google.

OAuth: Autorización para aplicaciones web y aplicaciones instaladas

Muchos servicios de Google permiten el acceso de terceros a datos generados por el usuario, como datos de Calendario o Documentos, siempre que el acceso esté autorizado por el usuario. Esta función permite a los usuarios intercambiar y compartir datos entre sus aplicaciones de Google y aplicaciones de terceros para una variedad de propósitos.

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

OAuth 2.0 para aplicaciones web y de instalación

Las aplicaciones web o las aplicaciones instaladas pueden usar el nuevo protocolo simplificado de 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 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 los ejemplos, consulte la guía de OAuth para aplicaciones web o consulte la descripción general en este documento.

OAuth 1.0 para aplicaciones instaladas

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

Uso de OAuth con aplicaciones web

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

Las bibliotecas cliente de las API 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 e intercambiar el token de solicitud autorizado por un token de acceso. Las bibliotecas también controlan los algoritmos de firma necesarios cuando realizan solicitudes a un servicio de datos de Google. Para obtener ejemplos extensos sobre cómo usar OAuth con las bibliotecas cliente de la API de datos de Google,consulta Cómo usar OAuth con las bibliotecas cliente de las API de datos de Google.

El proceso de autorización de OAuth

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

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

Tu aplicación solicita acceso y obtiene un token de solicitud no autorizado del servidor de autorización de Google.
Google le solicita al usuario que le otorgue acceso a los datos requeridos.
Tu aplicación obtiene un token de solicitud autorizado del servidor de autorización.
Intercambia el token de solicitud autorizado por un token de acceso.
Usa el token de acceso para solicitar datos de los servidores de acceso del servicio de Google.

Cuando su aplicación solicita acceso inicialmente a los datos de un usuario, Google emite un token no autorizado de solicitud a su aplicación.

Si el usuario aún no accedió, Google le solicita que acceda. Luego Google muestra una página de autorización que le permite al usuario ver los datos del servicio de Google a los cuales tu aplicación está solicitando acceso.

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

De forma predeterminada, los tokens de acceso son de larga duración. Cada token de acceso es específico de la cuenta de usuario especificada en la solicitud de autorización original y otorga acceso solo a los servicios especificados en esa solicitud. Tu aplicación debe almacenar el token de acceso de manera segura, ya que es necesario para todo acceso a los datos de un usuario.

Prepárate para OAuth

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

Decide si deseas registrar tu aplicación web

Para brindar a tus usuarios garantías adicionales de 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 la API de datos de Google solo están disponibles para las aplicaciones registradas. Consulta la documentación de la API de datos de Google que te interesa determinar si la API 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 un certificado para las firmas HMAC-SHA1. En su lugar, Google genera un valor consumer secret para OAuth, que se muestra en la página de registro de tu dominio después de que te registras.

Para obtener más información sobre el proceso de registro, consulta Registro para 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 API de datos de Google. Este acceso se expresa como un valor de alcance. Algunos servicios proporcionan diversos valores de permiso para permitir que un usuario elija qué aplicaciones deben tener acceso a determinados datos. Para obtener información sobre los valores de permiso disponibles del servicio de Google al que quieres 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.

Configura un mecanismo para administrar los tokens de OAuth

Cuando obtienes un token de acceso de OAuth para los datos de un usuario, debes usarlo 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 manera segura, incluido el seguimiento del servicio de Google para el que cada token es válido. Si necesitas acceder a más de un servicio de Google, puedes obtener varios tokens de acceso, pero un máximo de diez.

Si tu aplicación admite varias cuentas de usuario, debes realizar un seguimiento de las cuentas con las 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 al usuario correcto. Una forma de administrar esto es emitir una cookie al 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, podrás usar la cookie de tu aplicación para asociar el token con el usuario correcto.

Configura 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 a fin de combinar los dos procesos. Con OpenID+OAuth, las tareas de obtener un token de solicitud y autorizarlo se manejan 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 reciba este token, usa OAuthGetAccessToken para intercambiarlo por un token de acceso.

Cómo trabajar con tokens OAuth

Para usar OAuth, tu aplicación debe generar llamadas de solicitud de token con el formato correcto y firmar las respuestas, y administrar las respuestas, de la siguiente secuencia:

Obtener un token de solicitud no autorizado (OAuthGetRequestToken)
Autoriza el token de solicitud (OAuthAutorizaToken)
Intercambiar el token de solicitud autorizado por un token de acceso (OAuthGetAccessToken)

Todas las solicitudes de OAuth deben estar firmadas, ya sea que tu aplicación esté registrada o no. Para obtener más información, consulta Cómo firmar solicitudes de OAuth.

Puedes experimentar con la solicitud y la 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 OAuthGetRequestToken a fin de determinar el lugar al que 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 búsqueda, así como el token de solicitud autorizado, que la aplicación debe poder analizar.

Por ejemplo, cuando admites varios idiomas, puedes incluir un parámetro de consulta que identifique la versión de la aplicación que está viendo un usuario. Un valor oauth_callback de "http://www.tusitio.com/Recuperartoken?Lang=de daría como resultado el redireccionamiento "http://www.tusitio.com/Recuperartoken?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 (ver ejemplo) después de autorizar tu solicitud de acceso. El usuario debe regresar manualmente a tu aplicación y, luego, ingresar el número de verificación antes de que puedas obtener un token de solicitud autorizado.

Identifica tu aplicación para los usuarios

Por lo general, Google muestra el nombre de una aplicación cuando solicita el consentimiento de acceso del usuario (ver ejemplo).

Si la aplicación no está registrada, usa el parámetro xoauth_displayname en la solicitud OAuthGetRequestToken para especificar el nombre de la aplicación. Si no se especifica ese parámetro, Google muestra el nombre de dominio de la URL que proporcionó el parámetro oauth_callback. Si no se proporciona una URL de devolución de llamada, Google muestra la string “anónima”.

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

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

Cómo trabajar con dominios de Google Apps

Si tu aplicación está diseñada para usuarios de un dominio alojado en Cuentas de Google, considera usar el parámetro hd cuando autorices un token. Para obtener más información sobre el parámetro hd, consulta Cómo administrar 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:

Usa OAuth con las bibliotecas cliente de las API de datos de Google
Artículo: Cómo usar OAuth con las API de datos de Google, incluida una descripción de OAuth Playground, una herramienta interactiva para probar OAuth.
OAuth para aplicaciones web (documentación completa)
Registro para aplicaciones basadas en la Web
Genera claves y certificados
Especificación de OAuth

Volver al principio

Uso de OAuth con aplicaciones instaladas

Todas las API de datos de Google admiten OAuth, un estándar abierto para autorizar el uso de datos en las aplicaciones. No es necesario que las aplicaciones instaladas estén registradas 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 su aplicación, los servidores de autorización de Google y el usuario final.

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

Tu aplicación solicita acceso y obtiene un token de solicitud no autorizado del servidor de autorización de Google.
Google le solicita al usuario que le otorgue acceso a los datos requeridos.
Tu aplicación obtiene un token de solicitud autorizado del servidor de autorización.
Intercambia el token de solicitud autorizado por un token de acceso.
Usa el token de acceso para solicitar datos de los servidores de acceso del servicio de Google.

Cuando su aplicación solicita acceso inicialmente a los datos de un usuario, Google emite un token no autorizado de solicitud a su aplicación.

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

Prepárate para OAuth

Antes de que puedas configurar tu aplicación para usar 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

Configura un mecanismo para administrar los tokens de OAuth

Cuando obtienes un token de acceso de OAuth para los datos de un usuario, debes usarlo 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 manera segura, incluido el seguimiento del servicio de Google para el que cada token es válido.

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

Configura un mecanismo para solicitar acceso a un servicio de Google

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.

Cómo trabajar con tokens OAuth

Para usar OAuth, tu aplicación debe generar llamadas de solicitud de token con el formato correcto y firmar las respuestas, y administrar las respuestas, de la siguiente secuencia:

Obtener un token de solicitud no autorizado (OAuthGetRequestToken)
Autoriza el token de solicitud (OAuthAutorizaToken)
Intercambiar el token de solicitud autorizado por un token de acceso (OAuthGetAccessToken)

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

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

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

Identifica tu aplicación para los usuarios

Por lo general, Google muestra el nombre de una aplicación cuando solicita el consentimiento de acceso del usuario (ver 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 que proporcionó el parámetro oauth_callback. Si no se proporciona una URL de devolución de llamada, Google muestra la string “anónima”.

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

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 de detección automática debe usarse para la mayoría de las aplicaciones.
Se debe usar Device Mode para las aplicaciones que no puedan iniciar un navegador web completo.
El modo de desarrollo solo debe usarse durante el desarrollo temprano.

Modo de detección automática

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 muestra el token autorizado, tu aplicación debe detectar esto y recuperar el foco desde el navegador web.

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

A fin de mejorar la experiencia del usuario, tu aplicación debe detectar de forma automática cuándo se redirecciona al usuario a esta URL y, luego, ponerse en primer plano y realizar una solicitud OAuthGetAccessToken para completar el proceso de OAuth.

Para obtener más información y las prácticas recomendadas, consulta Detección automática de la aprobación.

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 ubicarse en primer plano, la URL de devolución de llamada debe mostrar una página en la que se explique cómo llevar tu aplicación al 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, también es posible que los dispositivos de cliente enriquecido se autoricen sin un navegador web.

Este modo permite que un desarrollador configure un sitio web donde un usuario puede autorizar la solicitud de acceso. Después de la autorización, el usuario obtiene un código que generó Google y se lo redirecciona al sitio del desarrollador. Este sitio debe explicarle 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 configurar el valor del parámetro oauth_callback como "oob" (fuera de banda).

En ese caso, una vez que el usuario autoriza tu solicitud, Google lo dirige a la 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 antes de que puedas realizar una solicitud OAuthGetAccessToken.

Más información sobre OAuth

Usa OAuth con las bibliotecas cliente de las API de datos de Google
Artículo: Cómo usar OAuth con las API de datos de Google, incluida una descripción de OAuth Playground, una herramienta interactiva para probar OAuth.
OAuth para aplicaciones instaladas (documentación completa)
Genera claves y certificados
Especificación de OAuth

Volver al principio

Usa AuthSub para la autorización

AuthSub es una API de autorización de Google, disponible como alternativa a OAuth para la mayoría de las API de Google. Debes evitar usar AuthSub si es posible. 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

Cuando la aplicación web necesita acceder al servicio de Google de un usuario, realiza una llamada de AuthSub al servicio Proxy de autorización de Google.
El servicio de autorización responde con la presentación de una página de solicitud de acceso. Esta página administrada por Google 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.
El usuario decide si otorgará o no el acceso a la aplicación web. Si el usuario rechaza el acceso, se lo redirige a una página de Google en lugar de a la aplicación web.
Si el usuario otorga el acceso, el servicio de autorización redirecciona al usuario de nuevo a la aplicación web. El redireccionamiento contiene un token de autorización válido para un solo uso; se puede intercambiar por un token de larga duración.
La aplicación web se comunica con el servicio de Google mediante una solicitud mediante el token de autorización para que actúe como agente del usuario.
Si el servicio de Google reconoce el token, proporcionará los datos solicitados.

Cómo trabajar con AuthSub

La incorporación de AuthSub a tu aplicación web requiere las siguientes tareas:

Decida si desea registrar su aplicación web o no.
Las aplicaciones web registradas tienen la ventaja de que Google las reconozca. La advertencia estándar que se muestra a los usuarios en la página de acceso de Google se modifica o se omite. Además, las aplicaciones web registradas se identifican con un nombre descriptivo en lugar de la simple URL de llamada. Ten en cuenta que algunos servicios de Google solo permiten el acceso limitado a 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 con un certificado en el archivo pueden adquirir tokens seguros para usar cuando solicitan datos de un servicio de Google. (También pueden usar tokens no seguros si es necesario).
Decide qué tipo de tokens usar y cómo administrarlos.
Un token de autorización recibido de Google está destinado para utilizarse en todas las interacciones futuras con el servicio de Google especificado para ese usuario. El tipo de token que elijas usar (un solo uso o sesión) dependerá del tipo de interacciones que tu aplicación web tendrá 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 excepcional.

Si eliges obtener tokens de sesión y usarlos con frecuencia para acceder al servicio de Google, tu aplicación web deberá administrar el almacenamiento de tokens, incluido el seguimiento del usuario y del servicio de Google para el cual es válido. Las cuentas de Google no están configuradas para administrar grandes cantidades de tokens y, de hecho, no permite que más de diez tokens válidos (por usuario, por aplicación web) estén pendientes en cualquier momento. Esta limitación permite que una aplicación web obtenga varios tokens para cubrir diferentes servicios, si es necesario; no admite la obtención de un nuevo token cada vez que la aplicación web necesita acceder a un servicio de Google. Si decides almacenar tokens de sesión, los tokens se deben tratar de manera tan segura como cualquier otra información sensible almacenada en el servidor.

Como alternativa, puedes 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.
Determine el alcance que requiere el servicio de Google para acceder.
Cada servicio de Google determina la cantidad y el tipo de acceso que permitirá. Este acceso se expresa como un valor de alcance. El alcance de un servicio puede ser una simple URL que identifique el servicio completo o puede especificar un acceso más restringido. Algunos servicios limitan seriamente el acceso, como el permiso de solo lectura a información limitada. Para obtener los permisos permitidos del servicio de Google al que quieres acceder, consulta la documentación de ese servicio. Debes solicitar el token con el alcance más estricto posible. Por ejemplo, si intentas acceder a la función Atom de Gmail, utiliza 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.
Configura un mecanismo para solicitar y recibir un token de autorización.
El mecanismo debe generar una llamada AuthSubRequest con el formato correcto, incluida la especificación de 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, si admites 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 daría como resultado 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 determinadas 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 consiste en acceder a la cuenta y elegir otorgar o no el acceso. Sin embargo, los usuarios que tengan más de una cuenta de Google (una cuenta de Gmail normal o una o más cuentas alojadas de Google Apps) deberán 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 utilizando 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 estableces el valor en el valor "default", se limitará la autorización solo a las cuentas normales. Cuando se configure el valor hd, Google seleccionará automáticamente la cuenta correcta para la autorización.

El mecanismo del token debe estar equipado para analizar el redireccionamiento recibido de Google, que contiene el token de un solo uso, y para realizar acciones con él. Debido a que los tokens de autorización son específicos para un usuario, tu aplicación debe poder asociar un token a su usuario. La opción preferida es emitir una cookie al usuario antes de realizar la solicitud de token. Luego, cuando Google redirecciona al usuario de vuelta a tu sitio con un token agregado, la aplicación puede leer la cookie y asociar el token con la identificación de usuario correcta.
Configura mecanismos para solicitar tokens de sesión y almacenarlos o revocarlos, si corresponde.
Según las decisiones de administración de tokens que haya tomado en el paso 2, es posible que deba crear mecanismos para obtener y revocar tokens de sesión (AuthSubSessionToken y AuthSubRevocaToken). Para probar los mecanismos de sesión y revocación, usa AuthSubTokenInfo, que indica si un token determinado es válido o no. Si se almacenan tokens, la aplicación debe realizar un seguimiento del ID de usuario y del servicio (alcance) que cubre el token.
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 tiene el formato de una solicitud GET de HTTP (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 respetar la siguiente forma:
```
Authorization: AuthSub token="token"
```
donde token es el token de autorización de un solo uso o una sesión que Google recibió en respuesta a una solicitud de AuthSub. Si el token es seguro, debe estar acompañado de una firma digital. Consulta "Firma de solicitudes" para obtener instrucciones y ejemplos.

En el siguiente ejemplo, se muestra un encabezado de solicitud de una llamada al servicio de feed de Calendario de Google. 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 sobre el intercambio de un token único por un token de sesión, consulta estos recursos adicionales:

Autenticación de AuthSub para aplicaciones web (documentación completa)
Usa AuthSub con las bibliotecas cliente de las API de datos de Google
Genera claves y certificados (AuthSub seguro)
Firma solicitudes con AuthSub (AuthSub segura)
Registro para aplicaciones basadas en la Web

Volver al principio

Usar ClientLogin para la autorización

ClientLogin es una API de autorización de propiedad de Google, disponible como alternativa a OAuth para la mayoría de las API de Google. En lo 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 a sus usuarios acceder a sus cuentas de Google desde su aplicación. Luego, la aplicación se comunica con Google a través de los datos de acceso y solicita acceso a una API de datos de Google especificada. Una vez que la información de acceso se haya autenticado correctamente, Google mostrará un token, al que hará referencia tu aplicación cada vez que solicite acceso a la cuenta del usuario; por ejemplo, para obtener o publicar datos. El token es válido por un período determinado, definido por el servicio de Google con el que estés trabajando.

Nota: Las bibliotecas cliente de las API de datos de Google proporcionan métodos para ayudarte a usar ClientLogin en las aplicaciones instaladas. En particular, 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 API de datos de Google.

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

Cuando la aplicación de terceros necesita acceder al servicio de Google del usuario, recupera el nombre de usuario y la contraseña del usuario.
Luego, la aplicación de terceros realiza una llamada ClientLogin al servicio de autorización de Google.
Si el Servicio de autorización de Google decide que es necesaria una evaluación adicional, muestra una respuesta de falla con un token y un desafío CAPTCHA en forma de URL para una imagen CAPTCHA.
Si se recibe un desafío de CAPTCHA, la aplicación de terceros muestra la imagen de CAPTCHA para el usuario y le solicita una respuesta.
Si se solicita, el usuario envía una respuesta al desafío CAPTCHA.
La aplicación de terceros hace una nueva llamada ClientLogin, pero esta vez incluye la respuesta y el token del CAPTCHA (recibido con la respuesta de falla).
En un intento de acceso exitoso (con o sin una verificación de CAPTCHA), el servicio de autorización de Google muestra un token a la aplicación.
La aplicación se comunica con el servicio de Google para hacer una solicitud de acceso a los datos y hacer referencia al token recibido del servicio de autorización de Google.
Si el servicio de Google reconoce el token, proporcionará el acceso solicitado a los datos.

Usar ClientLogin

Usa esta interfaz en tu aplicación instalada para acceder de manera programática a la Cuenta de Google de un usuario. Después de recopilar la información de acceso del usuario, llame a ClientLogin para solicitar acceso a la cuenta del usuario. Una vez que la información de acceso se haya autenticado correctamente, Google mostrará un token, al que hará referencia tu aplicación cada vez que solicite acceso a la cuenta del usuario. El token es válido por un período determinado, definido por el servicio de Google con el que trabajes.

La incorporación de ClientLogin en tu aplicación requiere estas tareas:

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 debería poder mostrar una imagen CAPTCHA con la URL que se recibe de Google, si es necesario, y solicitar la respuesta correcta del usuario. Lo ideal es que tu IU incluya un vínculo a la página de acceso de las cuentas de Google ("https://www.google.com/accounts/Login") en caso de que el usuario necesite registrarse para obtener una cuenta nueva o realizar otro mantenimiento de la cuenta.
Escribe el código para generar una solicitud ClientLogin POST de HTTPS con el formato correcto y transmitirla.
Este código debe contener lógica para manejar un desafío de CAPTCHA e incluir los parámetros logintoken y logincaptcha. La aplicación también debe ser capaz de detectar cuándo el usuario omite la información requerida (o repite datos incorrectos después de un error de acceso) y mostrar un error sin enviar una solicitud superflua.
Administra las respuestas de Google.
Existen cuatro respuestas posibles para una solicitud de acceso:
- correcto (un HTTP 200)
- un error HTTP (403) con un código de error explicativo;
- solicitud no válida, generalmente generada por una solicitud con formato incorrecto
- error con un desafío de CAPTCHA
Una respuesta exitosa 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 estrictamente y no deben entregarse a ninguna otra aplicación, dado que representan el acceso a la cuenta del usuario. El límite de tiempo para el 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 o 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 manejar todos los mensajes de error posibles según corresponda.
Una respuesta de falla con un desafío de CAPTCHA significa que Google decidió, por cualquier motivo, que se deben tomar medidas de seguridad adicionales. Esta respuesta se acompaña de una URL de imagen CAPTCHA y un token que representa el desafío específico de CAPTCHA.
Controla un desafío de CAPTCHA de Google.
Para abordar el desafío, la aplicación debe mostrar la imagen CAPTCHA y solicitar una respuesta al usuario. Para mostrar la imagen CAPTCHA, usa el valor de CaptchaUrl que se muestra con la respuesta de falla, prefijando la URL de Cuentas de Google como: "http://www.google.com/accounts/". Una vez que el usuario proporciona una respuesta, la aplicación debe reenviar la solicitud de acceso, esta vez con el token 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 los procesos de obtención y transmisión de una respuesta de CAPTCHA del usuario. En respuesta a un desafío de CAPTCHA, la aplicación puede dirigir al usuario a la página alojada en Google: "https://www.google.com/accounts/DisplayUnlockCaptcha". Una vez que el usuario haya respondido correctamente al desafío, el servidor de Google confía en la computadora que se está usando. Luego, la aplicación puede reenviar la solicitud de acceso original para obtener el token de autorización.

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

* CAPTCHA es una marca de la Universidad Carnegie Mellon

Volver al principio

Autenticación para gadgets

Proxy OAuth

Si creas un gadget con la API de gadgets estándar, puedes usar una función de la plataforma de gadget llamada Proxy de OAuth que te permite acceder a las API de datos de Google. 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; para ello, oculta muchos de los detalles de autenticación de OAuth. El proxy se basa en un proyecto de código abierto denominado Shindig, que es una implementación de la especificación del gadget.

Nota: El proxy de OAuth solo es compatible con 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 OAuth para 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:

Tu gadget se carga por primera vez e intenta acceder a los datos del usuario con una de las API de datos de Google.
La solicitud falla porque el usuario no ha otorgado 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 abrir una nueva ventana con esa URL.
En la página de aprobación, el usuario elige conceder o denegar el acceso a tu gadget. Si se ejecuta de forma correcta, se dirigirá al usuario a la página de oauth_callback que especifiques. Para obtener la mejor experiencia del usuario, usa http://oauth.gmodules.com/gadgets/oauthcallback.
A continuación, el usuario cierra la ventana emergente. Para notificar a tu gadget que el usuario ha aprobado, puedes utilizar 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 después de que se cierre esta ventana.
Tu gadget intenta acceder a la API de datos de Google por segunda vez mediante una nueva solicitud de datos del usuario. Este intento se realizó correctamente.
Tu gadget se autenticó y puede comenzar a funcionar normalmente.

Configuración del gadget

Para acceder a una o más API de datos de Google, primero debes indicarle a tu gadget que utilice OAuth como método de autenticación. Agrega un elemento <OAuth> en la sección <ModulePrefs> del archivo 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 utilizan en este parámetro. En este ejemplo, el gadget puede acceder a los datos de Blogger y Calendar. Un gadget puede solicitar datos para uno o varios alcances, como en este ejemplo.
oauth_callback: 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 proporcionar 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. Como alternativa, puede configurar este parámetro para que se oriente a su propia página "aprobada" o puede dejar el parámetro en blanco.

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

Una vez que el gadget haya autenticado al usuario, será sencillo acceder a una API de datos de Google con la biblioteca cliente de JavaScript de las API de datos de Google. 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 acerca de los gadgets

Para obtener información completa sobre la creación de gadgets de la API de datos de Google, incluidos los detalles del proxy de OAuth, un artículo sobre cómo comenzar y las especificaciones del gadgets.*, consulte estos recursos adicionales:

Usa la biblioteca cliente de JavaScript
Cómo crear un gadget de las API de datos de Google (artículo)
Escritura de gadgets de OAuth (documentación completa de gadgets)
Documentación de la API de gadgets de Google

Volver al principio