Migrar desde Acceso con Google

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

Si el cliente usa la biblioteca cliente de la API de Google para JavaScript, o bien otras bibliotecas anteriores para la autorización, consulta Migra a los servicios de Google Identity a fin de 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 de usuario o acceso. La autorización es el proceso de otorgar o rechazar el acceso a los datos o recursos. Por ejemplo, la 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 Servicios de identidad de Google se creó para admitir los procesos de autenticación y autorización.

Sin embargo, la biblioteca más reciente separa los dos procesos con el fin de reducir la complejidad para que los desarrolladores integren las Cuentas de Google en tu app.

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

Si tu caso práctico incluye autorización, consulta Cómo funciona la autorización de usuario y Migra a los servicios de identidad de Google para asegurarte de que tu aplicación use las API nuevas y mejoradas.

Qué cambió

Para los usuarios, la nueva biblioteca de Servicios de identidad de Google ofrece muchas mejoras de usabilidad. Se incluyen los siguientes aspectos destacados:

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

El enfoque para los desarrolladores fue reducir la complejidad, mejorar la seguridad y hacer que la integración sea lo más rápida y fácil posible. Algunas de estas mejoras son las siguientes:

• Para agregar el acceso de usuarios al contenido estático de tu sitio usando solo 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 OAuth2 ya no es necesaria simplemente para que los usuarios accedan a tu sitio,
• los modos de ventana emergente y redireccionamiento siguen siendo compatibles, pero la infraestructura de OAuth2 de Google ahora redirecciona al extremo de acceso de tu servidor backend
• la consolidación de la funcionalidad de las bibliotecas más antiguas de Google Identity y JavaScript de la API de Google en una sola biblioteca nueva,
• En el caso de las respuestas de acceso, ahora puedes decidir si deseas usar o no una promesa y, por cuestiones de simplicidad, se quitó el direccionamiento indirecto mediante funciones de estilo get.

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 logra mediante el cambio de las bibliotecas de JavaScript y la actualización de tu base de código para que use un objeto de acceso nuevo.

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 API 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 los servicios de identidad de Google: accounts.google.com/gsi/client.

Los tres módulos de JavaScript más antiguos: api, client y platform que se usan para acceder 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, debes hacer 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
• 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 tu aplicación web. Como parte de tu migración, te recomendamos que revises nuestras Políticas de OAuth 2.0 y uses la Consola de API de Google para confirmar y, de ser necesario, actualizar la siguiente configuración de cliente:

• sus aplicaciones de prueba y producción usan proyectos independientes y tienen sus propios ID de cliente.
• El tipo de ID de cliente de OAuth 2.0 es "Aplicación web"
• HTTPS se usa para los orígenes autorizados de JavaScript y los URI de redireccionamiento.

Identifica el código y las pruebas afectados

Una cookie de depuración puede ayudar a ubicar el código afectado y a 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 el uso existente de la funcionalidad que pronto dejará de estar disponible 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 acceder también al 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 cookie G_AUTH2_MIGRATION:

• enforced No cargues el módulo gapi.auth2.
• informational. Registro de uso de la funcionalidad obsoleta a 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 la prueba, antes de usarla en entornos de producción.

HTML y JavaScript

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

El método antiguo

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

La nueva forma

Para usar la biblioteca nueva en una situación de acceso de autenticación única, selecciona en el modo emergente o de redireccionamiento y usa la muestra de código para reemplazar la 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 anterior y el objeto g-signin2.

Además de procesar el nuevo botón personalizado, el código de ejemplo muestra la nueva ventana emergente del One Tap. Siempre que muestres el botón personalizado, te recomendamos que muestres la ventana emergente One Tap para minimizar la fricción del usuario durante el registro y el acceso.

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

API de HTML y JavaScript

En el ejemplo anterior, se muestra cómo usar la nueva API de HTML para agregar el acceso al sitio web. Como alternativa, puedes usar la API de JavaScript funcionalmente equivalente, o bien mezclar y hacer coincidir las API de HTML y JavaScript en tu sitio.

