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 di OAuth 2.0 ed è progettata per consentirti di chiamare le API di Google direttamente utilizzando REST e CORS oppure di utilizzare la nostra libreria client delle API di Google per JavaScript (nota anche come gapi.client) per un accesso semplice e 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 selezione, accesso e consenso dell'account 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.
Inizializza 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) => {
...
},
});
Attiva il flusso del token OAuth 2.0
Utilizza il metodo requestAccessToken() per attivare il flusso UX del token e ottenere un
token di accesso. Google chiede all'utente di:
- Scegli il suo account.
- accedi all'Account Google se non l'hai ancora fatto,
- concedere il consenso all'app web per accedere a ogni ambito richiesto.
Un gesto dell'utente attiva il flusso del 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 di callback.
Gli utenti possono chiudere le finestre di selezione dell'account o di accesso, nel qual caso la funzione di callback non verrà richiamata.
Come gestire il consenso
Il design e l'esperienza utente della tua app devono essere implementati solo dopo un'attenta revisione delle norme 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 in base alle necessità anziché in anticipo e tutte in una volta. Gli utenti possono approvare o rifiutare la condivisione delle singole risorse richieste dalla tua app. Questa operazione è nota come autorizzazioni granulari.
Durante questo processo, 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 tua 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, ci sono 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 alle autorizzazioni granulari. Per queste app, gli utenti non vedranno la schermata di consenso per le 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 mostrano l'autorizzazione incrementale utilizzando:
- Un'app Ajax a pagina singola, spesso utilizzando
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 considerazioni e metodologie di progettazione, ma non intendono essere consigli esaustivi su come integrare il consenso nella tua app. Le app reali potrebbero utilizzare una variazione o una combinazione di queste tecniche.
Ajax
Aggiungi il supporto dell'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 gesto dell'utente espande una sezione di contenuti compressa.
| App Ajax |
|---|
Inizializza il client token al caricamento della pagina:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Documenti da leggereMostra documenti recenti
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Prossimi eventiMostra informazioni calendario
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Carosello di fotoVisualizzare 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 si progetta 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 momento del caricamento. In questo scenario,
le singole pagine web vengono utilizzate per separare chiaramente le funzionalità e le risorse degli utenti in base all'ambito. In una situazione reale, le singole pagine potrebbero richiedere
più ambiti correlati.
Autorizzazioni granulari
Le autorizzazioni granulari vengono gestite allo stesso modo in tutti gli scenari; dopo che
requestAccessToken() richiama la tua 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 le concessioni precedentemente accettate di sessioni o richieste precedenti. Un record del consenso dell'utente viene mantenuto per utente e
ID cliente 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 della pagina utilizzando prompt=consent negli oggetti di configurazione del client token.
Utilizzo dei token
Nel modello di token, un token di accesso non viene memorizzato dal sistema operativo o dal browser, ma
un nuovo token viene ottenuto per la prima volta al momento del caricamento della pagina o successivamente attivando una
chiamata a requestAccessToken() tramite un gesto dell'utente, ad esempio la pressione di un pulsante.
Utilizzo di 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ò utilizzare 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();
Per saperne di più, consulta l'articolo Come utilizzare CORS per accedere alle API di Google.
La sezione successiva spiega come eseguire facilmente l'integrazione con API più complesse.
Utilizzo della libreria JavaScript delle API di Google
Il client token funziona con la libreria client dell'API di Google per JavaScript. Vedi lo snippet di codice di seguito.
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 basato sull'utente, ad esempio la pressione di un pulsante.
Utilizzo di 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);
});