OAuth 2.0 per applicazioni web lato client

Questo documento spiega come implementare l'autorizzazione OAuth 2.0 per accedere alle API di Google da un'applicazione web JavaScript. OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione, mantenendo privati i propri nomi utente, le password e altre informazioni. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione dagli utenti per archiviare i file nei loro Google Drive.

Questo flusso OAuth 2.0 è chiamato flusso di concessione implicita. È progettato per applicazioni che accedono alle API solo mentre l'utente è presente nell'applicazione. Queste applicazioni non sono in grado di memorizzare informazioni riservate.

In questo flusso, la tua app apre un URL Google che utilizza i parametri di query per identificare la tua app e il tipo di accesso API richiesto. Puoi aprire l'URL nella finestra del browser corrente o in un popup. L'utente può autenticarsi con Google e concedere le autorizzazioni richieste. Google reindirizza quindi l'utente alla tua app. Il reindirizzamento include un token di accesso, che la tua app verifica e poi utilizza per effettuare richieste API.

Libreria client delle API di Google e Google Identity Services

Se utilizzi la libreria client delle API di Google per JavaScript per effettuare chiamate autorizzate a Google, devi utilizzare la libreria JavaScript dei Servizi di identità Google per gestire il flusso OAuth 2.0. Consulta il modello di token dei servizi di identità di Google, basato sul flusso di concessione implicita OAuth 2.0.

Prerequisiti

Abilitare le API per il progetto

Qualsiasi applicazione che chiama le API di Google deve abilitarle in API Console.

Per abilitare un'API per il tuo progetto:

1. Open the API Library nella Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library elenca tutte le API disponibili, raggruppate per famiglia di prodotti e popolarità. Se l'API che vuoi attivare non è visibile nell'elenco, usa la ricerca per trovarla o fai clic su Visualizza tutto nella famiglia di prodotti a cui appartiene.
4. Seleziona l'API che vuoi abilitare, poi fai clic sul pulsante Abilita.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Crea le credenziali di autorizzazione

Qualsiasi applicazione che utilizza OAuth 2.0 per accedere alle API di Google deve disporre di credenziali di autorizzazione che identificano l'applicazione nel server OAuth 2.0 di Google. I passaggi seguenti spiegano come creare le credenziali per il tuo progetto. Le tue applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai abilitato per quel progetto.

1. Go to the Credentials page.
2. Fai clic su Crea cliente.
3. Seleziona il tipo di applicazione Applicazione web.
4. Compila il modulo. Le applicazioni che utilizzano JavaScript per effettuare richieste autorizzate alle API di Google devono specificare le origini JavaScript autorizzate. Le origini identificano i domini da cui la tua applicazione può inviare richieste al server OAuth 2.0. Queste origini devono rispettare le regole di convalida di Google.

Identificare gli ambiti di accesso

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, consentendo al contempo agli utenti di controllare la quantità di accesso che concedono alla tua applicazione. Pertanto, potrebbe esserci una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente.

Prima di iniziare a implementare l'autorizzazione OAuth 2.0, ti consigliamo di identificare gli ambiti a cui la tua app dovrà accedere.

Il documento Ambiti API OAuth 2.0 contiene un elenco completo di ambiti che puoi utilizzare per accedere alle API di Google.

Ottenere token di accesso OAuth 2.0

I seguenti passaggi mostrano come l'applicazione interagisce con il server OAuth 2.0 di Google per ottenere il consenso di un utente a eseguire una richiesta API per suo conto. La tua applicazione deve disporre di questo consenso prima di poter eseguire una richiesta API di Google che richiede l'autorizzazione dell'utente.

Passaggio 1: reindirizza al server OAuth 2.0 di Google

Per richiedere l'autorizzazione ad accedere ai dati di un utente, reindirizza l'utente al server OAuth 2.0 di Google.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

Passaggio 2: Google chiede il consenso all'utente

In questo passaggio, l'utente decide se concedere alla tua applicazione l'accesso richiesto. In questa fase, Google mostra una finestra di consenso che indica il nome dell'applicazione e i servizi dell'API di Google che sta richiedendo l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente, nonché un riepilogo degli ambiti di accesso da concedere. L'utente può quindi acconsentire a concedere l'accesso a uno o più ambiti richiesti dall'applicazione o rifiutare la richiesta.

A questo punto, l'applicazione non deve fare nulla, ma attende la risposta dal server OAuth 2.0 di Google che indica se è stato concesso l'accesso. Questa risposta è spiegata nel passaggio successivo.

Passaggio 3: gestisci la risposta del server OAuth 2.0

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Passaggio 4: controlla quali ambiti sono stati concessi dagli utenti

