Esta guía paso a paso te ayuda a tomar decisiones sobre todos los problemas de integración principales.
Acceder con Google en el resumen
A continuación, se indican los pasos generales que deben seguir los usuarios para acceder o registrarse en tu sitio web.
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 con un toque y el acceso automático se activan solo cuando los usuarios accedieron 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 les solicita a los usuarios que accedan a Google cuando se presiona el botón.
Los usuarios navegan por tus páginas web en las que se encuentran incorporados los botones One Tap, Acceso automático o Acceder con Google.
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 hiciste.
Cuando solo hay una sesión de Google activa en el navegador,
- One Tap selecciona la única sesión automáticamente 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 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, se mostrará una página de consentimiento.
Una vez que se apruebe, Google registrará la decisión para omitir la página de consentimiento la próxima vez.
Se comparte 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 con un controlador de devolución de llamada de JavaScript o un envío de publicación 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 de tu propia manera. Un buen ejemplo es usar un XmlHttpRequest para evitar la recarga de la página causada por el envío de la publicación.
En el servidor, se valida y consume la credencial JWT emitida por Google para crear una cuenta nueva o establecer una sesión autenticada en tu sitio web.
Administrarás el estado de acceso de los usuarios 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 del acceso, cuando sabes que el usuario se autenticó correctamente y accedió a su Cuenta de Google. Los usuarios pueden permanecer en sus cuentas, salir de ellas o cambiar a una Cuenta de Google diferente mientras mantienen 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 necesites integrar la API de autorización si tu sitio necesita acceder a las APIs y los servicios 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 a tu sitio tokens de acceso (separados) y permisos para usar las APIs y los servicios de Google. Consulta Cómo autorizar para la Web para obtener más información.
Separación de la 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 Cómo separar 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 uses la biblioteca de JavaScript de Google Identity Services, deberás ajustar tu UX para separar el momento de la autenticación del momento de la autorización.
- En el momento de la autenticación, tu sitio web puede integrarse con One Tap, el acceso automático o el botón de 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 para acceder a las APIs o los servicios de Google.
Para lograr una transición de UX fluida y una reducción de la complejidad, una práctica común es dividir el proceso en dos pasos separados.
- Refactoriza la UX para separar los momentos de autenticación y autorización.
Migra a la biblioteca de JavaScript de Google Identity Services.
API de HTML en comparación con la API de JavaScript
Puedes usar la API de HTML o la API de JavaScript para integrar el botón de One Tap, el Acceso automático o Acceder con Google en tus páginas web.
Con la API de HTML, tienes más funciones integradas. Por ejemplo:
- Renderización de 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, que se especifica en el atributo
data-login_uri, después de que se complete la UX de One Tap, el acceso automático o la ventana emergente o el redireccionamiento del botón. - Evita los ataques CSRF con la cookie de doble envío.
- 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 código 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 un 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 de la publicación predeterminada.
Con la API de JavaScript, tienes más flexibilidad en algunas situaciones.
- Renderización de One Tap y el botón Acceder con Google en otro momento Por ejemplo, después de que los usuarios seleccionan Acceder en el menú.
- Llamar a la API varias veces Por ejemplo, el botón Acceder con Google se debe renderizar 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 llamadas a la API en ellas
- Cargarás la biblioteca de JavaScript de Google Identity Services mucho más adelante.
El código de la API de 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 los Servicios de identidad de Google, lo que ocurra más tarde. 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 ni para la renderización de botones y One Tap. Verifica tu código, tanto HTML como JavaScript, para ver si se superponen. Ten en cuenta lo siguiente:
- Estás usando 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 se invoca uno o más de los métodos de
initialize(),prompt()orender()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 botones y One Tap. No tienen las APIs de HTML correspondientes:
Consideraciones sobre el botón de Acceder con Google
En esta sección, se analizan las consideraciones para integrar el botón Acceder con Google en tu sitio web.
Ventana emergente en comparación con el 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, en especial en la Web para computadoras de escritorio, puede brindar una mejor UX a los usuarios finales. Esto se debe a que los usuarios no se redireccionan a páginas de terceros, y una ventana emergente similar a un diálogo proporciona una experiencia en contexto para otorgar permisos.
Con la UX emergente, el proveedor de identidad debe compilar en canales de comunicación entre orígenes del cliente para pasar las respuestas de OAuth de la ventana emergente, donde se muestra la página de consentimiento del proveedor de identidad, a la ventana principal, donde se muestra la página de terceros. Por lo general, se requieren códigos de JavaScript en ambos lados para enviar y recibir la respuesta de OAuth en todas las ventanas.
El botón Acceder con Google admite la UX de la ventana emergente y el redireccionamiento.
De forma predeterminada, se usa la UX emergente. Puedes cambiar la UX configurando 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
POSTpara enviar la credencial a tu servidor web, mientras que el redireccionamiento de OAuth suele usar el métodoGET. - 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.
En el caso de los desarrolladores que usan la API de HTML, sin importar qué UX se use, 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 de UX sin otros cambios de código.
Para la UX de redireccionamiento, se debe agregar data-login_uri a los URIs 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 forma programática.
Para habilitar el flujo del botón Acceder con Google, solo debes renderizar uno o más botones de Acceder con Google en tus páginas web. El flujo de botones se inicia y se controla de forma transparente cuando los usuarios hacen clic en estos botones.
La API de renderización de botones te permite personalizar el aspecto del botón 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, copiarlo en los campos correspondientes de la API de JavaScript.
No hay una API que permita a los sitios web controlar si se debe usar la información personalizada para renderizar los botones. Los botones personalizados se muestran si se cumplen todas las condiciones. Obtén más información en Comprende el botón Personalizado.
Puedes colocar varios botones en la misma página web. El generador de códigos 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 la renderización de botones
Por motivos de privacidad, el botón personalizado se muestra en un iframe del dominio accounts.google.com. La carga de un iframe puede llevar mucho tiempo en una red lenta. Para mitigar este problema de latencia, los botones se renderizan en 2 pasos, como se muestra a continuación:
- Se renderiza una versión de botón intercalado en el árbol de 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.
- Se envía una solicitud de iframe a Google para cargar el iframe del botón, 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 enumeran algunas prácticas recomendadas para minimizar la latencia de la visualización del botón de flujo de 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, especialmente 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 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
La función de acceso automático permite que los usuarios accedan a tu sitio web sin hacer clic en la solicitud de One Tap si ya otorgaron permiso a tu sitio web.
El acceso automático cancelable proporciona los siguientes beneficios.
- Puede mejorar el porcentaje de accesos, ya que guarda una acción del usuario.
- A diferencia del acceso silencioso que proporcionaba la biblioteca de JavaScript de Acceso a Google anterior y obsoleta, los usuarios siempre ven una IU cuando se produce el acceso automático, lo que les brinda el contexto de por qué y cómo accedieron a tu sitio web. Los usuarios también pueden cancelar si así 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.
Debes tomar la decisión de habilitar el acceso automático en función de la UX y los requisitos comerciales 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 forma para que los usuarios recuperen el estado de la sesión.
Cuándo se debe mostrar la IU de One Tap
Con la API de HTML, One Tap siempre se muestra cuando se carga 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 invocar la API debido a los siguientes motivos.
- No hay una sesión de Google activa en el navegador.
- Todas las sesiones activas de Google están inhabilitadas.
- El tiempo de inactividad está en curso.
No intentes mostrar solo la IU de One Tap en un evento de clic en un botón. Es posible que la IU de One Tap no se muestre debido a los motivos mencionados, y es posible que los usuarios tengan 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:
Recomendado
- Muestra el 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 siempre se ofrezca a los usuarios un método de acceso a tu sitio web.
No se recomienda
- Si solo ofreces One Tap, es posible que los usuarios experimenten una experiencia de acceso defectuosa 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 No se recomienda, ya que es posible que la devolución de llamada de estado de la IU no funcione bien con la administración de credenciales federadas en una versión futura.
One Tap en navegadores de 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 cambio, en estos navegadores, se proporciona una UX diferente que comienza con una página de bienvenida.
Si lo deseas, puedes inhabilitar la UX de One Tap en los navegadores de ITP. Consulta Compatibilidad con One Tap en navegadores de ITP para obtener más detalles.
No hay forma de habilitar esta UX en navegadores que no sean de ITP, como Chrome en Android, macOS, Linux y Edge.
Cancela el mensaje si el usuario hace clic en otro lugar
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 el mensaje de One Tap abierto en la Web para computadoras, ya que el tamaño de la pantalla es lo suficientemente grande.
Cambia la posición de la IU de One Tap
En la Web para computadoras, puedes cambiar la posición del mensaje de un toque. Sin embargo, no se recomienda esta función, ya que la administración de credenciales federadas no la admitirá en una versión futura.
Cambia el contexto de acceso
El One Tap debe ser parte de un flujo de UX más grande en tu sitio web. De forma predeterminada, la IU de One Tap se usa en un contexto de acceso. El lenguaje de la IU contiene una redacción particular, como "acceder". Puedes cambiar el atributo de contexto para crear un conjunto diferente de redacción. 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" |
Escucha el estado de la IU de One Tap
Para integrarse sin problemas 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 es compatible con las versiones futuras de la administración de credenciales federadas.
One Tap en subdominios
De forma predeterminada, se realiza un seguimiento del tiempo de inactividad de One Tap y otros estados por origen. Si tu sitio web muestra One Tap en varios subdominios, debes indicarlo en tu código de API.
One Tap en páginas HTML estáticas
De forma predeterminada, la biblioteca de GIS supone 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, no se debe incluir el código HTML de One Tap 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 de One Tap HTML puede funcionar de otra manera, que está diseñada para sitios web que alojan mucho contenido HTML estático. Puedes incluir el código de la API de One Tap HTML 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 existe la cookie de sesión, se omite el flujo de One Tap.
En este caso, el estado de la cookie de sesión controla si se activa el flujo de One Tap, en lugar de la existencia del código de la API de One Tap HTML en tu página web.
Integración del servidor
Después de One Tap, el acceso automático 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 del servidor para recibir y validar el token de ID.
Consideraciones de UX
Por lo general, debes agregar un extremo HTTP en tu propio origen para controlar las respuestas en el servidor. Los siguientes factores pueden tener un impacto en la UX resultante.
- Si se activa One Tap o Acceder con Google
- Si se usa la API de HTML o la de JavaScript.
- Si se usa el URI de acceso o la función de devolución de llamada de JavaScript para controlar la respuesta
La UX real que obtienes se describe de la siguiente manera.
Para el modo de UX de redireccionamiento del botón Acceder con Google, haz lo siguiente:
- Independientemente de si se usa la API de HTML o la 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, ya que los usuarios ya se redireccionaron fuera de tu página web.
- Resumen de la 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.
Cuando termines, se enviará un
POSTde página completa al URI de acceso que especificaste.
Para el modo de UX de la ventana emergente del botón de One Tap o 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, haz lo siguiente:
- Las respuestas de autenticación se pasan a la función de devolución de llamada de JavaScript.
- Resumen de la UX: El mensaje de One Tap o una ventana emergente se muestran sobre la página web. Después de que los usuarios terminan 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 determina según la forma en que la función de devolución de llamada envía las respuestas a tu servidor.
De lo contrario (la API de HTML con el caso de URI de acceso):
- Las respuestas de autenticación se envían al URI de acceso.
- Resumen de la UX: El mensaje de One Tap o una ventana emergente se muestra sobre la página web. Después de que los usuarios terminan 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 con una entrega de
POSTde página completa a la URL de acceso que especificaste.
Te recomendamos 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, haz lo siguiente:
- Para el envío de publicaciones activado por la biblioteca cliente de JavaScript de Google Identity Service, puedes usar el patrón de cookie de doble envío integrado. Consulta Cómo verificar el token de ID de Google en el servidor para obtener más detalles.
- Para enviar a tu propio origen con un XmlHttpRequest, puedes usar el encabezado HTTP personalizado o bien otras medidas de seguridad aprobadas 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
¿Los botones One Tap y Acceder con Google están disponibles en los objetos View web?
No. Debido a problemas de seguridad, los usuarios no deben agregar sesiones de Google a las vistas web. Por lo tanto, los GIS están inhabilitados en las vistas web, ya que no se supone que haya sesiones de Google.
¿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 pudieron 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 de JavaScript de Google Identity Services debe generar todos los botones de Acceder con Google. Existen dos motivos para este cambio.
- Algunos terceros de confianza no siguieron los lineamientos, lo que genera botones de Acceder con Google incoherentes en los sitios web.
- Cuando se genera con la biblioteca, no es necesario realizar ningún cambio cuando cambian los Lineamientos de desarrollo de la marca de acceso.
Para 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?
Te recomendamos que uses 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 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 que se encuentra allí. Si accedes correctamente con el botón Acceder con Google, se borrará el estado de inactividad de One Tap para que se pueda mostrar en el próximo acceso. Otros flujos de botones de Google no pueden borrar los estados de inactividad de One Tap, ya que se encuentran en diferentes objetos binarios de JavaScript.
Si tu sitio web solo habilita el acceso con un toque, pero no el botón Acceder con Google, es posible que observes una disminución del rendimiento de tu flujo de acceso con un toque, ya que los estados de inactividad exponencial no se borran a tiempo.
¿Cuándo se analiza mi código de API de HTML? ¿Puedo cambiar mi código de API de HTML más adelante?
La biblioteca de JavaScript de los Servicios de identidad de Google analiza y ejecuta tu código de API de HTML en el evento de carga de la biblioteca de JavaScript o en el evento DomContentLoaded, lo que ocurra más tarde.
- Si se activa el evento DomContentLoaded cuando se carga la biblioteca de JavaScript, el código de la API de 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 el código de la API de HTML.
Además, ten en cuenta que el análisis y la ejecución del código de la API de HTML son uno.
- Después del análisis y la ejecución, se ignoran los cambios posteriores en el código de la API de HTML.
- No hay una API para que los desarrolladores activen el proceso de análisis o ejecución.