Cómo migrar desde el Acceso con Google

Esta guía te ayuda a comprender los cambios y los pasos necesarios para migrar de forma correcta 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 la API de Google para JavaScript o otras bibliotecas anteriores para la autorización, consulta Cómo migrar 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, por lo general, se conoce como registro o acceso del usuario. La autorización es el proceso de otorgar o rechazar el acceso a datos o recursos. Por ejemplo, tu app solicita el consentimiento del usuario para acceder a su cuenta de Google Drive.

Al igual que la biblioteca de la plataforma de Google Sign-In anterior, la nueva biblioteca de Google Identity Services está diseñada 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 los desarrolladores a la hora de integrar Cuentas de Google en tu app.

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

Si tu caso de uso incluye autorización, consulta Cómo funciona la autorización de usuarios 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 varias mejoras de usabilidad. Se incluyen los siguientes aspectos destacados:

• Nuevos flujos de acceso automático y One Tap de baja fricción con menos pasos individuales
• un botón de acceso actualizado con personalización del usuario
• el desarrollo de un desarrollo de la marca coherente y un comportamiento de acceso uniforme en toda la Web mejora la comprensión y la confianza.
• llegar rápidamente al contenido; los usuarios pueden registrarse y acceder directamente desde cualquier parte de tu sitio sin tener que visitar primero una página de acceso o de la cuenta.

Para los desarrolladores, nos enfocamos en reducir la complejidad, mejorar la seguridad y hacer que la integración sea lo más rápida posible. Estas son algunas de las mejoras:

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

Ejemplo de migración de acceso

Si migras desde el botón de acceso de Google existente 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, puedes 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 de los usuarios. 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 las cargas de gapi.client apis.google.com/js/api.js

En la mayoría de los casos, puedes seguir usando las credenciales de ID de cliente de tu aplicación web existente. Como parte de la migración, te recomendamos que revises nuestras Políticas de OAuth 2.0 y que uses la Consola de API 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”.
• HTTPS se usa 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 después de la baja.

En 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 funciones que pronto dejarán de estar disponibles en la consola, establece el valor de la cookie G_AUTH2_MIGRATION en informational. De forma opcional, agrega dos puntos seguidos de un valor de clave para registrarte también en el almacenamiento de sesión. Después de acceder y recibir las credenciales, revisa o envía los registros recopilados a un backend para analizarlos más adelante. 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 forzosa.

Valores posibles de la cookie G_AUTH2_MIGRATION:

• enforced No cargue el módulo gapi.auth2.
• informational Se registra el uso de funciones obsoletas en la consola de JS. Además, registra el almacenamiento de la sesión cuando se configure un nombre de clave opcional: informational:key-name.

Para minimizar el impacto en el usuario, se recomienda configurar esta cookie de manera local durante el desarrollo y las pruebas antes de usarla en entornos de producción.

HTML y JavaScript

En esta situación de acceso solo de autenticación, se muestran el código de ejemplo y las renderizaciones del botón de Acceso con Google existente. Selecciona el modo Popup o Redireccionamiento para ver las diferencias en la forma en que se controla la respuesta de autenticación, ya sea mediante una devolución de llamada de JavaScript o un redireccionamiento seguro al extremo de acceso de tu servidor de backend.

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 biblioteca nueva en una situación de acceso de solo autenticación, selecciona el modo Popup o Redirect y usa la muestra de código para reemplazar la implementación existente en tu 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 a la biblioteca apis.google.com/js/platform.js y al 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 One Tap. Independientemente de dónde muestres el botón personalizado, te recomendamos que también muestres la ventana emergente de One Tap para minimizar los inconvenientes de los usuarios durante el registro y el acceso.

Aunque no se recomienda debido a la mayor fricción del 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 funcionalmente equivalente o combinar las APIs de HTML y JavaScript en tu sitio.

Para ver de forma interactiva las opciones de personalización de botones, como el tipo de devolución de llamada y 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 HTML para usarlos en tu sitio.

Accede desde cualquier página con One Tap

One Tap es una nueva forma sencilla de que los usuarios se registren en tu sitio o accedan a él. 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 de registro y acceso, ya que les brinda a los usuarios la flexibilidad de registrarse y acceder desde páginas que no sean la página 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 algún otro objeto compartido en todo tu sitio.

También te recomendamos que agregues g_id_signin, que muestra el botón de acceso personalizado, solo en tus páginas de acceso o administración de cuentas de usuario. Para brindarles a los usuarios opciones de registro o acceso, muestra el botón junto con otros botones del proveedor de identidad federado y los campos de entrada de nombre de usuario y contraseña.

Respuesta de token

Para el acceso de usuarios, ya no es necesario que comprendas códigos de autorización, tokens de acceso o de actualización de OAuth 2.0 ni trabajes con ellos. 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 "get" para trabajar con los datos del perfil del usuario.

Se muestra una credencial de token de ID JWT segura firmada por Google en los siguientes casos:

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

En ambos casos, quita lo siguiente para actualizar los controladores de devolución de llamada existentes:

• 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 credential en el nuevo objeto CredentialResponse de JWT para trabajar con los datos del perfil del usuario.

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

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

Consentimiento del usuario y revocación del permiso

Cuando un usuario accede a tu sitio web por primera vez, Google le solicita su consentimiento para compartir el perfil de su cuenta con tu app. Solo después de proporcionar el consentimiento, el perfil del usuario se comparte 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 los permisos y desconectar tu app de su Cuenta de Google si visitan 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 salida del usuario de tu app. Se debe quitar cualquier uso de auth2.signOut(), y tu app debe administrar directamente el estado de la sesión y el estado de acceso de cada usuario.

Estado de la sesión y objetos de escucha

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

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

El estado de acceso del usuario a su Cuenta de Google 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.

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 lo siguiente:

• dar su consentimiento para compartir su perfil de usuario cuando se registre por primera vez o acceda a tu sitio
• y, más tarde, para acceder en visitas posteriores a tu sitio.

Los usuarios pueden permanecer conectados, salir o cambiar de Cuenta de Google mientras mantienen una sesión activa y abierta en tu sitio web.

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

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

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

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

Cookies

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

Ya no se usa la cookie G_ENABLED_IDPS que establece la biblioteca anterior de la plataforma de Acceso con Google.

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

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

• g_csrf_token es una cookie de envío doble que se usa para evitar ataques CSRF y se establece cuando se llama a tu extremo de acceso. El valor de tu URI de acceso se puede establecer de manera explícita o se puede establecer de forma predeterminada 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 configura data-login_uri

  • API de JavaScript con ux_mode=redirect y en la que no se usa google.accounts.id.prompt() 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 el acceso con un toque 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 de usuarios