Usa el modelo de token

La biblioteca de JavaScript google.accounts.oauth2 te ayuda a solicitar el consentimiento del usuario y obtener un token de acceso para trabajar con sus datos. Se basa en el flujo concesión implícito de OAuth 2.0 y está diseñado para permitirte llamar a las API de Google directamente con REST y CORS, o usar nuestra biblioteca cliente de las API de Google para JavaScript (también conocida como gapi.client) a fin de acceder a nuestras API más complejas y sencillas.

Antes de acceder a los datos protegidos de los usuarios desde un navegador, los usuarios de tu sitio activan el selector de cuentas, el acceso y los procesos de consentimiento basados en la Web de Google y, por último, los servidores de OAuth de Google generan un token de acceso y lo devuelven a tu aplicación web.

En el modelo de autorización basada en tokens, no es necesario almacenar tokens de actualización por usuario en el servidor de backend.

Se recomienda que sigas el enfoque que se describe aquí en lugar de las técnicas que se describen en la guía anterior de OAuth 2.0 para aplicaciones web del cliente.

Crear

Busca o crea un ID de cliente mediante los pasos que se describen en la guía Obtén tu ID de cliente de la API de Google. A continuación, agrega la biblioteca cliente a las páginas de tu sitio que llamarán a las API de Google. Por último, inicializa el cliente de tokens. Por lo general, esto se hace dentro del controlador onload de la biblioteca cliente.

Inicializa un cliente de token

Llama a initTokenClient() para inicializar un nuevo cliente de token con el ID de cliente de tu aplicación web. De manera opcional, puedes incluir una lista de uno o más alcances a los que el usuario necesita acceder:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

Activa el flujo de tokens de OAuth 2.0

Usa el método requestAccessToken() para activar el flujo de UX del token y obtener un token de acceso. Google le solicita al usuario que haga lo siguiente:

  • Elegir su cuenta
  • acceda a la cuenta de Google si aún no lo ha hecho,
  • otorga permiso para que tu app web acceda a cada alcance solicitado.

Un gesto del usuario activa el flujo de tokens: <button onclick="client.requestAccessToken();">Authorize me</button>

Luego, Google muestra un TokenResponse que contiene un token de acceso y una lista de permisos a los que el usuario le otorgó acceso, o un error, a tu controlador de devolución de llamada.

Los usuarios pueden cerrar el selector de cuentas o las ventanas de acceso, en cuyo caso tu función de devolución de llamada no se invocará.

El diseño y la experiencia del usuario de tu app solo deben implementarse después de una revisión exhaustiva de las políticas de OAuth 2.0 de Google. Estas políticas abarcan el trabajo con varios alcances, cuándo y cómo manejar el consentimiento del usuario, y mucho más.

La autorización incremental es una metodología de diseño de aplicaciones y políticas que se usa para solicitar acceso a los recursos mediante el uso de permisos, solo cuando es necesario en lugar de hacerlo por adelantado y todo a la vez. Los usuarios pueden aprobar o rechazar el uso compartido de los recursos individuales solicitados por la app, lo que se conoce como permisos detallados.

Durante este proceso, Google solicita el consentimiento del usuario y enumera de forma individual cada alcance solicitado, los usuarios seleccionan los recursos que se compartirán con tu app y, por último, Google invoca tu función de devolución de llamada para mostrar un token de acceso y los permisos aprobados por el usuario. Luego, tu app maneja de manera segura los diferentes resultados posibles con permisos detallados.

Autorización incremental

Para las aplicaciones web, las siguientes dos situaciones de alto nivel demuestran la autorización incremental mediante el siguiente comando:

  • Una app Ajax de una sola página, que a menudo usa XMLHttpRequest con acceso dinámico a los recursos
  • Si hay varias páginas web, los recursos se separan y se administran por página.

Estas dos situaciones se presentan para ilustrar las consideraciones y metodologías de diseño, pero no pretenden ser recomendaciones completas sobre cómo generar consentimiento en tu app. Las apps reales pueden usar una variación o una combinación de estas técnicas.

Ajax

