Consideraciones de integración

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

Acceder con Google de forma abstracta

A continuación, se indican los pasos generales que deben seguir los usuarios para acceder a su 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. El acceso automático y One Tap 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 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 One Tap, el Acceso automático o el botón 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 información del perfil con tu sitio web, si aún no lo han hecho.

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

    • Con One Tap, se selecciona automáticamente la única sesión y, por lo tanto, se 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 sesión de Google nueva cuando sea necesario.

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

    Consentimiento del botón Acceder con Google

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

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

    El objetivo de mostrar tokens de ID al controlador de devolución de llamada de JavaScript en el lado del cliente no es que lo decodifiques en el código de JavaScript, sino que debes enviarlo 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 una publicación.

  5. En el 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 a 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. Los usuarios pueden permanecer conectados, salir o cambiar a otra Cuenta de Google y, al mismo tiempo, mantener una sesión activa en tu sitio web.

En resumen, al igual que el acceso con contraseña, Acceder con Google proporciona otra forma de autenticar a los 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 las API y a los servicios de Google en nombre de los usuarios autenticados. Si bien la autenticación le proporciona a tu sitio tokens de ID para autenticar a los usuarios, la autorización le proporciona a tu sitio tokens de acceso (distintos) y permisos para usar las API y los servicios de Google. Consulta Autorizar para la Web para obtener más información.

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 de autorización, debes llamarlas por separado en diferentes momentos. Consulta Separa los momentos de autenticación y autorización.

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

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

Para lograr una transición fluida de la UX 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. Migrar a la biblioteca JavaScript de Google Identity Services

API de HTML frente a API de JavaScript

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

Con la API de HTML, tiene más funciones integradas. Por ejemplo,

  • Renderizar la función One Tap o el botón Acceder con Google cuando se carga la página
  • Envía la credencial que se muestra al extremo del servidor, especificado por el atributo data-login_uri, después de que se complete la UX de One Tap, acceso automático o redireccionamiento de botones o ventanas emergentes con botones.
  • Evita los ataques de 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 la página vuelva a cargarse debido al envío predeterminado de una publicación.

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

  • Renderizarán One Tap y el botón Acceder con Google en un momento posterior. Por ejemplo, después de que los usuarios seleccionen Acceder en el menú.
  • Llamar a la API varias veces Por ejemplo, se debe renderizar el botón Acceder con Google cada vez que se muestra 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
  • Debes cargar la biblioteca JavaScript de Google Identity Services mucho más tarde.

El código de la API HTML solo se puede invocar una vez en el evento de carga de la página o en el evento de carga de la biblioteca JavaScript de Google Identity Services, lo que ocurra más adelante. 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 botones. Revisa 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.
  • Estás usando la API de JavaScript si uno o más de los métodos en initialize(), prompt() o render() se invocan en el código de JavaScript, sin importar si están intercalados o se cargan 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 botones; no tienen las APIs de HTML correspondientes:

Consideraciones sobre el botón Acceder con Google

Ventana emergente o redireccionamiento

La especificación de OAuth 2.0 considera el redireccionamiento HTTP, pero carece de orientación para renderizar diálogos emergentes. La UX emergente, especialmente en la Web para computadoras, puede proporcionar una mejor UX para los usuarios finales. Esto se debe a que no se redirecciona a los usuarios de 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 emergente, el proveedor de identidad debe compilar en 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 de ambas partes para enviar y recibir la respuesta de OAuth en todas las ventanas.

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

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

  • El flujo de redireccionamiento del botón 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 Acceder con Google son diferentes de los del flujo de redireccionamiento de OAuth.

Para los desarrolladores que usan la API de HTML, sin importar qué UX se utilice, las credenciales siempre se envían a data-login_uri con el método POST y los mismos parámetros. Esto te permite cambiar el modo UX sin otros cambios en el código. Para la UX de redireccionamiento, data-login_uri se debe agregar 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 tu propio botón. No hay una API para iniciar un flujo de botones de manera programática.

Para habilitar el flujo de botones 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 maneja de manera transparente cuando los usuarios hacen clic en esos botones.

La API de renderización de botones te permite personalizar el aspecto del botón Acceder con Google. Te recomendamos usar 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, copiarlo en los campos correspondientes de la API de JavaScript.

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

Puedes colocar varios botones en la misma página web. El generador de código solo puede crear un botón por 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 la renderización de botones

Por motivos de privacidad, el botón personalizado se muestra en un iframe desde el 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 botón de iframe, que puede tener información personalizada. Una vez que se carga el iframe del botón, se quita el botón de la versión intercalada.

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

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

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

Consideraciones de One Tap

Acceso automático

El acceso automático cancelable ofrece los siguientes beneficios.

  • Es posible que mejore la tasa de acceso guardando una acción del usuario.
  • A diferencia del acceso silencioso proporcionado por la biblioteca JavaScript de Acceso con Google, que dejó de estar disponible, los usuarios siempre ven alguna IU cuando se produce el 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 si lo desean.
  • Selecciona automáticamente la cuenta que el usuario usó antes, lo que puede impedir que el usuario cree cuentas duplicadas en tu sitio web.

Habilitar el acceso automático es una decisión que debes tomar según los requisitos empresariales y de UX de tu sitio web. El acceso automático puede ser una buena forma de que los usuarios recuperen el estado de la sesión, 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.