Para ver de forma interactiva las opciones de personalización del botón, como el tipo de devolución de llamada y sus atributos, como color, tamaño, forma, texto y tema, consulta nuestro Generador de códigos. 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 de que los usuarios se registren o accedan a tu sitio sin inconvenientes. Te permite habilitar el acceso del usuario 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 la fricción del registro y el acceso, ya que brinda a los usuarios la flexibilidad de registrarse desde otras páginas que no sean tu página de acceso.

Para habilitar el acceso desde cualquier página, te recomendamos que incluyas g_id_onload en un encabezado, un pie de página o algún otro objeto compartido en todo tu 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 de registro o acceso. Para ello, muestra el botón junto con otros botones del proveedor de identidad federada y los campos de entrada de nombre de usuario y contraseña.

Respuesta del token

El acceso de usuario ya no requiere que comprendas ni trabajes con los códigos de autorización, los tokens de acceso ni los tokens de actualización de OAuth2. 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 usar métodos de acceso de estilo "get" a fin de trabajar con los datos del perfil del usuario.

Se muestra una credencial de token de ID de JWT segura y firmada por Google:

• al controlador de devolución de llamada de JavaScript basado en el navegador del usuario en el modo emergente, o
• 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, actualiza tus controladores de devolución de llamada existentes mediante la eliminación de lo siguiente:

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

En su lugar, usa referencias directas a los subcampos credential en el objeto nuevo JWT CredentialResponse 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 los usuarios interactúan con tu sitio, el campo select_by de CredentialResponse se puede usar a fin de determinar el resultado del consentimiento del usuario y el flujo de acceso específico.

Consentimiento del usuario y revocación del permiso

Cuando un usuario accede por primera vez a tu sitio web, Google le solicita el consentimiento para compartir el perfil de su cuenta con tu app. Solo después de proporcionar el consentimiento, se muestra el perfil del usuario compartido con tu app en una carga útil de la credencial del token de ID. Revocar el acceso a este perfil es equivalente 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. Para ello, deben visitar https://myaccount.google.com/permissions. Como alternativa, pueden desconectarse directamente de tu app activando una llamada a la API que implementes; el método disconnect más antiguo se reemplazó por el método revoke más nuevo.

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

Anteriormente, auth2.signOut() podía usarse para ayudar a administrar al usuario cerrar sesión desde tu app. Debe quitarse cualquier uso de auth2.signOut() y tu app debería administrar directamente el estado de acceso y el estado de sesión de cada usuario.

Objetos de escucha y estado de la sesión

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

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

El estado de acceso del usuario a su Cuenta de Google y a tu app es independiente 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 accede con Google, One Tap o el acceso automático en el sitio, los usuarios deben acceder primero a su cuenta de Google para lo siguiente:

• dar su consentimiento para compartir su perfil de usuario cuando se registre o acceda
• y, luego, acceder para que vuelvan a visitar su sitio.

Es posible que los usuarios permanezcan, salgan de sus cuentas o cambien a una Cuenta de Google diferente mientras mantengan una sesión activa y 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 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.

Antes, los objetos de escucha se usaban para compartir los cambios en el estado de acceso de la Cuenta de Google de un usuario. Los objetos de escucha ya no son compatibles.

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

Cookies

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

La cookie G_ENABLED_IDPS establecida por la antigua Biblioteca de la plataforma de Acceso con Google ya no se usa.

De forma opcional, la nueva biblioteca de Servicios de identidad de Google puede establecer estas cookies multidominio en función de 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 One Tap o el acceso automático.

• g_csrf_token es una cookie de envío doble que se usa para prevenir los ataques de CSRF y se establece cuando se llama al extremo de acceso. El valor de tu URI de acceso se puede establecer de manera explícita o se puede establecer como predeterminado para el URI de la página actual. Es posible que se llame a tu extremo de acceso en los siguientes casos:

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

  • API de JavaScript con ux_mode=redirect y en la que google.accounts.id.prompt() no se usa para mostrar un toque o acceso automático

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

Si administras varios dominios o subdominios, consulta Mostrar un toque en los 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