Utilizzo di OAuth 2.0 per applicazioni web JavaScript

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 semplici vengono rifiutate.

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

Reindirizzamento di esempio al server di autorizzazione di Google

L'URL di esempio riportato di seguito richiede l'accesso offline (access_type=offline) a un ambito che consente l'accesso per recuperare i report di YouTube Analytics dell'utente. Utilizza l'autorizzazione incrementale per garantire che il nuovo token di accesso copra tutti gli ambiti a cui l'utente ha precedentemente concesso l'accesso all'applicazione. L'URL imposta anche i valori per i parametri obbligatori redirect_uri, response_type e client_id, nonché per il parametro state. L'URL contiene interruzioni di riga e spazi per una maggiore leggibilità.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

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

Codice di esempio JavaScript

Lo snippet JavaScript riportato di seguito 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 questo 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/yt-analytics.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 al 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 sul frammento 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 di 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 del token di accesso, anche il relativo valore è incluso 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 l'accesso di sola lettura per visualizzare i metadati dei file su Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

Dopo aver completato il flusso OAuth 2.0, si aprirà la pagina http://localhost/oauth2callback. L'URL restituirà un errore 404 NOT FOUND, a meno che la tua macchina locale non pubblichi 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

Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API di Google per conto di un determinato account utente, nel caso in cui siano stati concessi gli ambiti di accesso richiesti dall'API. A questo scopo, includi il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer di intestazione HTTP Authorization. Quando possibile, è preferibile utilizzare 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 YouTube Analytics).

Tieni presente che l'API YouTube Analytics non supporta il flusso dell'account di servizio. L'API di reporting di YouTube supporta gli account di servizio solo per i proprietari di contenuti YouTube che possiedono e gestiscono più canali YouTube, come case discografiche e studi cinematografici.

Puoi provare tutte le API di Google e visualizzarne gli ambiti nello spazio pubblico OAuth 2.0.

Esempi di GET HTTP

Una chiamata all'endpoint reports.query (l'API YouTube Analytics) utilizzando l'intestazione HTTP Authorization: Bearer potrebbe avere il seguente aspetto. Tieni presente che devi specificare il tuo token di accesso:

GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

Esempi di curl

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/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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. In questo esempio non viene utilizzata la libreria client delle API di Google per JavaScript. Tuttavia, anche se non utilizzi la libreria client, la guida al supporto di CORS nella documentazione relativa alla libreria ti aiuterà 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 archiviare il token nello spazio di archiviazione locale del browser e recuperarlo quando si effettua una richiesta API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
    '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 riguarda una pagina HTML che mostra un pulsante per provare una richiesta API. Se fai clic sul pulsante, il codice controlla se la pagina ha archiviato un token di accesso all'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 all'ambito https://www.googleapis.com/auth/yt-analytics.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 di frammento.

3. La pagina utilizza il token di accesso per effettuare la richiesta API di esempio.

   Questa richiesta API chiama il metodo reports.query dell'API YouTube Analytics per recuperare il numero di visualizzazioni del canale YouTube dell'utente autorizzato.

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

Puoi revocare l'accesso all'app tramite la pagina Autorizzazioni del tuo Account Google. L'app sarà elencata come Demo OAuth 2.0 per documenti relativi alle API di Google.

Per eseguire questo codice in locale, devi impostare i valori delle variabili YOUR_CLIENT_ID e YOUR_REDIRECT_URI che corrispondono 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, riceverai un errore redirect_uri_mismatch. Il progetto deve anche aver abilitato l'API appropriata per questa richiesta.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

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

  // 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']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
          '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 {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // 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/yt-analytics.readonly',
                  'state': 'try_sample_request',
                  '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

In questo esempio, l'applicazione chiamante richiede l'accesso per recuperare i dati di YouTube Analytics dell'utente, oltre a qualsiasi altro accesso già concesso dall'utente all'applicazione.

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

Lo snippet di codice riportato di seguito mostra come eseguire questa operazione. Lo snippet presuppone che tu abbia archiviato gli ambiti per i quali il token di accesso è valido nello spazio di archiviazione locale del browser. Nel codice dell'esempio completo viene archiviato 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 quell'ambito, viene avviato il flusso OAuth 2.0. In questo caso, la funzione oauth2SignIn è uguale a quella fornita nel passaggio 2 (e indicata più avanti nell'esempio completo).

var SCOPE = 'https://www.googleapis.com/auth/yt-analytics.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 in modo programmatico un token, la tua 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 di aggiornamento. Se il token è un token di accesso e ha un token di aggiornamento corrispondente, verrà revocato anche il token di aggiornamento.

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 riportato di seguito 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 invece di 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();
}