Cómo migrar desde el Acceso con Google

Esta guía te ayuda a comprender los cambios y los pasos necesarios para migrar correctamente las bibliotecas de JavaScript de la biblioteca de la plataforma de Acceso con Google anterior a la biblioteca de Google Identity Services más reciente para la autenticación.

Si tu cliente usa la biblioteca cliente de las APIs de Google para JavaScript o alguna otra biblioteca anterior para la autorización, consulta Migra a los Servicios de identidad de Google para obtener más información.

Autenticación y autorización

La autenticación establece quién es una persona y se conoce comúnmente como registro o acceso del usuario. La autorización es el proceso de otorgar o rechazar el acceso a los datos o recursos. Por ejemplo, tu app solicita el consentimiento del usuario para acceder a su Google Drive.

Al igual que la anterior biblioteca de la plataforma de Acceso con Google, la nueva biblioteca de Google Identity Services se creó para admitir los procesos de autenticación y autorización.

Sin embargo, la biblioteca más reciente separa los dos procesos para reducir la complejidad de la integración de Cuentas de Google con tu app para los desarrolladores.

Si tu caso de uso solo se relaciona con la autenticación, sigue leyendo esta página.

Si tu caso de uso incluye la autorización, lee Cómo funciona la autorización del usuario y Migra a Google Identity Services para asegurarte de que tu aplicación use las APIs nuevas y mejoradas.

Qué cambió

Para los usuarios, la nueva biblioteca de Google Identity Services ofrece numerosas mejoras en la usabilidad. Entre los aspectos destacados, se incluyen los siguientes:

• Nuevos flujos de acceso automático y con One Tap de baja fricción con menos pasos individuales
• Un botón de acceso actualizado con personalización para el usuario
• La marca coherente y el comportamiento de acceso uniforme en la Web mejoran la comprensión y la confianza.
• Acceder rápidamente al contenido: Los usuarios pueden registrarse y acceder directamente desde cualquier lugar de tu sitio sin tener que visitar primero una página de acceso o de cuenta.

Para los desarrolladores, nuestro objetivo ha sido reducir la complejidad, mejorar la seguridad y hacer que la integración sea lo más rápida posible. Algunas de estas mejoras incluyen lo siguiente:

• La opción para agregar el acceso del usuario al contenido estático de tu sitio solo con HTML
• separación de la autenticación de acceso de la autorización y el uso compartido de datos del usuario, la complejidad de una integración de OAuth 2.0 ya no es necesaria para permitir que los usuarios accedan a tu sitio.
• Se siguen admitiendo los modos de redireccionamiento y ventana emergente, pero la infraestructura de OAuth 2.0 de Google ahora redirecciona al extremo de acceso de tu servidor backend.
• Consolidación de las capacidades de las bibliotecas anteriores de Google Identity y de la API de Google en JavaScript en una sola biblioteca nueva
• En el caso de las respuestas de acceso, ahora puedes decidir si usar o no una Promise, y se quitó la indirección a través de funciones de estilo getter para mayor simplicidad.

Ejemplo de migración de acceso

Si migras desde el botón existente de Acceder con Google y solo te interesa que los usuarios accedan a tu sitio, el cambio más sencillo es actualizar al nuevo botón personalizado. Para ello, debes intercambiar las bibliotecas de JavaScript y actualizar tu base de código para usar un nuevo objeto de acceso.

Bibliotecas y configuración

La biblioteca anterior de la plataforma de Acceso con Google, apis.google.com/js/platform.js, y la biblioteca cliente de las APIs de Google para JavaScript, gapi.client, ya no son necesarias para la autenticación y autorización del usuario. Se reemplazaron por una sola biblioteca nueva de JavaScript de Google Identity Services: accounts.google.com/gsi/client.

Los tres módulos de JavaScript anteriores: api, client y platform que se usan para el acceso se cargan desde apis.google.com. Para ayudarte a identificar las ubicaciones en las que se podría incluir la biblioteca anterior en tu sitio, por lo general, haz lo siguiente:

• el botón de acceso predeterminado carga apis.google.com/js/platform.js,
• Se carga un gráfico de botón personalizado apis.google.com/js/api:client.js.
• uso directo de gapi.client cargas apis.google.com/js/api.js

En la mayoría de los casos, puedes seguir usando tus credenciales existentes del ID de cliente de la aplicación web. Como parte de la migración, te recomendamos que revises nuestras Políticas de OAuth 2.0 y uses la Consola de APIs de Google para confirmar y, si es necesario, actualizar la siguiente configuración del cliente:

• Tus apps de prueba y producción usan proyectos separados y tienen sus propios IDs de cliente.
• El tipo de ID de cliente de OAuth 2.0 es "Aplicación web".
• Se usa HTTPS para los orígenes de JavaScript autorizados y los URIs de redireccionamiento.

Identifica el código afectado y realiza pruebas

Una cookie de depuración puede ayudar a ubicar el código afectado y a probar el comportamiento posterior a la baja.

