Acceso con Google con las APIs de FedCM

En esta guía, se analiza la adopción de las APIs de FedCM por parte de la biblioteca de la plataforma de Google Sign-in. Los temas incluyen el Cronograma y los Próximos pasos para una actualización retrocompatible de la biblioteca, cómo realizar una evaluación de impacto y verificar que el acceso de los usuarios siga funcionando como se espera y, si es necesario, instrucciones para actualizar tu app web. También se incluyen opciones para administrar el período de transición junto con cómo obtener ayuda.

Estado de la biblioteca

Se bloqueó el uso de la biblioteca obsoleta de la plataforma de Acceso con Google en las apps web nuevas, mientras que las apps que usan la biblioteca pueden seguir usándolas hasta nuevo aviso. No se estableció una fecha de desactivación final (cierre) para la biblioteca. Consulta Baja de la compatibilidad y desactivación para obtener más información.

Una actualización retrocompatible agrega APIs de FedCM a la biblioteca de Acceso con Google. Si bien la mayoría de los cambios son fluidos, la actualización introduce diferencias en las instrucciones para el usuario, la política de permisos del iframe y la Política de Seguridad del Contenido (CSP). Estos cambios pueden afectar a tu app web y requerir cambios en el código de la aplicación y la configuración del sitio.

Durante el período de transición, una opción de configuración controla si se usan o no las APIs de FedCM durante el acceso del usuario.

Después del período de transición, las APIs de FedCM son obligatorias para todas las apps web que usan la biblioteca de Acceso con Google.

Cronograma

Última actualización: septiembre de 2024

Estas son las fechas y los cambios que afectan el comportamiento de acceso de los usuarios:

  • Marzo de 2023: Baja de la compatibilidad con la biblioteca de la plataforma de Acceso con Google.
  • Comienza el período de transición de julio de 2024 y se agrega compatibilidad de la biblioteca de la plataforma de Acceso con Google con las APIs de FedCM. De forma predeterminada, Google controla el porcentaje de solicitudes de acceso de los usuarios con FedCM durante este período. Las apps web pueden anular este comportamiento de forma explícita con el parámetro use_fedcm.
  • Adopción obligatoria en marzo de 2025 de las APIs de FedCM por parte de la biblioteca de la plataforma de Acceso con Google. Después de este proceso, se ignora el parámetro use_fedcm y todas las solicitudes de acceso de los usuarios usan FedCM.

Próximos pasos

Existen tres opciones que puedes seguir:

  1. Realiza una evaluación de impacto y, si es necesario, actualiza tu app web. Con este enfoque, se evalúa si se están usando las funciones que requieren cambios en tu app web. En la siguiente sección de esta guía, se proporcionan instrucciones.
  2. Mueve a la biblioteca de Google Identity Services (GIS). Se recomienda que cambies a la biblioteca de acceso más reciente y compatible. Para ello, sigue estas instrucciones.
  3. No hacer nada. Tu app web se actualizará automáticamente cuando la biblioteca de Acceso con Google se traslade a las APIs de FedCM para el acceso de los usuarios. Esta es la opción que requiere menos trabajo, pero existe el riesgo de que los usuarios no puedan acceder a tu app web.

Realiza una evaluación de impacto

Sigue estas instrucciones para determinar si tu app web se puede actualizar sin problemas mediante una actualización retrocompatible o si se deben realizar cambios para evitar que los usuarios no puedan acceder cuando la biblioteca de la plataforma de Acceso con Google adopte por completo las APIs de FedCM.

Configuración

Las APIs del navegador y la versión más reciente de la biblioteca de la plataforma de Acceso con Google son necesarias para usar FedCM durante el acceso del usuario.

