Consideraciones sobre la integración

Esta guía paso a paso te ayuda a tomar decisiones sobre todos los problemas principales de integración.

Accede con Google en abstracto

A continuación, se indican los pasos generales que deben seguir los usuarios para acceder a tu sitio web o registrarse en él.

  1. Los usuarios acceden a un sitio web de Google.

    Para que Acceder con Google funcione, debe haber una sesión de Google activa en el navegador. One Tap y Acceso automático se activan solo cuando los usuarios acceden a Google antes de cargar tus páginas web. Este paso es opcional para el flujo del botón de Acceder con Google, ya que se solicita a los usuarios que accedan a Google cuando se presiona el botón.

  2. Los usuarios navegan por tus páginas web en las que están incorporados los botones One Tap, Acceso automático o Acceder con Google.

  3. Los usuarios interactúan con One Tap, el botón Acceder con Google y los flujos de UX posteriores para hacer lo siguiente:

    • Selecciona una sesión de Google activa para continuar.
    • Obtén el consentimiento de los usuarios finales para compartir la información del perfil con tu sitio web, si aún no lo has hecho.

    Cuando solo hay una sesión activa de Google en el navegador,

    • One Tap selecciona automáticamente la única sesión y, por lo tanto, omite la página del selector de cuentas.
    • El botón Acceder con Google permanece en la página del selector de cuentas, lo que permite a los usuarios agregar una nueva sesión de Google cuando sea necesario.

    Si la Cuenta de Google seleccionada no se usó antes en tu sitio web o se revocó el permiso, se mostrará una página de consentimiento.

    Consentimiento del botón de Acceder con Google

    Una vez que se apruebe, Google registrará la decisión para omitir la página de consentimiento para la próxima vez.

  4. Se comparte una credencial de token web JSON (también conocido como token de ID) que contiene el nombre, el correo electrónico y la foto de perfil del usuario mediante un controlador de devolución de llamada de JavaScript o un envío posterior a tu servicio de backend.

    El propósito de mostrar tokens de ID al controlador de devolución de llamada de JavaScript en el cliente no es que lo decodifiques en el código JavaScript, sino que lo envíes a tu servidor a tu manera. Un buen ejemplo es usar una XmlHttpRequest para evitar que se vuelva a cargar la página debido al envío de la publicación.

  5. En tu servidor, la credencial de JWT emitida por Google se valida y se consume para crear una cuenta nueva o establecer una sesión autenticada en tu sitio web.

    Administrarás el estado de acceso del usuario en tu propio sitio web.

    El estado de acceso de la Cuenta de Google del usuario y tu app son independientes entre sí, excepto durante el momento de acceso, cuando sabes que el usuario se autenticó correctamente y accedió a su Cuenta de Google. Es posible que los usuarios permanezcan conectados, salgan de su cuenta o cambien a una Cuenta de Google diferente mientras mantienen una sesión activa y abierta en tu sitio web.

En resumen, como el acceso basado en contraseña, Acceder con Google proporciona otra forma de autenticar usuarios en la Web. Acceder con Google no proporciona ninguna función para la administración de sesiones en tu sitio web después de la autenticación.

Accede a los servicios y las API de Google

Si bien integraste la API de autenticación, como se describió anteriormente, es posible que también debas integrar la API de authorization, si tu sitio necesita acceder a los servicios y las API de Google en nombre de los usuarios autenticados. Mientras que la autenticación le proporciona a tu sitio tokens de ID para autenticar a los usuarios, la autorización le proporciona tokens de acceso y permisos (independientes) para usar las API y los servicios de Google. Si deseas obtener más información, consulta Autorización para la Web.

Separación de UX para la autenticación y la autorización

Si tu sitio web necesita llamar a las APIs de autenticación y autorización, debes llamarlas por separado en diferentes momentos. Consulta Separa los momentos de autenticación y de autorización.