Cuándo mostrar la IU de One Tap

Con la API HTML, One Tap siempre se muestra cuando se carga la página. Con el código JavaScript,

API, puedes controlar cuándo se muestra la IU de One Tap. Ten en cuenta que es posible que la IU con One Tap no siempre se muestre después de invocar la API, debido a algunos de los motivos que se describen a continuación.

  • No hay ninguna sesión de Google activa en el navegador.
  • Todas las sesiones activas de Google están inhabilitadas.
  • El enfriamiento está en curso.

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 el cuadro de diálogo de acceso con la contraseña de acceso y el botón Acceder con Google, y llama a la API de One Tap al mismo tiempo. Esto garantiza que siempre se les ofrezca a los usuarios algún método de acceso para tu sitio web.

No se recomienda

One Tap en navegadores ITP

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

Puedes inhabilitar la UX de One Tap en los navegadores ITP si 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 ITP, como Chrome en Android/macOS/Linux y Edge.

Cancelar el mensaje si el usuario sale con un clic

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

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.

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 será compatible con la administración de credenciales federadas en una versión futura.

Cambia el contexto de acceso

One Tap debería ser parte de un flujo de UX más amplio en tu sitio web. De forma predeterminada, la IU de One Tap se usa en un contexto de acceso. El idioma de la IU contiene palabras particulares, 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 "Regístrate con Google".
use "Usar con Google"

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

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

One Tap en subdominios

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

One Tap en páginas HTML estáticas

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

  • Si no accedió ningún usuario, 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 debería incluirse en la página resultante.

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

El código de la API HTML de One Tap puede funcionar de otra manera, 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 la 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 las cookies de tu sesión controla la activación del flujo de One Tap, en lugar de la existencia del código de la API HTML de One Tap en la página web.

Integración del servidor

Después de que se completa el acceso con One Tap o el flujo de UX 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 a fin de recibir y validar el token de ID.

Consideraciones de UX

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

La UX real que obtienes se describe a continuación.

  1. Para el modo de UX de redireccionamiento del botón Acceder con Google:

    • Ya sea que se use 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 procesar la respuesta, dado que a los usuarios ya se los redireccionó de tu 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 seleccionar y aprobar la sesión. Una vez hecho esto, se enviará un POST de página completa al URI de acceso que especificaste.

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

    • Las respuestas de Auth se pasan 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 tu página web. Una vez que los usuarios finalizan la UX en el mensaje o la ventana emergente para la selección y aprobación de la sesión, la función de devolución de llamada de JavaScript recibe las respuestas. La UX posterior se decide 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 tu página web. Una vez que los usuarios finalizan la UX en el mensaje o la ventana emergente para la selección y aprobación de la sesión, las respuestas de autenticación se envían mediante un envío de página completa de POST a la URL de acceso que especificaste.

Se recomienda que uses una forma coherente para enviar las respuestas de One Tap y las respuestas del botón Acceder con Google.

Consideraciones de seguridad

Para evitar ataques de falsificación de solicitudes entre sitios,

  • Para el envío de publicaciones activado por la biblioteca cliente de JavaScript del servicio de Google Identity Service, puedes usar el patrón integrado de cookie de envío doble. Consulta Cómo verificar el token de ID de Google en el servidor para obtener más detalles.
  • Para enviar contenido a tu propio origen mediante una XmlHttpRequest, puedes usar el encabezado HTTP personalizado o alguna otra medida de seguridad que apruebe 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 JWT de uso general.

Preguntas frecuentes

  • ¿El botón 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 se inhabilitan en las WebViews, ya que se supone que no hay 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 de JavaScript de Acceso con Google, las partes de confianza podían usar los lineamientos de desarrollo de la marca para el acceso con el fin de compilar sus propias versiones de los botones de Acceso con Google.

    Sin embargo, Acceder con Google quitó esta función. Todos los botones de Acceder con Google deben generarse con la biblioteca de JavaScript de Google Identity Services. Hay dos motivos para este cambio.

    • Algunos usuarios de confianza no siguieron los lineamientos, lo que genera botones de Acceder con Google incoherentes en los sitios web.
    • Si generas la app mediante la biblioteca, no es necesario que realices ningún cambio cuando cambien los lineamientos de desarrollo de la marca para el acceso.

    Con el fin de aplicar esta regla, la biblioteca de JavaScript solo expone una API para renderizar 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?

    Se recomienda usar One Tap y el botón Acceder con Google en tu sitio web. Debido al enfriamiento exponencial, es posible que One Tap no se muestre todas las veces. Cuando los usuarios realmente deseen 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 allí. Si accedes correctamente con el botón Acceder con Google, se borrará el estado de enfriamiento de One Tap, de modo que One Tap pueda aparecer para el próximo 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 enfriamiento exponenciales no se borran a tiempo.

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

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

    • Si el evento DomContentLoaded se activa cuando se carga la biblioteca JavaScript, el código de la API HTML se analiza y ejecuta de inmediato.
    • De lo contrario, la biblioteca de 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 son únicos.

    • Después del análisis y la ejecución, se ignoran los cambios posteriores que se apliquen a tu código de API HTML.
    • No hay una API para que los desarrolladores activen el proceso de análisis o ejecución.