La libreria JavaScript google.accounts.oauth2 consente di richiedere il consenso dell'utente e di ottenere un token di accesso per utilizzare i dati utente. Si basa sul flusso di concessione implicita OAuth 2.0 ed è progettato per consentirti di chiamare le API di Google direttamente utilizzando REST e CORS oppure per 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 il selettore account, l'accesso e i processi di consenso di Google basati sul Web. Infine, i server OAuth di Google emettono e restituiscono un token di accesso alla tua app web.
Nel modello di autorizzazione basata 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 illustrate nella precedente guida OAuth 2.0 per applicazioni web lato client.
Configurazione
Trova o crea un ID client seguendo i passaggi descritti nella guida Ottenere l'ID client API di Google. A questo punto, aggiungi la libreria client alle pagine
del tuo sito che chiameranno le API di Google. Infine, inizializza il client
token. In genere, questa operazione viene eseguita all'interno del gestore onload della libreria client.
Inizializzare un client token
Chiama initTokenClient() per inizializzare un nuovo client token con l'ID client della tua app web. Se vuoi, puoi 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 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 già fatto
- Concedi alla tua app web il consenso ad 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 tuo gestore di callback.
Gli utenti possono chiudere il selettore account o le finestre 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 aver esaminato attentamente i criteri OAuth 2.0 di Google. Queste norme riguardano l'utilizzo di più ambiti, nonché quando e come gestire il consenso degli utenti e altro ancora.
L'autorizzazione incrementale è una metodologia di progettazione dei criteri e delle app utilizzata per richiedere l'accesso alle risorse, utilizzando gli ambiti, solo in base alle necessità e non in modo iniziale e tutto in una volta sola. Gli utenti possono approvare o rifiutare la condivisione delle singole risorse richieste dalla tua app. Queste autorizzazioni sono note 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. L'app gestisce quindi in modo sicuro i vari risultati possibili con autorizzazioni granulari.
Autorizzazione incrementale
Per le app web, i seguenti due scenari di alto livello mostrano l'autorizzazione incrementale mediante:
- 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 considerazioni di progettazione e metodologie, ma non intendono essere consigli esaustivi su come generare il consenso nella tua app. Le app reali possono utilizzare una variante 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 saranno richieste e saranno visibili
solo dopo che un gesto dell'utente espanderà una sezione di contenuti compressi.
| App Ajax |
|---|
Inizializza il client del token al caricamento della pagina:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Richiedi il consenso e ottieni i token di accesso tramite i gesti dell'utente. Fai clic su "+" per aprire:
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 fotoMostra foto
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Ogni chiamata a requestAccessToken attiva un momento per il 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 per l'autorizzazione incrementale, vengono utilizzate più pagine per richiedere solo gli ambiti necessari per caricare una pagina, il che riduce la complessità e la necessità di effettuare più chiamate per ottenere il consenso dell'utente e recuperare un token di accesso.
| App su più pagine | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Ogni pagina richiede l'ambito necessario e ottiene un token di accesso chiamando initTokenClient() e requestAccessToken() al momento del caricamento. In questo scenario, vengono utilizzate singole pagine web per separare chiaramente le funzionalità e le risorse utente in base all'ambito. In una situazione reale, singole pagine possono richiedere più ambiti correlati.
Autorizzazioni granulari
Le autorizzazioni granulari vengono gestite allo stesso modo in tutti gli scenari; dopo che requestAccessToken() chiama la funzione di callback e restituisce 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 saranno incluse anche tutte le concessioni accettate in precedenza da sessioni o richieste precedenti. Viene conservato un record del consenso dell'utente per utente e ID client e viene mantenuto per 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 Client token.
Utilizzare i token
Nel modello di token, un token di accesso non viene archiviato dal sistema operativo o dal browser, ma viene prima ottenuto un nuovo token 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
È possibile usare un token di accesso per inviare richieste autenticate alle API di Google mediante REST e CORS. Ciò consente agli utenti di accedere, concedere il consenso, Google di emettere un token di accesso e il tuo sito per 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 ulteriori informazioni, vedi Come utilizzare CORS per accedere alle API di Google.
La prossima sezione spiega come integrarsi facilmente con API più complesse.
Utilizzo della libreria JavaScript delle API di Google
Il client token funziona con la libreria client delle API di Google per JavaScript. Consulta lo snippet di codice riportato 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
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 gestito 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 degli utenti 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);
});