Si en el pasado tu sitio web solicitó tokens de autenticación y autorización juntos, cuando uses la biblioteca de JavaScript de Google Identity Services, deberás ajustar tu UX para separar el momento de autenticación del momento de autorización.

  • Durante el momento de la autenticación, tu sitio web se puede integrar con el botón One Tap, el acceso automático o el acceso con Google para permitir que los usuarios accedan a tu sitio web o se registren en él.
  • En el momento de la autorización, tu sitio web puede invocar a la API de autorización para obtener los permisos y los tokens necesarios para acceder a los servicios o las APIs de Google.

Para lograr una transición de UX fluida y reducir la complejidad, una práctica común es dividir el proceso en dos pasos separados.

  1. Refactoriza la UX para separar los momentos de autenticación y autorización.

  2. Migra a la biblioteca de JavaScript de Google Identity Services.

API de HTML versus API de JavaScript

Puedes usar la API de HTML o la API de JavaScript para integrar el botón One Tap, el acceso automático o el acceso con Google en tus páginas web.

Con la API de HTML, tienes más funciones incorporadas. Por ejemplo,

  • Cómo renderizar el botón de One Tap o de Acceder con Google cuando se carga la página
  • Envía la credencial que se muestra a tu extremo del servidor, especificado por el atributo data-login_uri, después de que se complete la UX con One Tap, el acceso automático o la UX de ventana emergente o redireccionamiento de botones.
  • Evita los ataques CSRF con double-submit-cookie.
  • Usa el generador de código para generar el código HTML y, luego, cópialo en tus páginas HTML.

Con la API de HTML, también puedes escribir JavaScript para personalizar el comportamiento.

  • Puedes escribir tu propio controlador de devolución de llamada y, luego, establecer el nombre de la función en el atributo data-callback. Un buen ejemplo es usar una XmlHttpRequest para enviar la credencial que se muestra a tu servidor y evitar que se vuelva a cargar la página debido al envío predeterminado posterior.

Con la API de JavaScript, tienes más flexibilidad en algunas situaciones, como se muestra a continuación.

  • Renderizando One Tap y el botón de Acceder con Google en otro momento. Por ejemplo, después de que los usuarios seleccionen Acceder en el menú.
  • Llamar a la API varias veces Por ejemplo, el botón Acceder con Google debe renderizarse cada vez que se renderiza el diálogo de acceso.
  • Generar tus páginas HTML de forma dinámica, lo que dificulta la incorporación de código de llamada a la API en ellas
  • Cargarás la biblioteca de JavaScript de Google Identity Services más adelante.

El código de la API HTML solo se puede invocar una vez, ya sea en el evento de carga de la página o en el evento de carga de la biblioteca de JavaScript de Google Identity Services, lo que ocurra después. Debes usar la API de JavaScript si el comportamiento de la API de HTML no cumple con tus expectativas.

No uses la API de HTML con la API de JavaScript en la misma página web para inicializar la página o para la renderización de One Tap y de botones. Verifica tu código, tanto HTML como JavaScript, para detectar lugares donde puedan superponerse. Ten en cuenta lo siguiente:

  • Usas la API de HTML si uno o más de los elementos de <div id='g_id_onload' ... ><id> o <div class='g_id_signin' ...></div> existen en tu código HTML.
  • Usas la API de JavaScript si se invocan uno o más métodos de initialize(), prompt() o render() en tu código JavaScript, sin importar si están intercalados o cargados desde un archivo JavaScript separado.

Las siguientes APIs de JavaScript se pueden usar independientemente de la inicialización o la renderización de One Tap y de botones. No tienen las APIs de HTML correspondientes:

Consideraciones sobre el botón de Acceder con Google

Ventana emergente en comparación con redireccionamiento

La especificación de OAuth 2.0 considera el redireccionamiento HTTP, pero carece de orientación para renderizar los diálogos de ventanas emergentes. La UX de ventanas emergentes, especialmente en la Web para computadoras, puede proporcionar una mejor UX para los usuarios finales. Esto se debe a que a los usuarios no se los redirecciona de las páginas de terceros, y una ventana emergente similar a un diálogo proporciona una experiencia en contexto para la concesión de permisos.