Antes de continuar, ten en cuenta lo siguiente:

  • Actualiza a la versión más reciente de Chrome para computadoras. Chrome para Android requiere la versión M128 o una posterior y no se puede probar con versiones anteriores.
  • Establece use_fedcm en true cuando inicialices la biblioteca de la plataforma de Acceso con Google en tu app web. Por lo general, la inicialización se ve de la siguiente manera:
    • gapi.client.init({use_fedcm: true}) o
    • gapi.auth2.init({use_fedcm: true}) o
    • gapi.auth2.authorize({use_fedcm: true}).
  • Invalida las versiones almacenadas en caché de la biblioteca de la plataforma de Acceso con Google. Por lo general, este paso no es necesario, ya que la versión más reciente de la biblioteca se descarga directamente en el navegador si se incluye api.js, client.js o platform.js en una etiqueta <script src> (la solicitud puede usar cualquiera de estos nombres de paquete para la biblioteca).

  • Confirma la configuración de OAuth para tu ID de cliente de OAuth:

    1. Abre la página Credenciales de la

    2. Verifica que el URI de tu sitio web se incluya en Orígenes autorizados de JavaScript. El URI solo incluye el esquema y el nombre de host completamente calificado. Por ejemplo, https://www.example.com

    3. De manera opcional, las credenciales se pueden mostrar mediante un redireccionamiento a un extremo que alojas en lugar de a través de una devolución de llamada de JavaScript. Si este es el caso, verifica que tus URIs de redireccionamiento se incluyan en URIs de redireccionamiento autorizados. Los URIs de redireccionamiento incluyen el esquema, el nombre de host completamente calificado y la ruta de acceso, y deben cumplir con las reglas de validación de URIs de redireccionamiento. Por ejemplo, https://www.example.com/auth-receiver.

Prueba

Después de seguir las instrucciones de Configuración, haz lo siguiente:

Cómo encontrar la solicitud de la biblioteca de Acceso con Google

Para verificar si son necesarios los cambios en permissions-policy y la Política de Seguridad del Contenido, inspecciona la solicitud de la biblioteca de la plataforma de Acceso con Google. Para ello, busca la solicitud con el nombre y el origen de la biblioteca:

  • En Chrome, abre el panel Red de DevTools y vuelve a cargar la página.
  • Usa los valores de las columnas Domain y Name para ubicar la solicitud de biblioteca:
    • El dominio es apis.google.com y
    • El nombre es api.js, client.js o platform.js. El valor específico de Name depende del paquete de bibliotecas que solicita el documento.

Por ejemplo, filtra por apis.google.com en la columna Dominio y platform.js en la columna Nombre.

Verifica la política de permisos del iframe

Es posible que tu sitio use la biblioteca de la plataforma de Acceso con Google dentro de un iframe de origen cruzado. Si es así, se necesita una actualización.

Después de seguir las instrucciones para encontrar la solicitud de la biblioteca de Acceso con Google, selecciona la solicitud de la biblioteca de Acceso con Google en el panel Red de DevTools y busca el encabezado Sec-Fetch-Site en la sección Encabezados de solicitud de la pestaña Encabezados. Si el valor del encabezado es el siguiente:

  • same-site o same-origin, entonces no se aplican las políticas de origen cruzado y no se necesitan cambios.
  • Es posible que se deban realizar cambios en cross-origin si se usa un iframe.

Para confirmar si hay un iframe, haz lo siguiente:

  • Selecciona el panel Elementos en las Herramientas para desarrolladores de Chrome.
  • Usa Ctrl + F para encontrar un iframe en el documento.

Si se encuentra un iframe, inspecciona el documento para verificar si hay llamadas a funciones de gapi.auth2 o directivas script src que carguen la biblioteca de Acceso con Google dentro del iframe. Si este es el caso, haz lo siguiente:

Repite este proceso para cada iframe del documento. Los iframes se pueden anidar, así que asegúrate de agregar la directiva allow a todos los iframes superiores circundantes.

Cómo verificar la Política de Seguridad del Contenido

Si tu sitio usa una Política de Seguridad del Contenido, es posible que debas actualizarla para permitir el uso de la biblioteca de Acceder con Google.

Después de seguir las instrucciones para encontrar la solicitud de la biblioteca de Acceso con Google, selecciona la solicitud de la biblioteca de Acceso con Google en el panel Red de DevTools y busca el encabezado Content-Security-Policy en la sección Encabezados de respuesta de la pestaña Encabezados.

