Migra desde el Acceso con Google

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

Si tu cliente usa la biblioteca cliente de la API de Google para JavaScript o alguna otra biblioteca anterior con el fin de realizar 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 un usuario y, por lo general, se denomina registro o acceso de 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 Acceso con Google anterior, la nueva biblioteca de Google Identity Services está diseñada para admitir procesos de autenticación y autorización.

Sin embargo, la biblioteca más nueva separa los dos procesos para reducir la complejidad que tienen los desarrolladores a la hora de integrar Cuentas de Google a tu app.

Si tu caso de uso solo involucra la autenticación, continúa leyendo esta página.

Si tu caso de uso incluye autorización, lee 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 baja fricción con One Tap y Acceso automático con menos pasos individuales.
  • un botón de acceso actualizado con personalización del usuario
  • un desarrollo de la marca coherente y un comportamiento uniforme de acceso en la Web mejoran la comprensión y la confianza,
  • los usuarios pueden registrarse y acceder directamente desde cualquier parte de tu sitio sin tener que visitar una página de acceso o de cuenta.

Para los desarrolladores, nuestro enfoque ha sido 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 acceso de 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 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,
  • los modos de ventana emergente y redireccionamiento siguen siendo compatibles, 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 JavaScript anteriores de Google Identity y de la API de Google en una nueva biblioteca única,
  • para las respuestas de acceso, ahora debes decidir si usar o no una promesa; además, se quitó la indirección a través de las funciones de estilo del método get para simplificar la tarea.

Un ejemplo de migración de acceso

Si migras desde el botón existente de Acceso 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. Esto se puede lograr si se cambian las bibliotecas de JavaScript y se actualiza 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 única biblioteca 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 acceder se cargan desde apis.google.com. Para ayudarte a identificar las ubicaciones en las que la biblioteca anterior podría estar incluida en tu sitio, haz lo siguiente:

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

En la mayoría de los casos, puedes seguir usando las credenciales existentes de ID de cliente de la aplicación web. Como parte de la migración, te recomendamos revisar nuestras Políticas de OAuth 2.0 y usar 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 ID de cliente.
  • el tipo de ID de cliente de OAuth 2.0 es "aplicación web", y
  • Se usa HTTPS para orígenes autorizados de JavaScript y URI de redireccionamiento.

Identifica el código afectado y realiza pruebas

Una cookie de depuración puede ayudar a ubicar el código afectado y probar el comportamiento posterior a 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 en la consola el uso existente de funciones que pronto serán obsoletas, establece el valor de la cookie G_AUTH2_MIGRATION en informational. De manera opcional, agrega dos puntos seguidos de un valor de clave para registrar 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 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 el módulo gapi.auth2 ya no esté cargado, 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 se carga el módulo gapi.auth2.
  • informational Registra el uso de las capacidades obsoletas en la consola de JS. También registra el almacenamiento de la sesión cuando se establece un nombre de clave opcional: informational:key-name.

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

HTML y JavaScript

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

El método anterior

Renderiza el botón de Acceso con Google y usa una devolución de llamada para controlar el acceso directamente desde el navegador del usuario.

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

Modo de redireccionamiento

Renderiza el botón de Acceso con Google, que finaliza con una llamada AJAX desde el navegador del usuario al extremo de acceso de tus servidores de backend.

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

Procesado

Los nuevos atributos visuales simplifican el método anterior de creación de un botón personalizado, eliminan las llamadas a gapi.signin2.render() y la necesidad de alojar y mantener imágenes y recursos visuales en tu sitio.

Acceso con Google

Acceso con Google

Texto del botón de actualizaciones de estado de acceso del usuario.

La nueva forma

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

Usa una devolución de llamada para controlar el acceso directamente desde el navegador del usuario.

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

Modo de redireccionamiento

