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 según lo esperado 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 impide que las apps web nuevas usen la biblioteca obsoleta de la plataforma de Acceso con Google, mientras que las apps que la usan pueden continuar hasta nuevo aviso. No se estableció una fecha final de desactivación (apagado) 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 no presentan inconvenientes, la actualización presenta diferencias en los mensajes del usuario, la política de permisos de 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 tiempo. 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 ese momento, se ignorará el parámetro use_fedcm y todas las solicitudes de acceso de los usuarios usarán FedCM.

Próximos pasos

Existen tres opciones que puedes seguir:

  1. Realiza una evaluación del impacto y, si es necesario, actualiza la app web. Este enfoque evalúa si se usan funciones que requieren cambios en la app web. Las instrucciones se proporcionan en la siguiente sección de esta guía.
  2. Mueve a la biblioteca de Google Identity Services (GIS). Se recomienda cambiar a la biblioteca de acceso más reciente y compatible. Para hacerlo, 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 a través de una actualización retrocompatible o si los cambios son necesarios para evitar que los usuarios no puedan acceder cuando la biblioteca de la plataforma de Acceso con Google adopta 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.

  • Abre chrome://flags y establece los siguientes atributos con estos valores:

    • #fedcm-authz habilitado
    • #tracking-protection-3pcd habilitado
    • #third-party-cookie-deprecation-trial Inhabilitada
    • #tpcd-metadata-grants inhabilitado
    • #tpcd-heuristics-grants Inhabilitado

    y reinicia Chrome.

  • 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 incluyendo api.js, client.js o platform.js en una etiqueta <script src> (la solicitud puede usar cualquiera de estos nombres de paquetes para la biblioteca).

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

    1. Abre la página Credenciales de la Google API Console

    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:

Ubica la solicitud a 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 en 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 Domain y platform.js en la columna Name.

Verifica la política de permisos de 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 Elements 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 la CSP está definida en el encabezado de la 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 agrega a 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.

Verifica si hay cambios en el mensaje del usuario

Existen algunas diferencias en el comportamiento de las instrucciones del 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 realizado 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 su información de acceso 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 está a cargo de 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, cuando presiona el botón de acceso, llama a auth2.signIn.

    En la demostración dos, se usan un elemento <div>, estilos de CSS y un gráfico personalizado para controlar la apariencia 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 durante el cierre de sesión.

  • 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 nueva sesión.

    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 del elemento <div>, llama a auth2.signIn con auth2.attachClickHandler durante el acceso o auth2.signOut cuando sales.

  • Cómo solicitar permisos adicionales

    En esta demo, se presiona un botón para solicitar permisos adicionales de OAuth 2.0, 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 demostración, para los usuarios que ya accedieron, el evento onload de la página muestra las credenciales de 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 al salir.

  • 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.

Cuando se elige la habilitación, se envía al usuario a través del flujo de acceso de FedCM, mientras que, si lo hace, se envía al usuario a través del 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 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.