Advertencia: Estos datos se proporcionan bajo la Política de datos de usuario de Google . Por favor revise y cumpla con la política. De lo contrario, podría resultar en la suspensión del proyecto o de la cuenta.

Migrar desde Acceso con Google

Esta guía te ayuda a comprender los cambios necesarios y los pasos necesarios para migrar correctamente las bibliotecas de JavaScript de la biblioteca de la plataforma de Acceso con Google más antigua 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 antigua para autorización, consulta Cómo migrar a los servicios de identidad de Google 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 o acceso de usuario. La autorización es el proceso de otorgar o rechazar el acceso a datos o recursos. Por ejemplo, la app solicita el consentimiento del usuario para acceder a 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 procesos de autenticación y de autorización.

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

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

Si tu caso de uso incluye autorización, lee 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 Google Identity Services ofrece muchas mejoras de usabilidad. Se incluyen los siguientes aspectos destacados:

  • Flujos de acceso automático, One Tap y nuevo con menos pasos individuales,
  • un botón de acceso actualizado con personalización del usuario,
  • una marca coherente y un comportamiento uniforme de acceso en la Web mejoran la comprensión y la confianza,
  • Accede a contenido rápidamente y permite que los usuarios se registren de manera directa y fácil desde cualquier parte del sitio sin tener que visitar una página de acceso o de la cuenta.

Para los desarrolladores, nuestro objetivo es reducir la complejidad, mejorar la seguridad y hacer que la integración sea lo más rápida y fácil posible. Estas son algunas de esas mejoras:

  • La opción de agregar el acceso de los 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 datos del usuario, la complejidad de una integración de OAuth2 ya no es necesario para permitir que los usuarios accedan a su sitio.
  • los modos emergente y de redireccionamiento siguen siendo compatibles, pero la infraestructura de OAuth2 de Google ahora redirecciona al extremo de acceso del servidor de backend
  • consolidar la funcionalidad de las bibliotecas más antiguas de Google Identity y JavaScript 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 mediante funciones de estilo get para simplificar el proceso.

Ejemplo de una migración de acceso

Si migras desde el botón de Acceso con Google existente y solo te interesa que los usuarios accedan a tu sitio, el cambio más sencillo es simplemente actualizar al nuevo botón personalizado. Esto se puede lograr cambiando las bibliotecas de JavaScript y actualizando la base de código para usar un objeto de acceso nuevo.

Bibliotecas y configuración

La biblioteca de la plataforma de Acceso con Google más antigua: 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 nueva biblioteca JavaScript de los servicios de Google Identity: accounts.google.com/gsi/client.

Los tres módulos más antiguos de JavaScript: 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 puede incluir la biblioteca antigua en tu sitio, por lo general, 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
  • el uso directo de gapi.client carga apis.google.com/js/api.js.

En la mayoría de los casos, puedes seguir usando tus credenciales de ID de cliente de aplicación web existentes. 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:

  • Las apps de prueba y producción usan proyectos diferentes y tienen sus propios ID de cliente.
  • el tipo de ID de cliente de OAuth 2.0 es una "aplicación web"
  • HTTPS se usa para los orígenes autorizados de JavaScript y los URI de redireccionamiento.

Identifica el código afectado y realiza pruebas

Una cookie de depuración puede ayudar a localizar 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 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 manera opcional, agrega dos puntos seguidos de un valor de clave para acceder al almacenamiento de sesión. Después del acceso y la recepción de las credenciales, se revisan o envían 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 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 de cookie G_AUTH2_MIGRATION posibles:

  • enforced No cargues el módulo gapi.auth2.
  • informational Registra el uso de la función obsoleta en la consola de JS. También accede al almacenamiento de la sesión cuando se establezca un nombre de clave opcional: informational:key-name.

Para minimizar el impacto en el usuario, se recomienda que primero configures esta cookie localmente 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 de Acceso con Google existente. Selecciona entre los modos Popup o Redirect 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 a tu extremo de acceso al servidor de backend.

Método antiguo

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 y 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 crear un botón personalizado, eliminan las llamadas a gapi.signin2.render() y la necesidad de que alojes y mantengas las imágenes y los elementos 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 simple de autenticación, selecciona desde 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.

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 tu extremo de acceso según lo especificado por el atributo data-login_url. Anteriormente, eras 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 atributos visuales para personalizar el tamaño, la forma y el color del botón de Acceder con Google. Muestra la ventana emergente One Tap junto con el botón personalizado para mejorar la tasa de acceso.

Botón de Acceder con Google Ventana emergente con un toque

El estado de acceso del usuario no actualiza el texto del botón de "Acceder" a "Acceso". Después de brindar el consentimiento o al regresar, el botón personalizado incluye el nombre, el correo electrónico y la foto de perfil del usuario.

En este ejemplo simple de autenticación simple, la biblioteca accounts.google.com/gsi/client nueva, 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 botón personalizado nuevo, el código de ejemplo también muestra la nueva ventana emergente One Tap. Siempre que muestres el botón personalizado, te recomendamos que también muestres la ventana emergente de One Tap para minimizar la fricción del usuario durante el registro y en el acceso.

Aunque no se recomienda debido a una 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 hacerlo, configura el atributo data-auto_prompt como false.

API de HTML y JavaScript

El ejemplo anterior muestra cómo usar la nueva API de HTML para agregar acceso a tu sitio web. Como alternativa, puedes usar la API de JavaScript equivalente funcionalmente, o bien mezclar y unir las API de HTML y JavaScript en tu sitio.