Google invoca el extremo de acceso como lo especifica el atributo data-login_url. Anteriormente, fuiste responsable de la operación POST y el nombre del parámetro. La biblioteca nueva publica el token de ID en tu extremo en el parámetro credential. Por último, verifica el token de ID en tu servidor de backend.

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

Procesado

Usa visual-attributes para personalizar el tamaño, la forma y el color del botón Acceder con Google. Muestra la ventana emergente de One Tap junto con el botón personalizado para mejorar la tasa de acceso.

Botón Acceder con Google ventana emergente con One Tap

El estado de acceso del usuario no actualiza el texto del botón de “Acceder” a “Accediste”. Después de proporcionar el consentimiento, o de las visitas recurrentes, el botón personalizado incluye el nombre, el correo electrónico y la foto de perfil del usuario.

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, en el código de ejemplo también se muestra la nueva ventana emergente de One Tap. Dondequiera que muestres el botón personalizado, te recomendamos que también muestres la ventana emergente de One Tap para minimizar las fricciones del usuario durante el registro y el acceso.

Aunque no se recomienda debido a la mayor fricción de 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 acceso a tu sitio web. Como alternativa, puedes usar la API de JavaScript que es equivalente en cuanto a las funciones o combinar y hacer coincidir las API 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 HTML para usar en tu sitio.

Accede desde cualquier página con One Tap

One Tap es una nueva forma sencilla de que los usuarios se registren o accedan a tu sitio. Te permite habilitar el acceso de los usuarios directamente desde cualquier página del sitio y elimina la necesidad de que visiten una página de acceso dedicada. En otras palabras, esto reduce las dificultades de registro y 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 incluir g_id_onload en un encabezado, pie de página o algún otro objeto compartido que se incluya en todo el sitio.

También recomendamos agregar g_id_signin, que muestra el botón de acceso personalizado, solo en tus 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 a otros botones de proveedores de identidad federados y campos de entrada de nombre de usuario y contraseña.

Respuesta del token

El acceso de usuarios ya no requiere que comprendas los códigos de autorización de OAuth 2.0, los tokens de acceso o los tokens de actualización ni que 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. Para simplificar aún más, ya no es necesario que uses métodos de acceso de estilo "get" a fin de trabajar con datos de perfil de usuario.

Se muestra una credencial de token de ID de JWT firmado por Google de forma segura:

  • al controlador de devolución de llamada de JavaScript basado en el navegador del usuario en 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 se establece en 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(), y
  • uso del objeto AuthResponse.

En su lugar, usa referencias directas a los subcampos credential en el objeto CredentialResponse nuevo del JWT para trabajar con 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 verificar el token de ID de Google en tu servidor de backend.

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

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 darlo, el perfil del usuario se comparte con tu app en una carga útil de credencial 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 en https://myaccount.google.com/permissions. Como alternativa, es posible que se desconecten directamente de tu app activando una llamada a la API que implementes. El método disconnect anterior se reemplazó por el método revoke más nuevo.

Cuando un usuario borra su cuenta en tu plataforma, la práctica recomendada es 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 del usuario en tu app. Se debe quitar cualquier uso de auth2.signOut(), y tu app debería administrar directamente el estado de 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 el de la sesión de tu app web.

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

Los estados de acceso del usuario a su Cuenta de Google y a 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 incluye Acceso con Google, One Tap o Acceso automático en tu sitio, los usuarios deben acceder primero a su Cuenta de Google para hacer lo siguiente:

  • dar su consentimiento para compartir su perfil de usuario cuando se registra o accede a su sitio por primera vez
  • y, luego, para el acceso en las visitas recurrentes a tu sitio.

Los usuarios pueden permanecer conectados, salir o cambiar a otra Cuenta de Google y, al mismo tiempo, mantener una sesión activa 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 con la supervisión del estado de la sesión del usuario.

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

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

Quita las referencias a listen(), auth2.currentUser y auth2.isSignedIn.

Galletas

Acceder con Google usa cookies de forma limitada, a continuación se incluye una descripción de ellas. Para obtener más información acerca de otros tipos de cookies que utiliza Google, consulta Cómo Google usa cookies.

