Utilizzo del modello di token

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 è progettato 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 semplice e flessibile alle nostre API più complesse.

Prima di accedere ai dati utente protetti da un browser, gli utenti sul 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 qui delineato anziché le tecniche illustrate nella precedente guida OAuth 2.0 per le applicazioni web lato client.

Configurazione

Per trovare o creare un ID client, segui la procedura descritta nella guida all'acquisizione dell'ID client API di Google. Successivamente, 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.

Inizializza un client token

Chiama initTokenClient() per inizializzare un nuovo client token con l'ID client della tua app web. Facoltativamente, 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 dell'esperienza utente del token e ottenere un token di accesso. Google chiede all'utente di:

• Scegli l'account
• Accedi all'Account Google se non l'hai ancora fatto.
• concedi alla tua app web il consenso per accedere a ciascun ambito richiesto.

Il gesto del token viene attivato dal gesto dell'utente: <button onclick="client.requestAccessToken();">Authorize me</button>

Google restituisce quindi un TokenResponse con 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 il selettore account o le finestre di accesso, nel qual caso la tua funzione di callback non verrà richiamata.

Come gestire il consenso

Il design e l'esperienza utente dell'app devono essere implementati solo dopo un'attenta revisione delle norme OAuth 2.0 di Google. Questi criteri riguardano il lavoro con più ambiti, quando e come gestire il consenso degli utenti e altro ancora.

L'autorizzazione incrementale è una metodologia di progettazione di criteri e app utilizzata per richiedere l'accesso alle risorse utilizzando gli ambiti solo quando necessario e in anticipo allo stesso tempo. Gli utenti possono approvare o rifiutare la condivisione delle singole risorse richieste dalla tua app. Queste azioni sono note come autorizzazioni granulari.

Durante questa procedura, Google richiede il consenso degli utenti, 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. L'app gestisce quindi i vari risultati possibili in modo sicuro con autorizzazioni granulari.

Autorizzazione incrementale

Per le app web, i seguenti due scenari ad alto livello mostrano l'autorizzazione incrementale utilizzando:

• Un'app Ajax a pagina singola, spesso con XMLHttpRequest con accesso dinamico alle risorse.
• Più pagine web, le risorse sono separate e gestite a livello di pagina.

Questi due scenari vengono presentati per illustrare le considerazioni e le metodologie di progettazione, ma non intendono fornire suggerimenti completi su come sviluppare il consenso nella tua app. Le app reali possono utilizzare una variante o una combinazione di queste tecniche.

Ajax

Aggiungi il supporto per l'autorizzazione incrementale alla tua app effettuando più chiamate a requestAccessToken() e usando il parametro scope dell'oggetto OverridableTokenClientConfig per richiedere ambiti individuali al momento necessario e solo quando necessario. In questo esempio le risorse saranno richieste e visibili solo dopo che un gesto dell'utente espanderà una sezione di contenuti compressi.

        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
      

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

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

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

Ogni chiamata a requestAccessToken attiva un momento del consenso dell'utente, la tua app avrà accesso solo alle risorse richieste dalla sezione che un utente sceglie di espandere, limitando 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.

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          

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

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();
          

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 funzione di callback e un token di accesso restituito, 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 donazioni precedentemente accettate derivanti da sessioni o richieste precedenti. Un record del consenso dell'utente viene conservato per utente e ID client e persiste per più chiamate a initTokenClient() o requestAccessToken(). Per impostazione predefinita, il consenso degli utenti è 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 configurazione client di Token.

Utilizzo dei token

Nel modello di token, un token di accesso non viene memorizzato dal sistema operativo o dal browser, ma viene ottenuto un nuovo token al momento del caricamento della pagina o in seguito attivando una chiamata a requestAccessToken() tramite un gesto dell'utente, ad esempio premendo un pulsante.

Utilizzo di REST e CORS con le API di Google

Puoi utilizzare un token di accesso per effettuare richieste autenticate alle API di Google utilizzando REST e CORS. Ciò consente agli utenti di accedere, concedere il consenso, Google a emettere un token di accesso e il tuo sito per lavorare con i dati degli utenti.

In questo esempio, visualizza gli eventi di calendario imminenti 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, consulta la pagina Come utilizzare CORS per accedere alle API di Google.

La prossima sezione illustra come eseguire facilmente l'integrazione con API più complesse.

Utilizzare la 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 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 token

In base alla loro progettazione, i token di accesso hanno una breve durata. 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 una 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);
  });