Con la UX de ventana emergente, el proveedor de identidad debe compilar en los canales de comunicación de origen cruzado del cliente para pasar las respuestas de OAuth de la ventana emergente, en la que se muestra la página de consentimiento del proveedor de identidad, a la ventana principal, donde se muestra la página del tercero. Por lo general, se requieren códigos JavaScript en ambos lados para enviar y recibir la respuesta de OAuth en todas las ventanas.

Tanto la UX de ventana emergente como la de redireccionamiento son compatibles con el botón Acceder con Google. De forma predeterminada, se usa la UX de ventanas emergentes. Puedes cambiar la UX si configuras el atributo data-ux_mode.

Existen algunas diferencias entre el flujo de redireccionamiento del botón de Acceder con Google y el flujo de redireccionamiento de OAuth.

  • El flujo de redireccionamiento del botón de Acceder con Google siempre usa el método POST para enviar la credencial a tu servidor web, mientras que el redireccionamiento de OAuth suele usar el método GET.
  • Los parámetros que envía el flujo de redireccionamiento del botón de Acceder con Google son diferentes de los del flujo de redireccionamiento de OAuth.

Para los desarrolladores que usan la API de HTML, independientemente de la UX que se use, las credenciales siempre se envían al data-login_uri con el método POST y los mismos parámetros. Esto te permite cambiar el modo de UX sin otros cambios en el código. Para la UX de redireccionamiento, se debe agregar data-login_uri a los URI de redireccionamiento autorizados de tu cliente en la Consola de APIs de Google.

Personalización de botones

No se admite el uso de un botón propio. No hay una API para iniciar un flujo de botones de manera programática.

Para habilitar el flujo del botón de Acceder con Google, lo único que debes hacer es renderizar uno o más botones de Acceder con Google en tus páginas web. El flujo de botones se inicia y controla con transparencia cuando los usuarios hacen clic en ellos.

La API de renderización de botones te permite personalizar el aspecto del botón de Acceder con Google. Te recomendamos que uses el generador de código para diseñar tus botones de forma interactiva. Incluso si usas la API de JavaScript, puedes generar primero el código HTML y, luego, copiar el código en los campos correspondientes de la API de JavaScript.

No hay una API que permita a los sitios web controlar si la información personalizada se debe usar para renderizar los botones. Los botones personalizados se muestran si se cumplen todas las condiciones. Obtén más detalles en el botón Información sobre las opciones personalizadas.

Puedes colocar varios botones en la misma página web. El generador de código solo puede crear un botón cada vez. Puedes ejecutarlo varias veces y copiar el código <div class='g_id_signin' ...></div> generado en la página web.

Prácticas recomendadas para el procesamiento de botones

Por motivos de privacidad, el botón personalizado se muestra en un iframe del dominio accounts.google.com. Cargar un iframe puede llevar mucho tiempo en una red lenta. Para mitigar este problema de latencia, los botones se renderizan en 2 pasos, de la siguiente manera:

  1. Se renderiza una versión de botón intercalado en el árbol del DOM de tu sitio web. Es solo un botón de texto, no se puede usar información personalizada. El objetivo es permitir que los usuarios vean el botón lo antes posible.
  2. Se envía una solicitud de iframe a Google para cargar el iframe del botón, que puede tener información personalizada. Una vez cargado el iframe del botón, se quita el botón de la versión intercalada.

A continuación, se enumeran algunas prácticas recomendadas para minimizar la latencia de visualización del botón de flujo del botón Acceder con Google.

  • Carga la biblioteca de JavaScript de Google Identity Services lo antes posible. Considera cargar la biblioteca de JavaScript antes que otras bibliotecas grandes, en especial en la Web móvil.

  • Si el botón Acceder con Google se renderiza solo después de que el usuario selecciona Acceder en el menú. Puedes renderizar el botón de Acceder con Google en un elemento oculto primero y, luego, hacerlo visible después de que el usuario seleccione Acceder en el menú.

Consideraciones sobre One Tap