Para ver opciones de personalización del botón de forma interactiva, como el tipo de devolución de llamada y atributos, como color, tamaño, forma, texto y tema, consulta el 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 forma nueva y sin fricciones para que los usuarios se registren o accedan a tu sitio. ya que 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 y acceder desde páginas que no son tu 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 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. Muestra a los usuarios opciones para registrarse o acceder mostrando el botón junto con otros botones federados de proveedores de identidad y campos de entrada de nombre de usuario y contraseña.

Respuesta del token

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

Se mostrará una credencial de token de ID de JWT firmada por Google de la siguiente manera:

  • 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 extremo de acceso cuando el botón ux_mode de Acceder con Google se configura en redirect.

En ambos casos, actualiza 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(), getEmail() y
  • 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, 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, se puede usar el campo select_by de CredentialResponse para determinar el resultado del consentimiento del usuario y el flujo de acceso específico que se usa.

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 dar su consentimiento, el perfil del usuario se comparte con tu app en una carga útil de 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 la app de sus Cuentas de Google en https://myaccount.google.com/permissions. Como alternativa, pueden desconectarse directamente de la app si activan una llamada a la API que implementas. El método disconnect más antiguo se reemplazó por el método revoke más reciente.

Cuando un usuario borra su cuenta de la plataforma, la práctica recomendada es usar revoke para desconectar la app de su Cuenta de Google.

Anteriormente, se podía usar auth2.signOut() para ayudar a administrar el cierre de los usuarios desde tu app. Debes quitar cualquier uso de auth2.signOut(), y tu app debería administrar directamente el estado de la sesión y el estado de acceso del usuario.

Objetos de escucha y estado de la sesión

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

El estado de acceso de una Cuenta de Google y el estado de sesión de tu app y el estado de acceso son conceptos distintos e 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 incluye el Acceso automático con Google, One Tap o el acceso automático en tu sitio, los usuarios deben acceder primero a su Cuenta de Google para lo siguiente:

  • brindar su consentimiento para compartir su perfil de usuario al registrarse o acceder por primera vez a tu sitio,
  • y más tarde para acceder a su cuenta en las visitas de devolución.

Es posible que los usuarios permanezcan en sus cuentas, salgan de ellas o cambien a una Cuenta de Google diferente mientras mantienen una sesión activa y activa en su 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 los cambios en el estado de acceso de una Cuenta de Google del usuario. Los objetos de escucha ya no son compatibles.

Quita todas 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 descripción. Consulta Cómo Google usa 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 configurada en la antigua plataforma de la plataforma de Acceso con Google.

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

  • g_state almacena el estado de salida de los usuarios 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 evitar ataques de CSRF y se establece cuando se llama a tu extremo de acceso. El valor de tu URI de acceso se puede establecer de forma explícita o puede ser el predeterminado de la 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 el acceso con One Tap o automático

Si tienes un servicio que administra cookies, asegúrate de agregar las dos cookies nuevas y quitar la anterior cuando finalice.

Si administras varios dominios o subdominios, consulta Cómo mostrar One Tap en todos los subdominios a fin de obtener más instrucciones para trabajar con la cookie g_state.

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

Antigua New Notas
Bibliotecas de JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Reemplaza lo viejo por lo nuevo.
apis.google.com/js/api.js accounts.google.com/gsi/client Reemplaza lo viejo por lo nuevo.
GoogleAuth y los métodos asociados:
GoogleAuth.attachClickHandler() IdConfiguration.callback para datos de devolución de llamada de JS y HTML Reemplaza lo viejo por lo nuevo.
GoogleAuth.currentUser.get(): CredentialResponse En su lugar, usa CredentialResponse, ya no es necesario.
GoogleAuth.currentUser.listen(). Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para obtener el consentimiento y los momentos de acceso. 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 lo viejo por lo nuevo. La revocación también puede ocurrir en https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
GoogleAuth.isSignedIn.get() Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para obtener el consentimiento y los momentos de acceso.
GoogleAuth.isSignedIn.listen(). Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para obtener el consentimiento y los momentos de acceso.
GoogleAuth.signIn(). Quitar. La carga de DOM HTML del elemento g_id_signin o de 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 para tu app y una Cuenta de Google es independiente. 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 lo viejo por lo nuevo. La revocación también puede ocurrir en https://myaccount.google.com/permissions
GoogleUser.getAuthResponse().
GoogleUser.getBasicProfile(). CredentialResponse Usa credential y los subcampos de forma directa en lugar de usar métodos BasicProfile.
GoogleUser.getGrantedScopes() Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
GoogleUser.getHostedDomain() CredentialResponse En su lugar, usa credential.hd directamente.
GoogleUser.getId() CredentialResponse En su lugar, usa credential.sub directamente.
GoogleUser.grantOfflineAccess() Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
GoogleUser.grant(). Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
GoogleUser.hasGrantedScopes() Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
UsuarioDeGoogle.isSignedIn() Quitar. El estado de acceso actual de un usuario en Google no está disponible. Los usuarios deben acceder a Google para obtener el consentimiento y los momentos de acceso.
GoogleUser.reloadAuthResponse(). Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
gapi.auth2 y los métodos asociados:
Objeto gapi.auth2.AuthorizeConfig Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
Objeto gapi.auth2.AuthorizeResponse Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
Objeto gapi.auth2.AuthResponse Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
gapi.auth2.authorized() Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
gapi.auth2.ClientConfig(). Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
gapi.auth2.getAuthInstance() Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
gapi.auth2.init(). Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
Objeto gapi.auth2.OfflineAccessOptions Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
Objeto gapi.auth2.SignInOptions Quitar. Un token de ID reemplazó los tokens de acceso y permisos de OAuth2.
gapi.signin2 y los métodos asociados:
gapi.signin2.render() Quitar. La carga de DOM HTML del elemento g_id_signin o de la llamada JS a google.accounts.id.renderButton activa el acceso del usuario a una Cuenta de Google.