Quando richiedono più autorizzazioni (ambiti), gli utenti potrebbero non concedere alla tua app l'accesso a tutte. La tua app deve verificare quali ambiti sono stati effettivamente concessi e gestire in modo controllato le situazioni in cui alcune autorizzazioni vengono negate, in genere disattivando le funzionalità che si basano su questi ambiti negati.

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. Invece, la tua app riceverà tutti gli ambiti richiesti o nessuno.

Per informazioni più dettagliate, vedi Come gestire le autorizzazioni granulari.

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Chiamata alle API di Google

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Esempio completo

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        var xhr = new XMLHttpRequest();
        xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
        xhr.onreadystatechange = function (e) {
          if (xhr.readyState === 4 && xhr.status === 200) {
            console.log(xhr.response);
          } else if (xhr.readyState === 4 && xhr.status === 401) {
            // Token invalid, so prompt for user permission.
            oauth2SignIn();
          }
        };
        xhr.send(null);
      }
      else {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

Regole di convalida dell'origine JavaScript

Google applica le seguenti regole di convalida alle origini JavaScript per aiutare gli sviluppatori a mantenere sicure le loro applicazioni. Le origini JavaScript devono rispettare queste regole. Consulta la sezione 3 dell'RFC 3986 per la definizione di dominio, host e schema, menzionati di seguito.

Autorizzazione incrementale

Nel protocollo OAuth 2.0, la tua app richiede l'autorizzazione per accedere alle risorse, che sono identificate dagli ambiti. È considerata una best practice per l'esperienza utente richiedere l'autorizzazione per le risorse nel momento in cui ne hai bisogno. Per consentire questa pratica, il server di autorizzazione di Google supporta l'autorizzazione incrementale. Questa funzionalità ti consente di richiedere gli ambiti in base alle necessità e, se l'utente concede l'autorizzazione per il nuovo ambito, restituisce un codice di autorizzazione che può essere scambiato con un token contenente tutti gli ambiti che l'utente ha concesso al progetto.

Ad esempio, un'app che consente alle persone di ascoltare in anteprima le tracce musicali e creare mix potrebbe richiedere pochissime risorse al momento dell'accesso, forse solo il nome della persona che esegue l'accesso. Tuttavia, per salvare un mix completato è necessario l'accesso a Google Drive. La maggior parte delle persone troverebbe naturale se venisse chiesto l'accesso a Google Drive solo nel momento in cui l'app ne ha effettivamente bisogno.

In questo caso, al momento dell'accesso l'app potrebbe richiedere gli ambiti openid e profile per eseguire l'accesso di base e poi richiedere l'ambito https://www.googleapis.com/auth/drive.file al momento della prima richiesta di salvataggio di un mix.

Le seguenti regole si applicano a un token di accesso ottenuto da un'autorizzazione incrementale:

• Il token può essere utilizzato per accedere alle risorse corrispondenti a uno qualsiasi degli ambiti inclusi nella nuova autorizzazione combinata.
• Quando utilizzi il token di aggiornamento per l'autorizzazione combinata per ottenere un token di accesso, quest'ultimo rappresenta l'autorizzazione combinata e può essere utilizzato per qualsiasi valore di scope incluso nella risposta.
• L'autorizzazione combinata include tutti gli ambiti che l'utente ha concesso al progetto API anche se le concessioni sono state richieste da client diversi. Ad esempio, se un utente ha concesso l'accesso a un ambito utilizzando il client desktop di un'applicazione e poi ha concesso un altro ambito alla stessa applicazione tramite un client mobile, l'autorizzazione combinata includerà entrambi gli ambiti.
• Se revochi un token che rappresenta un'autorizzazione combinata, l'accesso a tutti gli ambiti di questa autorizzazione per conto dell'utente associato viene revocato contemporaneamente.

Gli esempi di codice riportati di seguito mostrano come aggiungere ambiti a un token di accesso esistente. Questo approccio consente alla tua app di evitare di dover gestire più token di accesso.

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

Revoca del token

In alcuni casi, un utente potrebbe voler revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le impostazioni dell'account. Per saperne di più, consulta la sezione Rimuovere l'accesso di un sito o di un'app del documento di assistenza App e siti di terze parti con accesso al tuo account.

È anche possibile che un'applicazione revochi a livello di programmazione l'accesso che le è stato concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione, rimuove un'applicazione o le risorse API richieste da un'app sono cambiate in modo significativo. In altre parole, parte della procedura di rimozione può includere una richiesta API per garantire che le autorizzazioni precedentemente concesse all'applicazione vengano rimosse.

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}