Acceso automático

El acceso automático cancelable proporciona los siguientes beneficios.

  • Puede mejorar la tasa de acceso guardando una acción del usuario.
  • A diferencia del acceso silencioso que proporciona la biblioteca de JavaScript de Acceso con Google que dejó de estar disponible anteriormente, los usuarios siempre ven alguna IU cuando ocurre un acceso automático, lo que les brinda el contexto de por qué y cómo acceden a tu sitio web. Los usuarios también pueden cancelar el servicio si lo desean.
  • Selecciona automáticamente la cuenta que el usuario usó antes, lo que puede impedir que cree cuentas duplicadas en tu sitio web.

La habilitación del acceso automático es una decisión que debes tomar según los requisitos empresariales y de UX de tu sitio web. En especial si la mayoría de las salidas de tu sitio web se deben al tiempo de espera de la sesión en lugar de a elecciones explícitas del usuario, el acceso automático puede ser una buena manera de que tus usuarios recuperen el estado de la sesión.

Cuándo se debe mostrar la IU de One Tap

Con la API HTML, One Tap siempre se muestra al cargar la página. Con la API de JavaScript, puedes controlar cuándo se muestra la IU de One Tap. Ten en cuenta que es posible que la IU de One Tap no siempre se muestre después de que se invoque la API, debido a algunas razones que se describen a continuación.

No intentes mostrar solo la IU de One Tap en un evento de clic de botón. Es posible que la IU de One Tap no se muestre por los motivos anteriores, y los usuarios podrían tener una UX dañada, ya que no se muestra nada después de la acción del usuario. En un evento de clic en un botón:

Se recomienda

  • Muestra tu diálogo de acceso con el acceso con contraseña y el botón Acceder con Google, y llama a la API de One Tap al mismo tiempo. Esto garantiza que a los usuarios siempre se les ofrezca algún método de acceso a tu sitio web.

No recomendado

  • Cuando se ofrece solo One Tap, es posible que los usuarios experimenten una experiencia de acceso dañada si no se muestra One Tap.
  • Usar una devolución de llamada de estado de la IU para mostrar otra IU si no se muestra One Tap. Esto no se recomienda, ya que es posible que la devolución de llamada del estado de la IU no funcione bien con la administración de credenciales federadas en una versión futura.

One Tap en navegadores ITP

Debido a la Prevención de seguimiento inteligente (ITP), la UX normal de One Tap no funciona en los navegadores de ITP, como Chrome en iOS, Safari y Firefox. En su lugar, se proporciona una UX diferente que comienza con una página de bienvenida.

La UX de One Tap en los navegadores ITP se puede inhabilitar si así lo deseas. Para obtener más información, consulta Compatibilidad con One Tap en navegadores ITP.

No hay forma de habilitar esta UX en navegadores que no sean de ITP, como Chrome en Android, macOS/Linux y Edge.

Cancelar el mensaje si el usuario hace clic fuera

De forma predeterminada, el mensaje de One Tap se cierra automáticamente si el usuario hace clic fuera del mensaje. Puedes cambiar este comportamiento si lo deseas.

Te recomendamos que mantengas abierto el mensaje de One Tap en la Web para computadoras, ya que el tamaño de la pantalla es lo suficientemente grande.

Cómo cambiar la posición de la UX de One Tap

En la Web para computadoras, puedes cambiar la posición del mensaje de One Tap. Sin embargo, esta función no se recomienda, ya que no es compatible con la administración de credenciales federadas en una versión futura.

Cambia el contexto de acceso

One Tap debe formar parte de un flujo de UX más grande en tu sitio web. De forma predeterminada, la IU de One Tap se usa dentro de un contexto de acceso. El idioma de la IU contiene una redacción particular, como "acceder". Puedes cambiar el atributo de contexto para crear un conjunto diferente de palabras. Puedes seleccionar uno de los encabezados de One Tap que mejor se adapte a tu flujo de UX.

Contexto
signin "Acceder con Google"
signup "Registrarse con Google"
use "Usar con Google"

