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 de otorgamiento implícito de OAuth 2.0 y está diseñado para permitirte llamar a las APIs de Google directamente con REST y CORS, o usar nuestra biblioteca cliente de las APIs de Google para JavaScript (también conocida como gapi.client) para obtener acceso simple y flexible a nuestras APIs más complejas.
Antes de acceder a los datos del usuario protegidos 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 emiten y devuelven un token de acceso a tu app web.
En el modelo de autorización basado en tokens, no es necesario almacenar tokens de actualización por usuario en tu servidor de backend.
Te recomendamos que sigas el enfoque que se describe aquí en lugar de las técnicas que se abordan en la guía más antigua OAuth 2.0 para aplicaciones web del lado del cliente.
Configuración
Para buscar o crear un ID de cliente, sigue 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 APIs de Google. Por último, inicializa el cliente de tokens. Por lo general, esto se hace dentro del controlador onload de la biblioteca cliente.
Cómo inicializar un cliente de tokens
Llama a initTokenClient() para inicializar un nuevo cliente de tokens con el ID de cliente de tu app 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:
- Elige su cuenta.
- acceder a la Cuenta de Google si aún no lo hiciste
- Otorgar consentimiento para que tu app web acceda a cada permiso 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 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 no se invocará tu función de devolución de llamada.
Cómo controlar el consentimiento
El diseño y la experiencia del usuario de tu app deben implementarse solo después de una revisión exhaustiva de las Políticas de OAuth 2.0 de Google. Estas políticas abarcan trabajar con varios permisos, cuándo y cómo controlar el consentimiento del usuario, y mucho más.
La autorización incremental es una metodología de diseño de políticas y apps que se usa para solicitar acceso a recursos, con alcances, solo cuando sea necesario, en lugar de hacerlo de forma anticipada y todo a la vez. Los usuarios pueden aprobar o rechazar el uso compartido de los recursos individuales que solicita tu app. Esto se conoce como permisos detallados.
Durante este proceso, Google solicita el consentimiento del usuario y enumera de forma individual cada permiso 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 controla de forma segura los diferentes resultados posibles con permisos detallados.
Sin embargo, hay algunas excepciones. Las apps de Google Workspace Enterprise con delegación de autoridad en todo el dominio o las apps marcadas como Confiable omiten la pantalla de consentimiento de permisos detallados. En el caso de estas apps, los usuarios no verán la pantalla de consentimiento de permisos detallados. En su lugar, tu app recibirá todos los permisos solicitados o ninguno.
Para obtener información más detallada, consulta Cómo controlar permisos detallados.
Autorización incremental
En el caso de las apps web, los siguientes dos casos de alto nivel demuestran la autorización incremental con lo siguiente:
- Una app de Ajax de una sola página, que suele usar
XMLHttpRequestcon acceso dinámico a los recursos. - Varias páginas web y recursos se separan y administran por página.
Estos dos casos de uso se presentan para ilustrar las consideraciones y las metodologías de diseño, pero no tienen la intención de ser recomendaciones integrales sobre cómo incorporar el consentimiento en tu app. Las apps del mundo real pueden usar una variación o combinación de estas técnicas.
Ajax
Para agregar compatibilidad con la autorización incremental a tu app, realiza varias llamadas a requestAccessToken() y usa el parámetro scope del objeto OverridableTokenClientConfig para solicitar permisos individuales en el momento en que se necesiten 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ída.
| App de Ajax |
|---|
Inicializa el cliente de tokens cuando se carga la página:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Documentos para leerCómo mostrar documentos recientes
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Próximos eventosMostrar información del calendario
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Carrusel de fotosCómo 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 requiera la sección que el usuario elija expandir, lo que limita el uso compartido de recursos a través de la elección del usuario.
Varias páginas web
Cuando se diseña para la autorización incremental, se usan varias páginas para solicitar solo los permisos necesarios para cargar una página, lo que reduce la complejidad y la necesidad de realizar varias llamadas para obtener el consentimiento del usuario y recuperar un token de acceso.
| App de varias páginas | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Cada página solicita el alcance necesario y obtiene un token de acceso llamando a initTokenClient() y requestAccessToken() en el momento de la carga. En esta situación, se usan páginas web individuales para separar claramente la funcionalidad del usuario y los recursos por alcance. En una situación real, las páginas individuales pueden solicitar varios permisos relacionados.
Permisos detallados
Los permisos detallados se controlan 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
...
}
}
},
});
Cualquier subvención aceptada anteriormente de sesiones o solicitudes anteriores también se incluirá en la respuesta. Se mantiene un registro del consentimiento del usuario por usuario y 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 los objetos de configuración del cliente de tokens.
Cómo trabajar con tokens
En el modelo de token, el SO o el navegador no almacenan un token de acceso. En su lugar, primero se obtiene un token nuevo en el momento de la carga de la página o, posteriormente, activando una llamada a requestAccessToken() a través de un gesto del usuario, como presionar un botón.
Usa REST y CORS con las APIs de Google
Se puede usar un token de acceso para realizar solicitudes autenticadas a las APIs de Google con REST y CORS. Esto permite que los usuarios accedan, otorguen su consentimiento, que Google emita un token de acceso y que tu sitio funcione con los datos del usuario.
En este ejemplo, se muestran 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 APIs de Google para obtener más información.
En la siguiente sección, se explica cómo realizar integraciones fácilmente con APIs más complejas.
Cómo trabajar con la biblioteca de JavaScript de las APIs de Google
El cliente de tokens funciona con la biblioteca cliente de la API de Google para JavaScript. Consulta el siguiente fragmento de código.
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 de que finalice la sesión del usuario, obtén uno nuevo llamando a requestAccessToken() desde un evento controlado por el usuario, como presionar un botón.
Cómo usar un token de acceso para revocar el consentimiento
Llama al método google.accounts.oauth2.revoke para quitar el consentimiento del usuario y el acceso a los recursos de todos los permisos otorgados a tu app. Se requiere un token de acceso válido para revocar este permiso:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});