La libreria JavaScript google.accounts.oauth2 ti aiuta a richiedere il consenso dell'utente e a ottenere un token di accesso per lavorare con i dati utente. Si basa sul
flusso di concessione implicita OAuth 2.0 ed è progettata per consentirti di chiamare direttamente le API di Google
utilizzando REST e CORS o di utilizzare la nostra libreria client delle API di Google per
JavaScript (nota anche come gapi.client) per un accesso flessibile alle nostre
API più complesse.
Prima di accedere ai dati utente protetti da un browser, gli utenti del tuo sito attivano i processi di scelta dell'account, accesso e consenso basati sul web di Google e, infine, i server OAuth di Google emettono e restituiscono un token di accesso alla tua app web.
Nel modello di autorizzazione basato su token, non è necessario archiviare i token di aggiornamento per utente sul server di backend.
Ti consigliamo di seguire l'approccio descritto qui anziché le tecniche trattate nella guida precedente OAuth 2.0 per applicazioni web lato client.
Prerequisiti
Segui i passaggi descritti in Configurazione per configurare la schermata per il consenso OAuth , ottenere un ID client e caricare la libreria client.
Inizializzare un client token
Chiama initTokenClient() per inizializzare un nuovo client token con l'ID client della tua app web
. Devi includere un elenco di uno o più ambiti a cui l'utente
deve accedere:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (response) => {
...
},
});
Attivare il flusso di token OAuth 2.0
Utilizza il metodo requestAccessToken() per attivare il flusso dell'interfaccia utente del token e ottenere un token di accesso. Google chiede all'utente di:
- Scegliere il proprio account.
- Accedere all'Account Google, se non l'ha già fatto.
- Concedere il consenso alla tua app web per accedere a ogni ambito richiesto.
L'attivazione dall'utente attiva il flusso di token:
<button onclick="client.requestAccessToken();">Authorize me</button>
Google restituisce quindi un TokenResponse contenente un token di accesso e un elenco di ambiti a cui l'utente ha concesso l'accesso o un errore al gestore callback.
Gli utenti possono chiudere le finestre di scelta dell'account o di accesso, nel qual caso la funzione di callback non verrà richiamata.
Come gestire il consenso
La progettazione e l'esperienza utente della tua app devono essere implementate solo dopo un'attenta revisione delle Norme relative a OAuth 2.0 di Google. Queste norme riguardano l'utilizzo di più ambiti, quando e come gestire il consenso dell'utente e altro ancora.
L'autorizzazione incrementale è una metodologia di progettazione di policy e app utilizzata per richiedere l'accesso alle risorse, utilizzando gli ambiti, solo quando necessario anziché in anticipo e contemporaneamente. Gli utenti possono approvare o rifiutare la condivisione delle singole risorse richieste dalla tua app. Questa operazione è nota come autorizzazioni granulari.
Durante questa procedura, Google richiede il consenso dell'utente, elencando singolarmente ogni ambito richiesto, gli utenti selezionano le risorse da condividere con la tua app e, infine, Google richiama la funzione di callback per restituire un token di accesso e gli ambiti approvati dall'utente. La tua app gestisce in modo sicuro i vari risultati possibili con le autorizzazioni granulari.
Tuttavia, esistono delle eccezioni. Le app Google Workspace Enterprise con delega dell'autorità a livello di dominio o le app contrassegnate come attendibili, ignorano la schermata per il consenso delle autorizzazioni granulari. Per queste app, gli utenti non vedranno la schermata per il consenso delle autorizzazioni granulari. La tua app riceverà tutti gli ambiti richiesti o nessuno.
Per informazioni più dettagliate, vedi Come gestire le autorizzazioni granulari.
Autorizzazione incrementale
Per le app web, i due scenari di alto livello riportati di seguito illustrano l'autorizzazione incrementale utilizzando:
- Un'app Ajax a pagina singola, che spesso utilizza
XMLHttpRequestcon accesso dinamico alle risorse. - Più pagine web, le risorse sono separate e gestite in base alla pagina.
Questi due scenari vengono presentati per illustrare le considerazioni e le metodologie di progettazione, ma non sono intesi come raccomandazioni complete su come integrare il consenso nella tua app. Le app reali possono utilizzare una variazione o una combinazione di queste tecniche.
Ajax
Aggiungi il supporto per l'autorizzazione incrementale alla tua app effettuando più chiamate a requestAccessToken() e utilizzando il parametro scope dell'oggetto OverridableTokenClientConfig per richiedere singoli ambiti nel momento in cui sono necessari e solo quando necessario. In questo esempio, le risorse verranno richieste e saranno visibili solo dopo che un'attivazione dall'utente espande una sezione di contenuti compressa.
| App Ajax |
|---|
Inizializza il client token al caricamento pagina:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Documenti da leggereMostra i documenti recenti
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Prossimi eventiMostra le informazioni del calendario
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Carosello di fotoMostra le foto
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Ogni chiamata a requestAccessToken attiva un momento di consenso dell'utente. La tua app avrà accesso solo alle risorse richieste dalla sezione che un utente sceglie di espandere, limitando così la condivisione delle risorse tramite la scelta dell'utente.
Più pagine web
Quando progetti per l'autorizzazione incrementale, vengono utilizzate più pagine per richiedere solo gli ambiti necessari per caricare una pagina, riducendo la complessità e la necessità di effettuare più chiamate per ottenere il consenso dell'utente e recuperare un token di accesso.
| App multipagina | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Ogni pagina richiede l'ambito necessario e ottiene un token di accesso chiamando initTokenClient() e requestAccessToken() al tempo di caricamento. In questo scenario, le singole pagine web vengono utilizzate per separare chiaramente le funzionalità e le risorse utente per ambito. In una situazione reale, le singole pagine possono richiedere più ambiti correlati.
Autorizzazioni granulari
Le autorizzazioni granulari vengono gestite allo stesso modo in tutti gli scenari. Dopo che requestAccessToken() richiama la funzione di callback e viene restituito un token di accesso, verifica che l'utente abbia approvato gli ambiti richiesti utilizzando hasGrantedAllScopes() o hasGrantedAnyScope(). Ad esempio:
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
...
}
}
},
});
Nella risposta verranno incluse anche tutte le donazioni accettate in precedenza da sessioni o richieste precedenti. Un record del consenso dell'utente viene mantenuto per utente e ID client e persiste in più chiamate a initTokenClient() o requestAccessToken(). Per impostazione predefinita, il consenso dell'utente è necessario solo la prima volta che un utente visita il tuo sito web e richiede un nuovo ambito, ma può essere richiesto a ogni caricamento pagina utilizzando prompt=consent negli oggetti di configurazione del client token.
Utilizzare i token
Nel modello di token, un token di accesso non viene archiviato dal sistema operativo o dal browser, ma viene ottenuto un nuovo token al momento del caricamento della pagina o successivamente attivando una chiamata a requestAccessToken() tramite un'attivazione dall'utente, ad esempio la pressione di un pulsante.
Utilizzare REST e CORS con le API di Google
Un token di accesso può essere utilizzato per effettuare richieste autenticate alle API di Google utilizzando REST e CORS. In questo modo, gli utenti possono accedere, concedere il consenso, Google può emettere un token di accesso e il tuo sito può lavorare con i dati dell'utente.
In questo esempio, visualizza i prossimi eventi di calendario degli utenti che hanno eseguito l'accesso utilizzando il token di accesso restituito da 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();
Le API di Google supportano CORS per impostazione predefinita. L'inclusione di un token di accesso in una richiesta XMLHttpRequest o fetch attiva un controllo preflight CORS, ovvero una richiesta OPTIONS prima di una richiesta GET o POST.
La sezione successiva spiega come eseguire l'integrazione con API più complesse.
Utilizzare la libreria JavaScript delle API di Google
Il client token funziona con la libreria client delle API di Google per JavaScript Consulta il seguente snippet di codice.
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(...);
}
Scadenza del token
Per progettazione, i token di accesso hanno una durata breve. Se il token di accesso scade prima della fine della sessione dell'utente, ottieni un nuovo token chiamando requestAccessToken() da un evento guidato dall'utente, ad esempio la pressione di un pulsante.
Utilizzare un token di accesso per revocare il consenso
Chiama il metodo google.accounts.oauth2.revoke per rimuovere il consenso dell'utente e l'accesso alle risorse per tutti gli ambiti concessi alla tua app. Per revocare questa autorizzazione è necessario un token di accesso valido:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});