Utiliser OAuth 2.0 pour les applications Web JavaScript

Points de terminaison OAuth 2.0

Générez une URL pour demander l'accès au point de terminaison OAuth 2.0 de Google sur https://accounts.google.com/o/oauth2/v2/auth. Ce point de terminaison est accessible via HTTPS. Les connexions HTTP simples sont refusées.

Le serveur d'autorisation Google est compatible avec les paramètres de chaîne de requête suivants pour les applications de serveur Web:

Exemple de redirection vers le serveur d'autorisation de Google

L'exemple d'URL ci-dessous demande un accès hors connexion (access_type=offline) à un champ d'application qui permet d'accéder aux rapports YouTube Analytics de l'utilisateur. Il utilise une autorisation incrémentielle pour s'assurer que le nouveau jeton d'accès couvre tous les niveaux d'accès auxquels l'utilisateur a précédemment accordé l'accès à l'application. L'URL définit également des valeurs pour les paramètres redirect_uri, response_type et client_id requis, ainsi que pour le paramètre state. L'URL contient des sauts de ligne et des espaces pour améliorer la lisibilité.

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

Une fois l'URL de la requête créée, redirigez-y l'utilisateur.

Exemple de code JavaScript

L'extrait JavaScript suivant montre comment lancer le flux d'autorisation en JavaScript sans utiliser la bibliothèque cliente des API Google pour JavaScript. Étant donné que ce point de terminaison OAuth 2.0 n'est pas compatible avec le partage de ressources entre origines (CORS), l'extrait crée un formulaire qui ouvre la requête vers ce point de terminaison.

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

Points de terminaison OAuth 2.0

Le serveur OAuth 2.0 envoie une réponse à l'redirect_uri spécifié dans votre requête de jeton d'accès.

Si l'utilisateur approuve la requête, la réponse contient un jeton d'accès. Si l'utilisateur n'approuve pas la requête, la réponse contient un message d'erreur. Le jeton d'accès ou le message d'erreur est renvoyé dans le fragment de hachage de l'URI de redirection, comme illustré ci-dessous:

• Réponse d'un jeton d'accès:

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

  En plus du paramètre access_token, la chaîne de fragment contient également le paramètre token_type, qui est toujours défini sur Bearer, et le paramètre expires_in, qui spécifie la durée de vie du jeton, en secondes. Si le paramètre state a été spécifié dans la requête de jeton d'accès, sa valeur est également incluse dans la réponse.

• Réponse d'erreur:

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

Exemple de réponse du serveur OAuth 2.0

Vous pouvez tester ce flux en cliquant sur l'exemple d'URL suivant, qui demande un accès en lecture seule pour afficher les métadonnées des fichiers de votre compte Google Drive et un accès en lecture seule pour afficher vos événements Google Agenda:

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

Une fois le flux OAuth 2.0 terminé, vous serez redirigé vers http://localhost/oauth2callback. Cette URL génère une erreur 404 NOT FOUND, sauf si votre machine locale diffuse un fichier à cette adresse. L'étape suivante fournit plus d'informations sur les informations renvoyées dans l'URI lorsque l'utilisateur est redirigé vers votre application.

Points de terminaison OAuth 2.0

Pour vérifier si l'utilisateur a accordé à votre application l'accès à un champ d'application particulier, examinez le champ scope dans la réponse du jeton d'accès. Champs d'application d'accès accordés par le jeton d'accès, exprimés sous la forme d'une liste de chaînes sensibles à la casse, délimitées par des espaces.

Par exemple, l'exemple de réponse du jeton d'accès suivant indique que l'utilisateur a accordé à votre application l'accès aux autorisations d'activité Drive en lecture seule et aux événements Agenda:

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

Points de terminaison OAuth 2.0

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour effectuer des appels à une API Google au nom d'un compte utilisateur donné si le ou les champs d'application de l'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête envoyée à l'API en incluant un paramètre de requête access_token ou une valeur Bearer d'en-tête HTTP Authorization. Lorsque c'est possible, l'en-tête HTTP est préférable, car les chaînes de requête ont tendance à être visibles dans les journaux du serveur. Dans la plupart des cas, vous pouvez utiliser une bibliothèque cliente pour configurer vos appels aux API Google (par exemple, lorsque vous appelez l'API YouTube Analytics).

Notez que l'API YouTube Analytics n'est pas compatible avec le flux de compte de service. L'API YouTube Reporting n'est compatible qu'avec les comptes de service des propriétaires de contenu YouTube qui possèdent et gèrent plusieurs chaînes YouTube, comme les maisons de disques et les studios de cinéma.

Vous pouvez tester toutes les API Google et consulter leurs champs d'application sur OAuth 2.0 Playground.

Exemples de requêtes HTTP GET

Un appel au point de terminaison reports.query (API YouTube Analytics) à l'aide de l'en-tête HTTP Authorization: Bearer peut se présenter comme suit. Notez que vous devez spécifier votre propre jeton d'accès:

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

Voici un appel à la même API pour l'utilisateur authentifié à l'aide du paramètre de chaîne de requête 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

curl exemples

Vous pouvez tester ces commandes avec l'application de ligne de commande curl. Voici un exemple qui utilise l'option d'en-tête HTTP (recommandée):

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

Vous pouvez également utiliser l'option de paramètre de chaîne de requête:

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

