OAuth 2.0 pour les applications Web côté client

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

Vous trouverez ci-dessous un exemple d'URL, avec des sauts de ligne et des espaces pour une meilleure lisibilité.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.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

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 de ressources inter-origines (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/drive.metadata.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 au redirect_uri spécifié 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:

• Une réponse du jeton d'accès:

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

  Outre le 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 Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.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

Après avoir terminé le flux OAuth 2.0, vous serez redirigé vers http://localhost/oauth2callback. Cette URL générera 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 le ou les champs d'application 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 Authorization d'en-tête HTTP Bearer. Dans la mesure du possible, il est préférable d'utiliser l'en-tête HTTP, 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 Drive Files).

Vous pouvez essayer toutes les API Google et consulter leurs habilitations sur OAuth 2.0 Playground.

Exemples HTTP GET

Un appel vers le point de terminaison drive.files (API Drive Files) avec 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 /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Voici un appel vers 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/drive/v2/files?access_token=access_token

Exemples curl

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é):

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

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

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

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. Cependant, même si vous n'utilisez pas la bibliothèque cliente, le guide sur la compatibilité CORS 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/drive/v3/about?fields=user&' +
    '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 parcours 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 pour 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, elle lance le flux OAuth 2.0.

Pour le flux OAuth 2.0, procédez comme suit:

1. Il 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/drive.metadata.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 utilise le jeton d'accès pour effectuer l'exemple de requête API.

   La requête API appelle la méthode about.get de l'API Drive pour récupérer des informations sur le compte Google Drive 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 est listée dans la documentation de démonstration OAuth 2.0 pour l'API Google Docs.

Pour exécuter ce code localement, vous devez définir les valeurs des 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 sur laquelle 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 s'affiche. Votre projet doit également activer 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';
  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/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 {
      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/drive.metadata.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>

Points de terminaison OAuth 2.0

Pour ajouter des champs d'application à un jeton d'accès existant, incluez le paramètre include_granted_scopes dans votre requête envoyé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 habilitations pour lesquelles votre jeton d'accès est valide dans l'espace de stockage local du navigateur. L'exemple complet stocke une liste de 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 de code compare les champs d'application pour lesquels le jeton d'accès est valide à ceux que vous souhaitez utiliser pour une requête donnée. 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 (qui est fournie plus loin dans l'exemple complet).

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

Points de terminaison OAuth 2.0

Pour révoquer programmatiquement un jeton, 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}

Le jeton peut être un jeton d'accès ou un jeton d'actualisation. Si le jeton est un jeton d'accès et qu'il possède un jeton d'actualisation correspondant, il est é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 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();
}