En las apps grandes o complejas, puede ser difícil encontrar todo el código afectado por la baja del módulo gapi.auth2. Para registrar el uso existente de las capacidades que pronto se dejarán de usar en la consola, establece el valor de la cookie G_AUTH2_MIGRATION en informational. De manera opcional, agrega dos puntos seguidos de un valor de clave para también registrarlo en el almacenamiento de sesión. Después de acceder y recibir la revisión de credenciales o enviar los registros recopilados a un backend para su análisis posterior Por ejemplo, informational:showauth2use guarda el origen y la URL en una clave de almacenamiento de sesión llamada showauth2use.

Para verificar el comportamiento de la app cuando ya no se carga el módulo gapi.auth2, establece el valor de la cookie G_AUTH2_MIGRATION en enforced. Esto permite probar el comportamiento posterior a la baja antes de la fecha de aplicación.

Valores posibles de la cookie G_AUTH2_MIGRATION:

• enforced No cargues el módulo gapi.auth2.
• informational Se registra el uso de capacidades obsoletas en la consola de JS. También se registra en el almacenamiento de sesión cuando se establece un nombre de clave opcional: informational:key-name.

Para minimizar el impacto en los usuarios, se recomienda que primero establezcas esta cookie de forma local durante el desarrollo y las pruebas, antes de usarla en entornos de producción.

HTML y JavaScript

En este caso de acceso solo con autenticación, se muestran ejemplos de código y renderizaciones del botón existente de Acceder con Google. Selecciona el modo de ventana emergente o redireccionamiento para ver las diferencias en la forma en que se controla la respuesta de autenticación, ya sea a través de una devolución de llamada de JavaScript o de un redireccionamiento seguro al extremo de acceso del servidor de backend.

El método anterior

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Método nuevo

Para usar la nueva biblioteca en una situación de acceso solo con autenticación, selecciona el modo de ventana emergente o redireccionamiento, y usa la muestra de código para reemplazar tu implementación existente en la página de acceso.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

En este ejemplo de solo autenticación, la nueva biblioteca accounts.google.com/gsi/client, la clase g_id_signin y el objeto g_id_onload reemplazan la biblioteca apis.google.com/js/platform.js y el objeto g-signin2 anteriores.

Además de renderizar el nuevo botón personalizado, el código de ejemplo también muestra la nueva ventana emergente de Un toque. Te recomendamos que, dondequiera que muestres el botón personalizado, también muestres la ventana emergente de One Tap para minimizar la fricción del usuario durante el registro y el acceso.

Aunque no se recomienda debido a la mayor fricción en el acceso, el nuevo botón personalizado se puede mostrar solo, sin mostrar simultáneamente el diálogo de One Tap. Para ello, establece el atributo data-auto_prompt en false.

APIs de HTML y JavaScript

En el ejemplo anterior, se muestra cómo usar la nueva API de HTML para agregar el acceso a tu sitio web. Como alternativa, puedes usar la API de JavaScript, que es funcionalmente equivalente, o combinar las APIs de HTML y JavaScript en tu sitio.

Para ver de forma interactiva las opciones de personalización de los botones, como el tipo de devolución de llamada y los atributos, como el color, el tamaño, la forma, el texto y el tema, consulta nuestro Generador de código. Se puede usar para comparar rápidamente diferentes opciones y generar fragmentos de HTML para usar en tu sitio.

Accede desde cualquier página con One Tap

One Tap es una nueva forma de baja fricción para que los usuarios se registren o accedan a tu sitio. Te permite habilitar el acceso de los usuarios directamente desde cualquier página de tu sitio y elimina la necesidad de que los usuarios visiten una página de acceso dedicada. En otras palabras, esto reduce los inconvenientes en el registro y el acceso, ya que les brinda a los usuarios la flexibilidad de registrarse y acceder desde páginas que no sean la de acceso.

Para habilitar el acceso desde cualquier página, te recomendamos que incluyas g_id_onload en un encabezado, pie de página o cualquier otro objeto compartido que se incluya en todo tu sitio.

También recomendamos agregar g_id_signin, que muestra el botón de acceso personalizado, solo en las páginas de acceso o de administración de cuentas de usuario. Ofrece a los usuarios opciones para registrarse o acceder mostrando el botón junto con otros botones de proveedores de identidad federada y campos de entrada de nombre de usuario y contraseña.

Respuesta de token

El acceso del usuario ya no requiere que comprendas ni trabajes con códigos de autorización, tokens de acceso o tokens de actualización de OAuth 2.0. En su lugar, se usa un token de ID de token web JSON (JWT) para compartir el estado de acceso y el perfil del usuario. Como una simplificación adicional, ya no es necesario que uses métodos de acceso de estilo "getter" para trabajar con los datos del perfil del usuario.

Se devuelve una credencial de token de ID de JWT segura y firmada por Google de una de las siguientes maneras:

• al controlador de devolución de llamada de JavaScript basado en el navegador del usuario en modo emergente
• a tu servidor de backend a través de un redireccionamiento de Google a tu endpoint de acceso cuando el botón Acceder con Google ux_mode está configurado como redirect.