Exemple de code JavaScript

L'extrait de code ci-dessous montre comment utiliser le partage de ressources entre origines (CORS) pour envoyer une requête à une API Google. Cet exemple n'utilise pas la bibliothèque cliente des API Google pour JavaScript. Toutefois, même si vous n'utilisez pas la bibliothèque cliente, le guide de compatibilité avec CORS de la documentation de cette bibliothèque vous aidera probablement à mieux comprendre ces requêtes.

Dans cet extrait de code, la variable access_token représente le jeton que vous avez obtenu pour envoyer des requêtes API au nom de l'utilisateur autorisé. L'exemple complet montre comment stocker ce jeton dans l'espace de stockage local du navigateur et le récupérer lors de l'envoi d'une requête 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);

Points de terminaison OAuth 2.0

Cet exemple de code montre comment effectuer le flux OAuth 2.0 en JavaScript sans utiliser la bibliothèque cliente des API Google pour JavaScript. Le code est destiné à une page HTML qui affiche un bouton permettant d'essayer une requête API. Si vous cliquez sur le bouton, le code vérifie si la page a stocké un jeton d'accès à l'API dans l'espace de stockage local de votre navigateur. Si c'est le cas, il exécute la requête API. Sinon, il lance le flux OAuth 2.0.

Pour le flux OAuth 2.0, la page suit ces étapes:

1. Il redirige l'utilisateur vers le serveur OAuth 2.0 de Google, qui demande l'accès aux habilitations https://www.googleapis.com/auth/yt-analytics.readonly et https://www.googleapis.com/auth/calendar.readonly.
2. Après avoir accordé (ou refusé) l'accès à un ou plusieurs champs d'application demandés, l'utilisateur est redirigé vers la page d'origine, qui analyse le jeton d'accès à partir de la chaîne d'identifiant de fragment.
3. La page vérifie les autorisations que l'utilisateur a accordées à l'application.

4. Si l'utilisateur a accordé l'accès aux champs d'application demandés, la page utilise le jeton d'accès pour envoyer l'exemple de requête API.

   Cette requête d'API appelle la méthode reports.query de l'API YouTube Analytics pour récupérer le nombre de vues de la chaîne YouTube de l'utilisateur autorisé.

5. Si la requête s'exécute correctement, la réponse de l'API est enregistrée dans la console de débogage du navigateur.

Vous pouvez révoquer l'accès à l'application sur la page Autorisations de votre compte Google. L'application sera listée sous le nom Démo OAuth 2.0 pour la documentation des API Google.

Pour exécuter ce code localement, vous devez définir des valeurs pour les variables YOUR_CLIENT_ID et YOUR_REDIRECT_URI qui correspondent à vos identifiants d'autorisation. La variable YOUR_REDIRECT_URI doit être définie sur la même URL que celle de la page diffusée. La valeur doit correspondre exactement à l'un des URI de redirection autorisés pour le client OAuth 2.0, que vous avez configuré dans API Console Credentials page. Si cette valeur ne correspond pas à un URI autorisé, une erreur redirect_uri_mismatch s'affiche. Votre projet doit également avoir activé l'API appropriée pour cette requête.

<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/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 {
        // 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/yt-analytics.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>

Points de terminaison OAuth 2.0

Dans cet exemple, l'application appelante demande l'accès pour récupérer les données YouTube Analytics de l'utilisateur en plus de tout autre accès que l'utilisateur a déjà accordé à l'application.

Pour ajouter des habilitations à un jeton d'accès existant, incluez le paramètre include_granted_scopes dans votre requête adressée au serveur OAuth 2.0 de Google.

L'extrait de code suivant montre comment procéder. L'extrait suppose que vous avez stocké les portées pour lesquelles votre jeton d'accès est valide dans l'espace de stockage local du navigateur. (Le code de l'exemple complet stocke une liste des champs d'application pour lesquels le jeton d'accès est valide en définissant la propriété oauth2-test-params.scope dans l'espace de stockage local du navigateur.)

L'extrait compare les champs d'application pour lesquels le jeton d'accès est valide au champ d'application que vous souhaitez utiliser pour une requête particulière. Si le jeton d'accès ne couvre pas ce champ d'application, le flux OAuth 2.0 commence. Ici, la fonction oauth2SignIn est identique à celle fournie à l'étape 2 (et qui est fournie plus tard dans l'exemple complet).

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

Points de terminaison OAuth 2.0

Pour révoquer un jeton de manière programmatique, votre application envoie une requête à https://oauth2.googleapis.com/revoke et inclut le jeton en tant que paramètre:

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

Il peut s'agir d'un jeton d'accès ou d'un jeton d'actualisation. Si le jeton est un jeton d'accès et qu'il dispose d'un jeton d'actualisation correspondant, le jeton d'actualisation est également révoqué.

Si la révocation est traitée avec succès, le code d'état HTTP de la réponse est 200. Pour les conditions d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

L'extrait de code JavaScript suivant montre comment révoquer un jeton en JavaScript sans utiliser la bibliothèque cliente des API Google pour JavaScript. Étant donné que le point de terminaison OAuth 2.0 de Google pour la révocation des jetons n'est pas compatible avec le partage de ressources inter-origines (CORS), le code crée un formulaire et l'envoie au point de terminaison au lieu d'utiliser la méthode XMLHttpRequest() pour publier la requête.

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