Ya no se usa la cookie G_ENABLED_IDPS establecida por la biblioteca de la plataforma de Acceso con Google anterior.

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

  • g_state almacena el estado de cierre de sesión 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 de CSRF y se establece cuando se llama a tu extremo de acceso. El valor del URI de acceso se puede establecer de forma explícita o puede usarse de forma predeterminada en el URI de la página actual. Se puede llamar a tu extremo de acceso en estas condiciones cuando se usa 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 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 cookie anterior cuando se complete la migración.

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

Referencia de migración de objetos para el acceso de los usuarios

Antiguas Nuevo Notas
Bibliotecas de JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Reemplaza la versión anterior por la nueva.
apis.google.com/js/api.js accounts.google.com/gsi/client Reemplaza la versión anterior por la nueva.
GoogleAuth y los métodos asociados:
GoogleAuth.adjuntClickHandler() IdConfiguration.callback para la devolución de llamada de datos de JS y HTML Reemplaza la versión anterior por la nueva.
GoogleAuth.currentUser.get() CredentialResponse En su lugar, ya no es necesario usar CredentialResponse.
GoogleAuth.currentUser.listen() Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para dar su consentimiento y acceder. El campo select_by de CredentialResponse se puede usar para determinar el resultado del consentimiento del usuario junto con el método de acceso utilizado.
GoogleAuth.disconnect() google.accounts.id.revoke. Reemplaza la versión anterior por la nueva. La revocación también puede ocurrir en https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
GoogleAuth.isSignedIn.get() Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para dar su consentimiento y acceder.
GoogleAuth.isSignedIn.listen() Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para dar su consentimiento y acceder.
GoogleAuth.signIn() Quitar. La carga del DOM HTML del elemento g_id_signin o la llamada JS a google.accounts.id.renderButton activa el acceso del usuario a una Cuenta de Google.
GoogleAuth.signOut() Quitar. El estado de acceso del usuario a tu app y la Cuenta de Google son independientes. Google no administra el estado de la sesión de tu app.
GoogleAuth.then() Quitar. GoogleAuth dejó de estar disponible.
GoogleUser y los métodos asociados:
GoogleUser.disconnect() google.accounts.id.revoke. Reemplaza la versión anterior por la nueva. La revocación también puede ocurrir en https://myaccount.google.com/permissions
UsuariodeGoogle.getAuthResponse()
UsuariodeGoogle.getBasicProfile() CredentialResponse Usa directamente credential y subcampos, en lugar de métodos BasicProfile.
GoogleUser.getGrantedScopes() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
UsuariodeGoogle.getHostedDomain() CredentialResponse En su lugar, usa directamente credential.hd.
UsuariodeGoogle.getId() CredentialResponse En su lugar, usa directamente credential.sub.
GoogleUser.grantOfflineAccess() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
GoogleUser.grant() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
GoogleUser.hasGrantedScopes() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
UsuariodeGoogle.isSignedIn() Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para dar su consentimiento y acceder.
GoogleUser.reloadAuthResponse() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
gapi.auth2 y los métodos asociados:
Objeto gapi.auth2.AuthorizeConfig Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
Objeto gapi.auth2.AuthorizeResponse Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
Objeto gapi.auth2.AuthResponse Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
gapi.auth2.authorize() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
gapi.auth2.ClientConfig() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
gapi.auth2.getAuthInstance() Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
gapi.auth2.init(). Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
Objeto gapi.auth2.OfflineAccessOptions Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
Objeto gapi.auth2.SignInOptions Quitar. Un token de ID reemplazó a los tokens de acceso y permisos de OAuth 2.0.
Objeto gapi.signin2 y métodos asociados:
gapi.signin2.render() Quitar. La carga del DOM HTML del elemento g_id_signin o la llamada JS a google.accounts.id.renderButton activa el acceso del usuario a una Cuenta de Google.