En ambos casos, actualiza los controladores de devolución de llamada existentes quitando lo siguiente:

• Llamadas a googleUser.getBasicProfile()
• Referencias a BasicProfile y llamadas asociadas a los métodos getId(), getName(), getGivenName(), getFamilyName(), getImageUrl() y getEmail()
• uso del objeto AuthResponse

En su lugar, usa referencias directas a los subcampos de credential en el nuevo objeto CredentialResponse de JWT para trabajar con los datos del perfil del usuario.

Además, y solo para el modo de redireccionamiento, asegúrate de evitar la falsificación de solicitudes entre sitios (CSRF) y de verificar el token de ID de Google en tu servidor de backend.

Para comprender mejor cómo interactúan los usuarios con tu sitio, se puede usar el campo select_by en CredentialResponse para determinar el resultado del consentimiento del usuario y el flujo de acceso específico que se usó.

Consentimiento del usuario y revocación de permisos

Cuando un usuario accede por primera vez a tu sitio web, Google le solicita su consentimiento para compartir el perfil de su cuenta con tu app. Solo después de que el usuario otorga su consentimiento, se comparte su perfil con tu app en una carga útil de credenciales de token de ID. Revocar el acceso a este perfil equivale a revocar un token de acceso en la biblioteca de acceso anterior.

Los usuarios pueden revocar permisos y desconectar tu app de su Cuenta de Google en https://myaccount.google.com/permissions. Como alternativa, pueden desconectarse directamente de tu app activando una llamada a la API que implementes. El método anterior disconnect se reemplazó por el método más reciente revoke.

Cuando un usuario borra su cuenta en tu plataforma, se recomienda usar revoke para desconectar tu app de su Cuenta de Google.

Anteriormente, se podía usar auth2.signOut() para ayudar a administrar el cierre de sesión de los usuarios en tu app. Se debe quitar todo uso de auth2.signOut(), y tu app debe administrar directamente el estado de la sesión por usuario y el estado de acceso.

Estado de la sesión y objetos de escucha

La nueva biblioteca no mantiene el estado de acceso ni el estado de sesión de tu app web.

El estado de acceso de una Cuenta de Google, el estado de la sesión de tu app y el estado de acceso son conceptos distintos y separados.

El estado de acceso del usuario a su Cuenta de Google y a tu app son independientes entre sí, excepto durante el momento del acceso en sí, cuando sabes que el usuario se autenticó correctamente y accedió a su Cuenta de Google.

Cuando se incluyen Acceder con Google, One Tap o el acceso automático en tu sitio, los usuarios primero deben acceder a su Cuenta de Google para realizar las siguientes acciones:

• dar su consentimiento para compartir su perfil de usuario cuando se registren o accedan por primera vez a tu sitio
• y, luego, para acceder a tu cuenta en las visitas posteriores a tu sitio.

Los usuarios pueden permanecer con la sesión iniciada, salir de ella o cambiar a otra Cuenta de Google mientras mantienen una sesión activa con acceso en tu sitio web.

Ahora eres responsable de administrar directamente el estado de acceso de los usuarios de tu aplicación web. Anteriormente, el Acceso con Google ayudaba a supervisar el estado de la sesión del usuario.

Quita cualquier referencia a auth2.attachClickHandler() y a sus controladores de devolución de llamada registrados.

Anteriormente, se usaban los Listeners para compartir los cambios en el estado de acceso de la Cuenta de Google de un usuario. Ya no se admiten los objetos de escucha.

Quita cualquier referencia a listen(), auth2.currentUser y auth2.isSignedIn.

Cookies

Acceder con Google hace un uso limitado de las cookies, cuya descripción se incluye a continuación. Consulta Cómo usa Google las cookies para obtener más información sobre los otros tipos de cookies que utiliza Google.

Ya no se usa la cookie G_ENABLED_IDPS establecida por la versión anterior de la biblioteca de la Plataforma de acceso con Google.

De manera opcional, la nueva biblioteca de Google Identity Services puede establecer estas cookies de dominio cruzado según tus opciones de configuración:

• g_state almacena el estado de salida del usuario y se configura cuando se usa la ventana emergente de One Tap o el acceso automático.

• g_csrf_token es una cookie de doble envío que se usa para evitar ataques de CSRF y se configura cuando se llama a tu extremo de acceso. El valor de tu URI de acceso puede establecerse de forma explícita o puede establecerse de forma predeterminada en el URI de la página actual. Es posible que se llame a tu extremo de acceso en las siguientes condiciones cuando uses lo siguiente:

  • API de HTML con data-ux_mode=redirect o cuando se establece data-login_uri

  • API de JavaScript con ux_mode=redirect y donde google.accounts.id.prompt() no se usa para mostrar One Tap o el acceso automático.

Si tienes un servicio que administra cookies, asegúrate de agregar las dos cookies nuevas y quitar la anterior cuando se complete la migración.

Si administras varios dominios o subdominios, consulta Cómo mostrar One Tap en subdominios para obtener más instrucciones sobre cómo trabajar con la cookie g_state.

Referencia de migración de objetos para el acceso del usuario