Si no se encuentra el encabezado, no es necesario realizar cambios. De lo contrario, verifica si alguna de estas directivas de CSP está definida en el encabezado de CSP y actualízalas de la siguiente manera:

  • Agregar https://apis.google.com/js/, https://accounts.google.com/gsi/ y https://acounts.google.com/o/fedcm/ a cualquier directiva connect-src, default-src o frame-src

  • Se agregó https://apis.google.com/js/bundle-name.js a la directiva script-src. Reemplaza bundle-name.js por api.js, client.js o platform.js según el paquete de bibliotecas que solicite el documento.

Cómo verificar si hay cambios en las instrucciones para el usuario

Hay algunas diferencias en el comportamiento de las indicaciones para el usuario. FedCM agrega un diálogo modal que muestra el navegador y actualiza los requisitos de activación del usuario.

Imagen del diálogo modal de FedCM

Inspecciona el diseño de tu sitio para confirmar que el contenido subyacente se pueda superponer de forma segura y ocultar temporalmente con el diálogo modal del navegador. Si no es así, es posible que debas ajustar el diseño o la posición de algunos elementos de tu sitio web.

Activación del usuario

El MTC incluye requisitos actualizados para la activación de los usuarios. Presionar un botón o hacer clic en un vínculo son ejemplos de gestos del usuario que permiten que los orígenes de terceros realicen solicitudes de red o almacenen datos. Con FedCM, el navegador solicita el consentimiento del usuario en los siguientes casos:

  • un usuario accede por primera vez a una app web con una instancia de navegador nueva
  • Se llama a GoogleAuth.signIn.

Actualmente, si el usuario accedió a tu sitio web antes, puedes obtener su información de acceso cuando inicializas la biblioteca de Acceso con Google con gapi.auth2.init, sin más interacciones del usuario. Esto ya no es posible, a menos que el usuario haya pasado por el flujo de acceso de FedCM al menos una vez.

Si habilitas FedCM y llamas a GoogleAuth.signIn, la próxima vez que el mismo usuario visite tu sitio web, gapi.auth2.init podrá obtener la información de acceso del usuario durante la inicialización sin interacción del usuario.

Casos de uso habituales

