OAuth 2.0 per applicazioni web lato client

Endpoint OAuth 2.0

Genera un URL per richiedere l'accesso dall'endpoint OAuth 2.0 di Google all'indirizzo https://accounts.google.com/o/oauth2/v2/auth. Questo endpoint è accessibile tramite HTTPS. Le connessioni HTTP non protette vengono rifiutate.

Il server di autorizzazione di Google supporta i seguenti parametri di stringa di query per le applicazioni di server web:

Esempio di reindirizzamento al server di autorizzazione di Google

Di seguito è riportato un URL di esempio, con interruzioni di riga e spazi per la leggibilità.

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

Dopo aver creato l'URL della richiesta, reindirizza l'utente a questo URL.

Codice di esempio JavaScript

Il seguente snippet JavaScript mostra come avviare il flusso di autorizzazione in JavaScript senza utilizzare la libreria client delle API di Google per JavaScript. Poiché questo endpoint OAuth 2.0 non supporta la condivisione delle risorse tra origini (CORS), lo snippet crea un modulo che apre la richiesta a quell'endpoint.

/*
 * 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();
}

Endpoint OAuth 2.0

Il server OAuth 2.0 invia una risposta all'redirect_uri specificato nella richiesta del token di accesso.

Se l'utente approva la richiesta, la risposta contiene un token di accesso. Se l'utente non approva la richiesta, la risposta contiene un messaggio di errore. Il token di accesso o il messaggio di errore viene restituito nel frammento di hash dell'URI di reindirizzamento, come mostrato di seguito:

• Una risposta del token di accesso:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  Oltre al parametro access_token, la stringa del frammento contiene anche il parametro token_type, che è sempre impostato su Bearer, e il parametro expires_in, che specifica la durata del token in secondi. Se il parametro state è stato specificato nella richiesta dell'token di accesso, il relativo valore è incluso anche nella risposta.

• Una risposta di errore:

  https://oauth2.example.com/callback#error=access_denied

Esempio di risposta del server OAuth 2.0

Puoi testare questo flusso facendo clic sul seguente URL di esempio, che richiede accesso di sola lettura per visualizzare i metadati dei file in Google Drive e accesso di sola lettura per visualizzare gli eventi di Google Calendar:

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

Una volta completato il flusso OAuth 2.0, verrà visualizzata la pagina http://localhost/oauth2callback. L'URL restituirà un errore 404 NOT FOUND, a meno che la tua macchina locale non serva un file a quell'indirizzo. Il passaggio successivo fornisce ulteriori dettagli sulle informazioni restituite nell'URI quando l'utente viene reindirizzato alla tua applicazione.

Endpoint OAuth 2.0

Per verificare se l'utente ha concesso alla tua applicazione l'accesso a un determinato ambito, esamina il campo scope nella risposta del token di accesso. Gli ambiti di accesso concessi dal token di accesso espressi come un elenco di stringhe sensibili alle maiuscole delimitate da spazi.

Ad esempio, la seguente risposta di esempio del token di accesso indica che l'utente ha concesso alla tua applicazione l'accesso alle autorizzazioni di sola lettura per le attività di Drive e gli eventi di Calendar:

  {
    "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"
  }

Endpoint OAuth 2.0

Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API Google per conto di un determinato account utente se gli ambiti di accesso richiesti dall'API sono stati concessi. Per farlo, includi il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile l'intestazione HTTP, perché le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, quando chiami l'API Drive Files).

Puoi provare tutte le API di Google e visualizzarne gli ambiti in OAuth 2.0 Playground.

Esempi di richieste GET HTTP

Una chiamata all'endpoint drive.files (l'API Drive Files) che utilizza l'intestazione HTTP Authorization: Bearer potrebbe avere il seguente aspetto. Tieni presente che devi specificare il tuo token di accesso:

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

Ecco una chiamata alla stessa API per l'utente autenticato che utilizza il parametro della stringa di query access_token:

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

curl esempi

Puoi testare questi comandi con l'applicazione a riga di comando curl. Ecco un esempio che utilizza l'opzione dell'intestazione HTTP (opzione preferita):

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

In alternativa, l'opzione del parametro stringa di query:

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

Codice di esempio JavaScript

Lo snippet di codice riportato di seguito mostra come utilizzare CORS (Cross-Origin Resource Sharing) per inviare una richiesta a un'API di Google. Questo esempio non utilizza la libreria client delle API di Google per JavaScript. Tuttavia, anche se non utilizzi la libreria client, la guida al supporto CORS nella documentazione della libreria potrebbe aiutarti a comprendere meglio queste richieste.

In questo snippet di codice, la variabile access_token rappresenta il token che hai ottenuto per effettuare richieste API per conto dell'utente autorizzato. L'esempio completo mostra come memorizzare il token nello spazio di archiviazione locale del browser e recuperarlo quando viene effettuata una richiesta API.

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);

Endpoint OAuth 2.0

Questo esempio di codice mostra come completare il flusso OAuth 2.0 in JavaScript senza utilizzare la libreria client delle API di Google per JavaScript. Il codice è per una pagina HTML che mostra un pulsante per provare una richiesta API. Se fai clic sul pulsante, il codice controlla se la pagina ha memorizzato un token di accesso API nello spazio di archiviazione locale del browser. In questo caso, esegue la richiesta API. In caso contrario, avvia il flusso OAuth 2.0.

Per il flusso OAuth 2.0, la pagina segue questi passaggi:

1. Indirizza l'utente al server OAuth 2.0 di Google, che richiede l'accesso agli ambiti https://www.googleapis.com/auth/drive.metadata.readonly e https://www.googleapis.com/auth/calendar.readonly.
2. Dopo aver concesso (o negato) l'accesso a uno o più ambiti richiesti, l'utente viene reindirizzato alla pagina originale, che analizza il token di accesso dalla stringa dell'identificatore del frammento.
3. La pagina controlla gli ambiti a cui l'utente ha concesso l'accesso all'applicazione.

4. Se l'utente ha concesso l'accesso agli scope() richiesti, la pagina utilizza il token di accesso per effettuare la richiesta API di esempio.

   La richiesta API chiama il metodo about.get dell'API Drive per recuperare informazioni sull'account Google Drive dell'utente autorizzato.

5. Se la richiesta viene eseguita correttamente, la risposta dell'API viene registrata nella console di debugging del browser.

Puoi revocare l'accesso all'app tramite la pagina Autorizzazioni del tuo Account Google. L'app verrà elencata come Demo OAuth 2.0 per la documentazione dell'API Google.

Per eseguire questo codice localmente, devi impostare i valori per le variabili YOUR_CLIENT_ID e YOUR_REDIRECT_URI corrispondenti alle tue credenziali di autorizzazione. La variabile YOUR_REDIRECT_URI deve essere impostata sullo stesso URL in cui viene pubblicata la pagina. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0 che hai configurato in API Console Credentials page. Se questo valore non corrisponde a un URI autorizzato, verrà visualizzato un errore redirect_uri_mismatch. Per questa richiesta, nel progetto deve essere stata anche attivata l'API appropriata.

<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>

Endpoint OAuth 2.0

Per aggiungere ambiti a un token di accesso esistente, includi il parametro include_granted_scopes nella richiesta al server OAuth 2.0 di Google.

Il seguente snippet di codice mostra come eseguire questa operazione. Lo snippet presuppone che tu abbia memorizzato gli ambiti per i quali il token di accesso è valido nello spazio di archiviazione locale del browser. Il codice dell'esempio completo memorizza un elenco di ambiti per i quali il token di accesso è valido impostando la proprietà oauth2-test-params.scope nello spazio di archiviazione locale del browser.

Lo snippet confronta gli ambiti per i quali il token di accesso è valido con l'ambito che vuoi utilizzare per una determinata query. Se il token di accesso non copre questo ambito, viene avviato il flusso OAuth 2.0. Qui la funzione oauth2SignIn è la stessa fornita nel passaggio 2 (e fornita più avanti nell'esempio completo).

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.
}

Endpoint OAuth 2.0

Per revocare un token in modo programmatico, l'applicazione invia una richiesta a https://oauth2.googleapis.com/revoke e include il token come parametro:

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

Il token può essere un token di accesso o un token di aggiornamento. Se il token è un token di accesso e ha un token di aggiornamento corrispondente, anche il token di aggiornamento verrà revocato.

Se la revoca viene elaborata correttamente, il codice di stato HTTP della risposta è 200. Per le condizioni di errore, viene restituito un codice di stato HTTP 400 insieme a un codice di errore.

Lo snippet JavaScript seguente mostra come revocare un token in JavaScript senza utilizzare la libreria client delle API di Google per JavaScript. Poiché l'endpoint OAuth 2.0 di Google per la revoca dei token non supporta la condivisione delle risorse tra origini (CORS), il codice crea un modulo e lo invia all'endpoint anziché utilizzare il metodo XMLHttpRequest() per pubblicare la richiesta.

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();
}