Cómo migrar desde el Acceso con Google

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

Si tu cliente usa la biblioteca cliente de las APIs de Google para JavaScript o cualquier otro bibliotecas anteriores para autorización; consulta Migrar a Google Identity Servicios 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 la denomina el registro o el acceso de un usuario. La autorización es el proceso de otorgar o el rechazo del acceso a los datos o recursos. Por ejemplo, tu app solicita tu 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 versión de Google Identity La biblioteca de servicios se diseñó para admitir la autenticación y la autorización. procesos.

Sin embargo, la biblioteca más nueva separa los dos procesos para reducir la complejidad para que los desarrolladores integren Cuentas de Google con 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 esté con las APIs nuevas y mejoradas.

Qué cambió

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

• Nuevos flujos de acceso automático y con One Tap de bajo fricción con menos usuarios individuales pasos,
• un botón de acceso actualizado con personalización del usuario
• el desarrollo de la marca y el comportamiento de acceso uniformes en la Web mejoran comprensión y confianza,
• llegar rápidamente al contenido; Los usuarios pueden registrarse y acceder directamente desde cualquier lugar. en su sitio sin tener que visitar la página de acceso o de una cuenta.

Para los desarrolladores, nos enfocamos en reducir la complejidad, mejorar la seguridad y que la integración sea lo más rápida posible. Entre estas mejoras, se incluyen las siguientes:

• La opción de agregar el acceso de usuarios al contenido estático de tu sitio utilizando solo HTML,
• la separación de la autenticación de acceso de la autorización y el uso compartido de 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
• ambos modos de redireccionamiento y de ventana emergente siguen siendo compatibles, pero la interfaz de OAuth de Google La infraestructura 2.0 ahora redirecciona al extremo de acceso del servidor de backend,
• la consolidación de las funciones de los productos y las bibliotecas de JavaScript de la API de Google en una única biblioteca nueva,
• para las respuestas de acceso, ahora puedes decidir si usar o no una Promise y la indirección a través de funciones de estilo get. se quitaron para mayor simplicidad.

Un ejemplo de migración de acceso

Si estás migrando desde el botón existente de Acceso con Google y solo estás interesadas en que los usuarios accedan a tu sitio, el cambio más directo es para actualizar al nuevo botón personalizado. Esto se puede lograr al intercambiar Bibliotecas de JavaScript y actualización de tu base de código para usar 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 biblioteca cliente de las APIs de Google para JavaScript: gapi.client, no son se requieren más para la autenticación y autorización de usuarios. Han sido por una única biblioteca JavaScript de Google Identity Services nueva: accounts.google.com/gsi/client

Los tres primeros módulos de JavaScript (api, client y platform) que se usan para accesos se cargan desde apis.google.com. Para ayudarte a identificar ubicaciones en la que la biblioteca anterior podría estar incluida en tu sitio, por lo general:

• el botón de acceso predeterminado carga apis.google.com/js/platform.js,
• un gráfico de botones personalizado carga 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 el ID de cliente de tu aplicación web existente. credenciales. Como parte de la migración, te recomendamos revisar nuestro Políticas de OAuth 2.0 y usa la Consola de APIs de Google para confirmar y, de ser necesario, actualiza la siguiente configuración del cliente:

• Tus apps de prueba y producción usan proyectos independientes y tienen los suyos 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 autorizados de JavaScript y los URI de redireccionamiento.

Identifica el código afectado y realiza una prueba

Una cookie de depuración puede ayudar a localizar el código afectado y a realizar pruebas posteriores a la baja el comportamiento de los usuarios.

En apps grandes o complejas, puede ser difícil encontrar todo el código afectado por el dejará de estar disponible el módulo gapi.auth2. Para registrar el uso existente funciones obsoletas de la consola, establece el valor de G_AUTH2_MIGRATION cookie a informational. También puedes agregar dos puntos seguidos de un valor clave en también registran el almacenamiento de la sesión. Después de acceder y recibir revisar las credenciales o enviar los registros recopilados a un backend para su posterior análisis. Para Por ejemplo, informational:showauth2use guarda el origen y la URL en un almacenamiento de sesión llamada showauth2use.

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

Posibles valores de cookie G_AUTH2_MIGRATION:

• enforced No cargar el módulo gapi.auth2.
• informational Registra el uso de capacidades obsoletas en la consola de JS. Registrar también al almacenamiento de sesión cuando se establece un nombre de clave opcional: informational:key-name

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

HTML y JavaScript