Cómo escuchar en el estado de la IU de One Tap

Para integrarte sin problemas en tu flujo de UX más grande, One Tap puede notificarte cuando cambie el estado de la IU. Sin embargo, esta función no será compatible con versiones futuras de administración de credenciales federadas.

One Tap entre subdominios

De forma predeterminada, el período de inactividad de One Tap y otros estados se rastrean por origen. Si tu sitio web muestra One Tap en varios subdominios, debes indicarlo en el código de la API.

One Tap en páginas HTML estáticas

De forma predeterminada, la biblioteca de GIS asume que tus páginas web se generan de forma dinámica. Tu servidor HTTP verifica el estado de acceso del usuario cuando genera el código HTML.

  • Si ningún usuario accedió, se debe incluir el código HTML de One Tap en la página resultante para activar One Tap y permitir que los usuarios accedan a tu sitio web.
  • Si los usuarios ya accedieron, el código HTML de One Tap no se debe incluir en la página resultante.

En este caso, es responsabilidad de tu servidor web agregar o quitar el código de la API de HTML de One Tap.

El código de la API HTML de One Tap puede funcionar de otra manera, ya que está diseñado para sitios web que alojan una gran cantidad de contenido HTML estático. Siempre puedes incluir el código de la API HTML de One Tap en tus páginas HTML estáticas y especificar el nombre de cookie de sesión que se usa en tu sitio web.

  • Si la cookie de sesión no existe, se activa el flujo de One Tap.
  • Si la cookie de sesión existe, se omite el flujo de One Tap.

En este caso, el estado de la cookie de sesión controla si deseas activar el flujo de One Tap, en lugar de la existencia del código de la API HTML de One Tap en tu página web.

Integración del servidor

Después de que se realiza One Tap, se completa el flujo de UX del acceso automático o del botón Acceder con Google, se emite un token de ID y se comparte con tu sitio web. Para autenticar al usuario, se requieren algunos cambios en el servidor para recibir y validar el token de ID.

Consideraciones sobre la UX

Por lo general, debes agregar un extremo HTTP en tu propio origen para controlar las respuestas del servidor. Los siguientes factores pueden tener un impacto en la UX resultante.

La UX real que obtienes se describe de la siguiente manera.

  1. Para el modo de UX de redireccionamiento del botón para acceder con Google, haz lo siguiente:

    • Si se usa la API de HTML o la API de JavaScript, debes configurar el URI de acceso. Es imposible usar una función de devolución de llamada de JavaScript para controlar la respuesta, dado que a los usuarios ya se los redireccionó fuera de la página web.
    • Resumen de UX: Después de hacer clic en el botón Acceder con Google, los usuarios ven un redireccionamiento de página completa a una IU de Google para la selección y aprobación de la sesión. Una vez hecho esto, se envía una POST de página completa al URI de acceso que especificaste.

  2. En el caso del modo de UX emergente de One Tap o del botón Acceder con Google, si se usa la API de JavaScript o si se usa la API de HTML y se proporciona una función de devolución de llamada de JavaScript:

    • Las respuestas de Auth se envían a la función de devolución de llamada de JavaScript.
    • Resumen de UX: Se muestra el mensaje de One Tap o una ventana emergente sobre la página web. Una vez que los usuarios finalizan la UX en la instrucción o en la ventana emergente para seleccionar y aprobar la sesión, la función de devolución de llamada de JavaScript recibe las respuestas. La UX posterior se determina según la forma en que la función de devolución de llamada envía las respuestas a tu servidor.

  3. De lo contrario (la API HTML con el caso del URI de acceso):

    • Las respuestas de autenticación se envían al URI de acceso.
    • Resumen de UX: se muestra el mensaje de One Tap o una ventana emergente sobre la página web. Después de que los usuarios finalizan la UX en la instrucción o en la ventana emergente para seleccionar y aprobar la sesión, las respuestas de autenticación se envían con un envío de página completa POST a la URL de acceso que especificaste.