Agrega compatibilidad con la autorización incremental a tu app mediante varias llamadas a requestAccessToken() y el uso del parámetro scope del objeto OverridableTokenClientConfig para solicitar alcances individuales en el momento en que sean necesarios y solo cuando sea necesario. En este ejemplo, los recursos se solicitarán y serán visibles solo después de que un gesto del usuario expanda una sección de contenido contraído.

App de Ajax
Inicializa el cliente de token durante la carga de la página:
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
      
Solicita consentimiento y obtén tokens de acceso mediante los gestos del usuario; haz clic en "+" para abrirlo:

Documentos para leer

Mostrar documentos recientes

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );
        

Próximos eventos

Mostrar información del calendario

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );
        

Mostrar fotos

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );
        

Cada llamada a requestAccessToken activa un momento de consentimiento del usuario, tu app solo tendrá acceso a los recursos que requiere la sección que un usuario elija expandir, lo que limitará el uso compartido de recursos a través de la elección del usuario.

Varias páginas web

Cuando se diseña para una autorización incremental, se usan varias páginas a fin de solicitar solo los permisos necesarios para cargar una página, lo que reduce la complejidad y la necesidad de realizar varias llamadas a fin de obtener el consentimiento del usuario y recuperar un token de acceso.

Aplicación de varias páginas
Página web Código
Página 1. Documentos para leer
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          
Página 2. Próximos eventos
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
          
Página 3. Carrusel de fotos
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();
          

Cada página solicita el alcance necesario y obtiene un token de acceso mediante una llamada a initTokenClient() y requestAccessToken() en el momento de la carga. En esta situación, las páginas web individuales se usan para separar claramente la funcionalidad del usuario y los recursos por alcance. En una situación real, las páginas individuales pueden solicitar varios alcances relacionados.

Permisos detallados

Los permisos detallados se manejan de la misma manera en todas las situaciones; después de que requestAccessToken() invoque tu función de devolución de llamada y se muestre un token de acceso, verifica que el usuario haya aprobado los permisos solicitados con hasGrantedAllScopes() o hasGrantedAnyScope(). Por ejemplo:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

Todas las subvenciones aceptadas con anterioridad de las sesiones o solicitudes anteriores también se incluirán en la respuesta. Se conserva un registro de consentimiento por usuario y de ID de cliente, y persiste en varias llamadas a initTokenClient() o requestAccessToken(). De forma predeterminada, el consentimiento del usuario solo es necesario la primera vez que un usuario visita tu sitio web y solicita un nuevo alcance, pero se puede solicitar en cada carga de página con prompt=consent en objetos de configuración del cliente Token.

Trabaja con tokens

En el modelo de tokens, el SO o el navegador no almacenan un token de acceso, sino que se obtiene un token nuevo cuando se carga la página o, posteriormente, mediante una llamada a requestAccessToken() mediante un gesto del usuario, como cuando se presiona un botón.

Usa REST y CORS con las API de Google

Se puede usar un token de acceso para realizar solicitudes autenticadas a las API de Google con REST y CORS. Esto permite a los usuarios acceder, otorgar su consentimiento y que Google emita un token de acceso para que tu sitio trabaje con los datos del usuario.

En este ejemplo, visualiza los próximos eventos de calendario de los usuarios que accedieron con el token de acceso que muestra tokenRequest():

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

Consulta Cómo usar CORS para acceder a las API de Google a fin de obtener más información.

En la siguiente sección, se explica cómo realizar una integración sencilla con API más complejas.

Cómo trabajar con la biblioteca JavaScript de las API de Google

El cliente del token funciona con la biblioteca cliente de la API de Google para JavaScript. Consulta el fragmento de código que aparece a continuación.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

Vencimiento del token

Por diseño, los tokens de acceso tienen una vida útil corta. Si el token de acceso vence antes del final de la sesión del usuario, obtén un token nuevo llamando a requestAccessToken() desde un evento controlado por el usuario, como cuando se presiona un botón.

Llama al método google.accounts.oauth2.revoke a fin de quitar el consentimiento del usuario y el acceso a los recursos para todos los alcances otorgados a tu app. Se requiere un token de acceso válido a fin de revocar este permiso:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7');