En esta situación de acceso de solo autenticación, el código de ejemplo y las renderizaciones de la el botón de Acceso con Google existente. Selecciona una ventana emergente o una opción de redireccionamiento. para ver las diferencias en cómo se maneja la respuesta de autenticación, ya sea una devolución de llamada de JavaScript o mediante un redireccionamiento seguro a la información de acceso al servidor de backend extremo.

La forma 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 un caso de acceso de solo autenticación, selecciona del modo Ventana emergente o Redireccionamiento y usa la muestra de código para reemplazar el 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, el nuevo accounts.google.com/gsi/client biblioteca, la clase g_id_signin y el objeto g_id_onload reemplazan al anterior biblioteca apis.google.com/js/platform.js y el objeto g-signin2.

Además de renderizar el nuevo botón personalizado, el código de ejemplo también 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 inconvenientes durante el registro y el acceso.

Aunque no se recomienda debido a la mayor fricción en el acceso, la nueva el botón de personalización puede mostrarse solo, sin mostrar al mismo tiempo el Cuadro de diálogo de One Tap. Para ello, establece el atributo data-auto_prompt en 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 el equivalente funcionalmente API de JavaScript o mezclar y combinar las APIs de HTML y JavaScript en tu .

Para ver de forma interactiva las opciones de personalización de botones, como el tipo de devolución de llamada atributos como color, tamaño, forma, texto y tema, consulta nuestro Código generador. 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 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. Dicho de otro modo, Esto reduce las dificultades de registro y acceso, ya que les brinda a los usuarios la flexibilidad de pueden registrarse y acceder desde otras 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, un pie de página o algún otro objeto compartido incluido en todo el sitio.

También te recomendamos agregar g_id_signin, que muestra el acceso personalizado. solo en las páginas de acceso o de administración de cuentas de usuario. Brinda opciones a los usuarios para registrarse o acceder mostrando el botón junto a otras aplicaciones botones del proveedor de identidad y campos de entrada de nombre de usuario y contraseña.

Respuesta de token

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

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

• al controlador de devolución de llamada de JavaScript basado en el navegador del usuario en el modo de ventana emergente.
• 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 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 getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), métodos getEmail()
• uso del objeto AuthResponse.

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

Además, y solo en el caso del modo de redireccionamiento, asegúrate de evitar las solicitudes entre sitios Falsificación (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, el El campo select_by de CredentialResponse se puede usar para determinar la identidad el resultado del consentimiento 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 dar su consentimiento se El perfil del usuario que se comparte con tu app en una carga útil de credenciales del token de ID. Revocar el acceso a este perfil equivale a revocar un token de acceso en la biblioteca de acceso anticipado.

Los usuarios pueden revocar los permisos y desconectar tu app de su Cuenta de Google Visita https://myaccount.google.com/permissions. Como alternativa, es posible que se desconecten directamente de tu app mediante la activación de una API. la llamada que implementas; se aplicó el método disconnect anterior se reemplazó por el método revoke más reciente.

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

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

Estado de la sesión y objetos de escucha

La nueva biblioteca no mantiene el estado de acceso ni de sesión en tu Web .

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

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

Cuando Acceder con Google, One Tap o el acceso automático están incluidos en tu los usuarios del sitio primero deben acceder a su Cuenta de Google para lo siguiente:

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

Los usuarios pueden permanecer en la cuenta, salir o cambiar de Cuenta de Google. y, al mismo tiempo, mantener una sesión activa y iniciada en tu sitio web.

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

Quita todas las referencias a auth2.attachClickHandler() y su nombre registrado controladores de devolución de llamada.

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

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

Cookies

Acceder con Google hace un uso limitado de las cookies, una descripción de estas sigue. Consulte Cómo Google utiliza las cookies. para obtener más información sobre los demás tipos de cookies que utiliza Google.

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

La nueva biblioteca de Google Identity Services puede configurar, cookies basadas en sus opciones de configuración:

• g_state almacena el estado de salida del usuario y se establece cuando se usa One Tap o el acceso automático,

• g_csrf_token es una cookie de envío doble que se utiliza para prevenir los ataques CSRF. y se configura cuando se llama al extremo de acceso. El valor de tu URI de acceso se puede configurar de forma explícita o se puede establecer de forma predeterminada el URI de la página actual. Tu se puede llamar al extremo de acceso en las siguientes condiciones cuando se usa:

  • API de HTML con data-ux_mode=redirect o cuando data-login_uri es establecer, o

  • API de JavaScript con ux_mode=redirect y dónde google.accounts.id.prompt() no se usa para mostrar One Tap ni 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 administra varios dominios o subdominios, consulte 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 de usuarios