La documentación para desarrolladores de la biblioteca de Acceder con Google incluye guías y muestras de código para casos de uso comunes. En esta sección, se explica cómo el FedCM afecta su comportamiento.

  • Cómo integrar el Acceso con Google en tu app web

    En esta demo, un elemento <div> y una clase renderizan el botón y, para los usuarios que ya accedieron, el evento onload de la página muestra las credenciales del usuario. Se requiere la interacción del usuario para acceder y establecer una sesión nueva.

    La inicialización de la biblioteca la realiza la clase g-signin2, que llama a gapi.load y gapi.auth2.init.

    Un gesto del usuario, un evento onclick de un elemento <div>, llama a auth2.signIn durante el acceso o a auth2.signOut durante el cierre de sesión.

  • Cómo compilar un botón de Acceso con Google personalizado

    En la demo uno, se usan atributos personalizados para controlar la apariencia del botón de acceso y, para los usuarios que ya accedieron, el evento onload de la página muestra las credenciales del usuario. Se requiere la interacción del usuario para acceder y establecer una sesión nueva.

    La inicialización de la biblioteca se realiza a través de un evento onload para la biblioteca platform.js, y gapi.signin2.render muestra el botón.

    Un gesto del usuario, que presiona el botón de acceso, llama a auth2.signIn.

    En la demostración dos, se usa un elemento <div>, diseños de CSS y un elemento gráfico personalizado para controlar el aspecto del botón de acceso. Se requiere la interacción del usuario para acceder y establecer una sesión nueva.

    La inicialización de la biblioteca se realiza cuando se carga el documento con una función de inicio que llama a gapi.load, gapi.auth2.init y gapi.auth2.attachClickHandler.

    Un gesto del usuario, un evento onclick de elemento <div>, llama a auth2.signIn con auth2.attachClickHandler durante el acceso o auth2.signOut al salir.

  • Supervisa el estado de la sesión del usuario

    En esta demostración, se presiona un botón para que el usuario acceda a su cuenta y salga de ella. Se requiere la interacción del usuario para acceder y establecer una sesión nueva.

    Para inicializar la biblioteca, llama directamente a gapi.load, gapi.auth2.init y gapi.auth2.attachClickHandler() después de cargar platform.js con script src.

    Un gesto del usuario, un evento onclick de elemento <div>, llama a auth2.signIn con auth2.attachClickHandler durante el acceso o auth2.signOut durante el cierre de sesión.

  • Cómo solicitar permisos adicionales

    En esta demo, se presiona un botón para solicitar permisos de OAuth 2.0 adicionales, obtener un token de acceso nuevo y, para los usuarios que ya accedieron, el evento onload de la página muestra las credenciales del usuario. Se requiere la interacción del usuario para acceder y establecer una sesión nueva.

    El evento onload de la biblioteca platform.js realiza la inicialización de la biblioteca a través de una llamada a gapi.signin2.render.

    Un gesto del usuario, hacer clic en un elemento <button>, activa una solicitud de permisos de OAuth 2.0 adicionales con googleUser.grant o auth2.signOut cuando se cierra la sesión.

  • Cómo integrar el Acceso con Google con objetos de escucha

    En esta demo, para los usuarios que ya accedieron, el evento onload de la página muestra las credenciales del usuario. Se requiere la interacción del usuario para acceder y establecer una sesión nueva.

    La inicialización de la biblioteca se realiza cuando se carga el documento con una función de inicio que llama a gapi.load, gapi.auth2.init y gapi.auth2.attachClickHandler. A continuación, se usan auth2.isSignedIn.listen y auth2.currentUser.listen para configurar la notificación de cambios en el estado de la sesión. Por último, se llama a auth2.SignIn para que devuelva las credenciales de los usuarios que accedieron.

    Un gesto del usuario, un evento onclick de elemento <div>, llama a auth2.signIn con auth2.attachClickHandler durante el acceso o auth2.signOut durante el cierre de sesión.

  • Acceso con Google para apps del servidor

    En esta demo, se usa un gesto del usuario para solicitar un código de autenticación de OAuth 2.0, y una devolución de llamada de JS realiza una llamada AJAX para enviar la respuesta al servidor de backend para su verificación.

    La inicialización de la biblioteca se realiza con un evento onload para la biblioteca platform.js, que usa una función de inicio para llamar a gapi.load y gapi.auth2.init.

    Un gesto del usuario, que hace clic en un elemento <button>, activa una solicitud de un código de autorización llamando a auth2.grantOfflineAccess.

  • SSO multiplataforma

    FedCM requiere el consentimiento para cada instancia del navegador, incluso si los usuarios de Android ya accedieron a sus cuentas. Es necesario un consentimiento único.

Administra el período de transición

Durante el período de transición, es posible que un porcentaje de los accesos de los usuarios use FedCM. El porcentaje exacto puede variar con el tiempo. De forma predeterminada, Google controla cuántas solicitudes de acceso usan FedCM, pero puedes habilitar o inhabilitar el uso de FedCM durante el período de transición. Al final del período de transición, el FedCM se vuelve obligatorio y se usa para todas las solicitudes de acceso.

Si aceptas la opción, el usuario pasará por el flujo de acceso de FedCM, mientras que si la rechazas, pasará por el flujo de acceso existente. Este comportamiento se controla con el parámetro use_fedcm.

Habilitar

Puede ser útil controlar si todos o algunos de los intentos de acceso a tu sitio usan las APIs de FedCM. Para ello, establece use_fedcm en true cuando inicialices la biblioteca de la plataforma. En este caso, la solicitud de acceso del usuario usa las APIs de FedCM.

Inhabilitación

Durante el período de transición, un porcentaje de los intentos de acceso de los usuarios a tu sitio usará las APIs de FedCM de forma predeterminada. Si necesitas más tiempo para realizar cambios en tu app, puedes inhabilitar temporalmente el uso de las APIs de FedCM. Para ello, establece use_fedcm en false cuando inicialices la biblioteca de la plataforma. En este caso, la solicitud de acceso del usuario no usará las APIs de FedCM.

Después de que se produce la adopción obligatoria, la biblioteca de la plataforma de Acceso con Google ignora cualquier configuración de use_fedcm.

Obtener ayuda

Busca o haz preguntas en StackOverflow con la etiqueta google-signin.