Te recomendamos que uses de manera coherente las respuestas de One Tap y del botón de Acceder con Google.

Consideraciones de seguridad

Para prevenir los ataques de falsificación de solicitudes entre sitios,

  • Para el envío posterior activado por la biblioteca de JavaScript del cliente de Google Identity Service, puedes usar el patrón integrado de envío doble de cookies. Consulta Cómo verificar el token de ID de Google en tu servidor para obtener más detalles.
  • Para el envío a tu propio origen mediante XmlHttpRequest, puedes usar el encabezado HTTP personalizado o alguna otra medida de seguridad aprobada por tu equipo de seguridad.

Para verificar los tokens de ID en las respuestas de autenticación, te recomendamos que uses una biblioteca cliente de la API de Google para tu plataforma o una biblioteca de JWT de uso general.

Preguntas frecuentes

  • ¿El botón de One Tap y Acceder con Google está disponible en WebViews?

    No. Debido a cuestiones de seguridad, los usuarios no deben agregar sesiones de Google a WebViews. Por lo tanto, los GIS están inhabilitados en WebView, ya que no se supone que haya sesiones de Google allí.

  • ¿Puedo usar mi propio botón de Acceder con Google? No. Con el flujo del servidor de OAuth o la versión anterior de la biblioteca JavaScript de Acceso con Google, las partes de confianza podían usar los lineamientos de desarrollo de la marca de acceso para compilar sus propias versiones de los botones de Acceso con Google.

    Sin embargo, Acceder con Google quitó esta función. La biblioteca JavaScript de Google Identity Services debe generar todos los botones de Acceder con Google. Hay dos motivos para este cambio.

    • Algunos usuarios de confianza no siguieron los lineamientos, lo que generaba discrepancias en los botones de Acceder con Google en los sitios web.
    • Si lo generas a través de la biblioteca, no es necesario realizar ningún cambio cuando cambien los Lineamientos de desarrollo de la marca para el acceso.

    Para aplicar esta regla, la biblioteca de JavaScript solo expone una API para procesar un botón, pero no la API para iniciar el flujo de acceso.

  • ¿Qué sucede si mi sitio web solo habilita One Tap, pero no el botón Acceder con Google?

    Te recomendamos que uses One Tap y el botón Acceder con Google en tu sitio web. Debido al período de inactividad exponencial, es posible que One Tap no se muestre siempre. Cuando los usuarios realmente quieran acceder a tu sitio web con sus Cuentas de Google, pueden ir al diálogo de acceso principal y acceder con el botón Acceder con Google. Si accedes correctamente mediante el botón Acceder con Google, se borrará el estado de enfriamiento de One Tap para que se pueda mostrar en el siguiente acceso. Otros flujos de botones de Google no pueden borrar los estados de inactividad de One Tap, ya que están en diferentes objetos binarios de JavaScript.

    Si tu sitio web solo habilita One Tap, pero no el botón Acceder con Google, es posible que veas una disminución en el rendimiento de tu flujo de One Tap, ya que los estados de inactividad exponenciales no se borran a tiempo.

  • ¿Cuándo se analiza mi código HTML de la API? ¿Puedo cambiar mi código HTML de la API más adelante?

    La biblioteca de JavaScript de Google Identity Services analiza y ejecuta tu código de API HTML, ya sea en el evento de carga de la biblioteca de JavaScript o en el evento DomContentLoaded, lo que ocurra después.

    • Si el evento DomContentLoaded se activa cuando se carga la biblioteca JavaScript, el código de tu API HTML se analiza y se ejecuta de inmediato.
    • De lo contrario, la biblioteca JavaScript agrega un objeto de escucha para el evento DomContentLoaded. Cuando se activa, el objeto de escucha analiza y ejecuta tu código de API HTML.

    Además, ten en cuenta que el análisis y la ejecución del código de la API HTML se realiza una sola vez.

    • Después del análisis y la ejecución, se ignorará cualquier cambio posterior en el código de la API HTML.
    • No hay una API para que los desarrolladores activen el proceso de análisis o ejecución.