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 à l'adresse 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 accepte 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 permettant d'afficher le compte YouTube de l'utilisateur. Il utilise une autorisation incrémentielle pour s'assurer que le nouveau jeton d'accès couvre tous les champs d'application auxquels l'utilisateur a précédemment accordé l'accès à l'application. L'URL définit également des valeurs pour les paramètres requis redirect_uri, response_type et client_id, ainsi que pour le paramètre state. L'URL contient des sauts de ligne et des espaces pour une meilleure lisibilité.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.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 requête créée, redirigez l'utilisateur vers celle-ci.

Exemple de code JavaScript

L'extrait de code 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 des ressources entre origines multiples (CORS), l'extrait crée un formulaire qui ouvre la requête à 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/youtube.force-ssl',
                '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'adresse redirect_uri spécifiée dans votre requête de jeton d'accès.

Si l'utilisateur approuve la demande, 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é sur le fragment de hachage de l'URI de redirection, comme indiqué ci-dessous:

• Réponse de 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'URL d'exemple suivante, qui demande un accès en lecture seule pour afficher les métadonnées des fichiers de votre Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.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 renverra une erreur 404 NOT FOUND, sauf si votre ordinateur local diffuse un fichier à cette adresse. L'étape suivante fournit plus de détails sur les informations renvoyées dans l'URI lorsque l'utilisateur est redirigé vers votre application.

Points de terminaison OAuth 2.0

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour appeler une API Google au nom d'un compte utilisateur donné si les champs d'application d'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête adressée à l'API en incluant un paramètre de requête access_token ou une valeur d'en-tête HTTP Authorization Bearer. Dans la mesure du 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 Data).

Notez que l'API YouTube Data n'accepte les comptes de service que pour les propriétaires de contenu YouTube qui possèdent et gèrent plusieurs chaînes YouTube, comme des maisons de disques et des studios de cinéma.

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

Exemples de requête HTTP GET

Un appel au point de terminaison youtube.channels (API YouTube Data) à 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/v3/channels?part=snippet&mine=true 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/v3/channels?access_token=access_token&part=snippet&mine=true

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/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Exemple de code JavaScript

L'extrait de code ci-dessous montre comment utiliser CORS (Cross-Origin Resource Sharing) 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 support CORS disponible dans 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 effectuer 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 d'une requête API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    '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 terminer 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 ce 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 tel 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 les étapes suivantes:

1. Elle redirige l'utilisateur vers le serveur OAuth 2.0 de Google, qui demande l'accès au champ d'application https://www.googleapis.com/auth/youtube.force-ssl.
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 utilise le jeton d'accès pour envoyer l'exemple de requête API.

   Cette requête API appelle la méthode channels.list de l'API YouTube Data pour récupérer des données sur la chaîne YouTube de l'utilisateur autorisé.

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

Vous pouvez révoquer l'accès à l'application via la page Autorisations de votre compte Google. L'application sera répertoriée en tant que Démo OAuth 2.0 pour la documentation sur les API Google.

Pour exécuter ce code localement, vous devez définir des valeurs pour les variables YOUR_CLIENT_ID et YOUR_REDIRECT_URI correspondant à vos identifiants d'autorisation. La variable YOUR_REDIRECT_URI doit être définie sur l'URL où la page est 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 est renvoyée. 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']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          '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() {
    // 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/youtube.force-ssl',
                  '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 champs d'application à un jeton d'accès existant, incluez le paramètre include_granted_scopes dans la requête envoyée au serveur OAuth 2.0 de Google.

L'extrait de code suivant montre comment procéder. Cet extrait suppose que vous avez stocké les niveaux d'accès pour lesquels votre jeton d'accès est valide dans l'espace de stockage local du navigateur. (L'exemple de code 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 à celui 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 démarre. Ici, la fonction oauth2SignIn est identique à celle fournie à l'étape 2 (et mentionnée plus loin dans l'exemple complet).

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
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 automatisée, 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 possède un jeton d'actualisation correspondant, il sera également révoqué.

Si la révocation a bien été traitée, 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 des ressources entre origines multiples (CORS), le code crée un formulaire et l'envoie au point de terminaison plutôt que 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();
}