OAuth 2.0 pour les applications Web côté client

Ce document explique comment mettre en œuvre l'autorisation OAuth 2.0 pour accéder aux API Google à partir d'une application Web JavaScript. OAuth 2.0 permet aux utilisateurs de partager des données spécifiques avec une application tout en préservant la confidentialité de leurs noms d'utilisateur, mots de passe et autres informations. Par exemple, une application peut utiliser OAuth 2.0 pour obtenir l'autorisation des utilisateurs pour stocker des fichiers dans leurs Drive.

Ce parcours OAuth 2.0 est appelé flux d'octroi implicite. Il est conçu pour les applications qui accèdent aux API uniquement lorsque l'utilisateur est présent dans l'application. Ces applications ne sont pas en mesure de stocker des informations confidentielles.

Dans ce flux, votre application ouvre une URL Google qui utilise des paramètres de requête pour identifier votre application et le type d'accès à l'API requis par l'application. Vous pouvez l'ouvrir dans la fenêtre du navigateur actuel ou dans une fenêtre pop-up. L'utilisateur peut s'authentifier auprès de Google et accorder les autorisations demandées. Google redirige ensuite l'utilisateur vers votre application. Celle-ci inclut un jeton d'accès que votre application valide, puis utilise pour envoyer des requêtes API.

Prerequisites

Activer les API pour votre projet.

Toute application qui appelle les API Google doit activer ces API dans le API Console.

Pour activer une API pour votre projet:

  1. Open the API Library dans Google API Console.
  2. If prompted, select a project, or create a new one.
  3. API Library répertorie toutes les API disponibles, regroupées par famille de produits et classées en fonction de leur popularité. Si l'API que vous souhaitez activer n'est pas visible dans la liste, recherchez-la ou cliquez sur Tout afficher dans la famille de produits à laquelle elle appartient.
  4. Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Créer des identifiants d'autorisation

Toute application qui utilise OAuth 2.0 pour accéder aux API Google doit disposer d'identifiants d'autorisation qui identifient l'application sur le serveur OAuth 2.0 de Google. Les étapes suivantes expliquent comment créer des identifiants pour votre projet. Vos applications peuvent ensuite utiliser les identifiants pour accéder aux API que vous avez activées pour ce projet.

  1. Go to the Credentials page.
  2. Cliquez sur Créer des identifiants > ID client OAuth.
  3. Sélectionnez le type d'application Web application (Application Web).
  4. Remplissez le formulaire. Les applications qui utilisent JavaScript pour effectuer des requêtes API Google autorisées doivent spécifier les origines JavaScript autorisées. Les origines identifient les domaines à partir desquels votre application peut envoyer des requêtes au serveur OAuth 2.0. Ces origines doivent respecter les Règles de validation de Google.

Identifier les niveaux d'accès

Les champs d'application permettent à votre application de demander l'accès aux ressources dont elle a besoin tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils peuvent accorder à votre application. Par conséquent, il peut y avoir une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur.

Avant de commencer à mettre en œuvre l'autorisation OAuth 2.0, nous vous recommandons d'identifier les niveaux d'accès requis pour votre application.

Le document Champs d'application de l'API OAuth 2.0 contient une liste complète des champs d'application que vous pouvez utiliser pour accéder aux API Google.

Obtenir des jetons d'accès OAuth 2.0

La procédure suivante montre comment votre application interagit avec le serveur OAuth 2.0 de Google pour obtenir le consentement d'un utilisateur afin d'exécuter une requête API pour le compte de l'utilisateur. Votre application doit disposer de ce consentement pour pouvoir exécuter une requête API Google nécessitant une autorisation utilisateur.

Étape 1: Configurez l'objet client

Si vous gérez le flux OAuth 2.0 à l'aide de la bibliothèque cliente des API Google pour JavaScript, la première étape consiste à configurer les objets gapi.auth2 et gapi.client. Ces objets permettent à votre application d'obtenir des autorisations utilisateur et d'effectuer des requêtes API autorisées.

L'objet client identifie les champs d'application pour lesquels votre application demande l'autorisation d'accéder. Ces valeurs indiquent l'écran de consentement que Google affiche à l'utilisateur.

Bibliothèque cliente JS

La bibliothèque cliente JavaScript simplifie de nombreux aspects du processus d'autorisation:

  1. Elle crée l'URL de redirection du serveur d'autorisation de Google et fournit une méthode pour rediriger l'utilisateur vers cette URL.
  2. Il gère la redirection de ce serveur vers votre application.
  3. qui permet de valider le jeton d'accès renvoyé par le serveur d'autorisation.
  4. Il stocke le jeton d'accès que le serveur d'autorisation envoie à votre application et le récupère lorsque votre application effectue des appels d'API autorisés.

L'extrait de code ci-dessous est issu de l'exemple complet présenté plus loin dans ce document. Ce code initialise l'objet gapi.client que votre application utilisera plus tard pour effectuer des appels d'API. Une fois cet objet créé, l'objet gapi.auth2, qui permet à votre application de vérifier et de surveiller l'état d'autorisation de l'utilisateur, est également initialisé.

L'appel de gapi.client.init spécifie les champs suivants:

  • Les valeurs apiKey et clientId spécifient les identifiants d'autorisation de votre application. Comme indiqué dans la section Créer des identifiants d'autorisation, ces valeurs peuvent être obtenues dans API Console. Notez que clientId est obligatoire si votre application effectue des requêtes API autorisées. Les applications qui n'envoient que des requêtes non autorisées peuvent simplement spécifier une clé API.
  • Le champ scope spécifie une liste de niveaux d'accès séparés par des espaces, correspondant aux ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google présente à l'utilisateur.

    Dans la mesure du possible, nous vous recommandons de demander à votre application l'accès aux champs d'application des autorisations. En demandant aux utilisateurs d'accéder aux données en contexte via une autorisation incrémentielle, vous aidez les utilisateurs à comprendre plus facilement pourquoi votre application a besoin de cet accès.

  • Le champ discoveryDocs identifie les documents de découverte des API utilisés par votre application. Un document de découverte décrit la surface d'une API, y compris ses schémas de ressources, et la bibliothèque cliente JavaScript s'en sert pour générer des méthodes utilisables par les applications. Dans cet exemple, le code récupère le document de découverte pour la version 3 de l'API Google Drive.

Une fois l'appel gapi.client.init terminé, le code définit la variable GoogleAuth pour identifier l'objet Google Auth. Enfin, le code définit un écouteur qui appelle une fonction lorsque l'état de connexion de l'utilisateur change. (Cette fonction n'est pas définie dans l'extrait.)

var GoogleAuth; // Google Auth object.
function initClient() {
  gapi.client.init({
      'apiKey': 'YOUR_API_KEY',
      'clientId': 'YOUR_CLIENT_ID',
      'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
      'discoveryDocs': ['https://www.googleapis.com/discovery/v1/apis/drive/v3/rest']
  }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);
  });
}

Points de terminaison OAuth 2.0

Si vous accédez directement aux points de terminaison OAuth 2.0, vous pouvez passer à l'étape suivante.

Étape 2: Redirection vers le serveur OAuth 2.0 de Google

Pour demander l'autorisation d'accéder aux données d'un utilisateur, redirigez-le vers le serveur OAuth 2.0 de Google.

Bibliothèque cliente JS

Appelez la méthode GoogleAuth.signIn() pour diriger l'utilisateur vers le serveur d'autorisation de Google.

GoogleAuth.signIn();

Dans la pratique, votre application peut définir une valeur booléenne pour déterminer s'il faut appeler la méthode signIn() avant d'essayer d'effectuer un appel d'API.

L'extrait de code ci-dessous montre comment lancer le parcours d'autorisation utilisateur. Veuillez noter les points suivants concernant l'extrait:

  • L'objet GoogleAuth référencé dans le code est identique à la variable globale définie dans l'extrait de code de l'étape 1.

  • La fonction updateSigninStatus est un écouteur qui écoute les modifications de l'état d'autorisation de l'utilisateur. Son rôle d'écouteur a également été défini dans l'extrait de code de l'étape 1 :
    GoogleAuth.isSignedIn.listen(updateSigninStatus);
  • L'extrait définit deux variables globales supplémentaires:

    • isAuthorized est une variable booléenne indiquant si l'utilisateur est déjà connecté. Cette valeur peut être définie lors du chargement de l'application et mise à jour si l'utilisateur se connecte ou se déconnecte de l'application.

      Dans cet extrait, la fonction sendAuthorizedApiRequest vérifie la valeur de la variable pour déterminer si l'application doit tenter d'exécuter une requête API nécessitant une autorisation ou inviter l'utilisateur à autoriser l'application.

    • currentApiRequest est un objet qui stocke les détails de la dernière requête de l'API que l'utilisateur a tentée. La valeur de l'objet est définie lorsque l'application appelle la fonction sendAuthorizedApiRequest.

      Si l'utilisateur a autorisé l'application, la requête est exécutée immédiatement. Sinon, la fonction redirige l'utilisateur pour se connecter. Une fois l'utilisateur connecté, la fonction updateSignInStatus appelle sendAuthorizedApiRequest et transmet la même requête que la tentative d'autorisation.

var isAuthorized;
var currentApiRequest;

/**
 * Store the request details. Then check to determine whether the user
 * has authorized the application.
 *   - If the user has granted access, make the API request.
 *   - If the user has not granted access, initiate the sign-in flow.
 */
function sendAuthorizedApiRequest(requestDetails) {
  currentApiRequest = requestDetails;
  if (isAuthorized) {
    // Make API request
    // gapi.client.request(requestDetails)

    // Reset currentApiRequest variable.
    currentApiRequest = {};
  } else {
    GoogleAuth.signIn();
  }
}

/**
 * Listener called when user completes auth flow. If the currentApiRequest
 * variable is set, then the user was prompted to authorize the application
 * before the request executed. In that case, proceed with that API request.
 */
function updateSigninStatus(isSignedIn) {
  if (isSignedIn) {
    isAuthorized = true;
    if (currentApiRequest) {
      sendAuthorizedApiRequest(currentApiRequest);
    }
  } else {
    isAuthorized = false;
  }
}

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:

Paramètres
client_id Obligatoire

ID client de votre application. Vous pouvez trouver cette valeur dans le API ConsoleCredentials page.

redirect_uri Obligatoire

Détermine où le serveur d'API redirige l'utilisateur une fois que l'utilisateur a terminé le parcours d'autorisation. La valeur doit correspondre exactement à l'un des URI de redirection autorisés pour le client OAuth 2.0, que vous avez configurés dans API ConsoleCredentials page. Si cette valeur ne correspond pas à un URI de redirection autorisé pour le client_id fourni, une erreur redirect_uri_mismatch est renvoyée.

Notez que le schéma http ou https, la casse et la barre oblique finale ('/') doivent tous correspondre.

response_type Obligatoire

Les applications JavaScript doivent définir la valeur du paramètre sur token. Cette valeur indique au serveur d'autorisation Google de renvoyer le jeton d'accès en tant que paire name=value dans l'identifiant de fragment de l'URI (#) vers lequel l'utilisateur est redirigé une fois le processus d'autorisation terminé.

scope Obligatoire

Liste de champs d'application délimitée par des espaces qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs indiquent l'écran de consentement que Google affiche à l'utilisateur.

Les champs d'application permettent à votre application de demander l'accès aux ressources dont elle a besoin tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils peuvent accorder à votre application. Par conséquent, il existe une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur.

Dans la mesure du possible, nous vous recommandons de demander à votre application d'accéder aux champs d'application des autorisations. En demandant aux utilisateurs d'accéder aux données utilisateur en contexte via une autorisation incrémentielle, vous les aidez à comprendre plus facilement pourquoi votre application a besoin d'accéder à ces données.

state Approche conseillée

Spécifie toute valeur de chaîne que votre application utilise pour maintenir l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation. Le serveur renvoie la valeur exacte que vous envoyez sous forme de paire name=value dans l'identifiant de fragment d'URL (#) de redirect_uri, après que l'utilisateur a autorisé ou refusé la demande d'accès de votre application.

Vous pouvez utiliser ce paramètre à diverses fins, par exemple pour rediriger l'utilisateur vers la ressource appropriée de votre application, pour envoyer des nonces et pour atténuer la falsification de requêtes intersites. Étant donné que la valeur redirect_uri peut être devinée, l'utilisation d'une valeur state peut renforcer l'assurance qu'une connexion entrante est le résultat d'une requête d'authentification. Si vous générez une chaîne aléatoire ou encodez le hachage d'un cookie ou d'une autre valeur qui capture l'état du client, vous pouvez valider la réponse pour vous assurer que la requête et la réponse proviennent du même navigateur, ce qui offre une protection contre les attaques telles que la falsification de requêtes intersites. Consultez la documentation d'OpenID Connect pour découvrir comment créer et confirmer un jeton state.

include_granted_scopes Facultatif

Permet aux applications d'utiliser une autorisation incrémentielle pour demander l'accès à des niveaux d'accès supplémentaires en contexte. Si vous définissez la valeur de ce paramètre sur true et que la demande d'autorisation est accordée, le nouveau jeton d'accès couvre également tous les champs d'application auxquels l'utilisateur a précédemment accordé l'accès à l'application. Consultez la section sur l'autorisation incrémentielle pour obtenir des exemples.

login_hint Facultatif

Si votre application sait quel utilisateur tente d'authentifier, elle peut utiliser ce paramètre pour fournir une indication au serveur Google Authentication. Le serveur utilise l'indice pour simplifier le flux de connexion en préremplissant le champ d'adresse e-mail dans le formulaire de connexion ou en sélectionnant la session de connexion multicompte appropriée.

Définissez la valeur du paramètre sur une adresse e-mail ou un identifiant sub, ce qui équivaut à l'identifiant Google de l'utilisateur.

prompt Facultatif

Liste d'invites séparées par un espace et sensible à la casse, destinées à présenter l'utilisateur. Si vous ne spécifiez pas ce paramètre, l'utilisateur n'est invité que la première fois que votre projet demande l'accès. Pour en savoir plus, consultez la section Demander le nouveau consentement.

Les valeurs possibles sont les suivantes :

none N'affichez aucun écran d'authentification ou d'autorisation. Ne doit pas être spécifié avec d'autres valeurs.
consent Demander l'autorisation à l'utilisateur
select_account Invitez l'utilisateur à sélectionner un compte.

Exemple de redirection vers le serveur d'autorisation de Google

Un exemple d'URL est affiché ci-dessous, avec des sauts de ligne et des espaces pour les rendre plus lisibles.

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 créé l'URL de la requête, redirigez-le vers lui.

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. Comme ce point de terminaison OAuth 2.0 n'est pas compatible avec le partage de ressources multi-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();
}

Étape 3: Google demande l'autorisation à l'utilisateur

Dans cette étape, l'utilisateur décide d'accorder ou non l'accès à votre application. À ce stade, Google affiche une fenêtre de consentement indiquant le nom de votre application et les services d'API Google auxquels elle demande l'autorisation d'accéder avec les identifiants d'autorisation de l'utilisateur, ainsi qu'un résumé des champs d'application à accorder. L'utilisateur peut ensuite accepter d'accorder l'accès à un ou plusieurs niveaux d'accès demandés par votre application ou refuser la demande.

À ce stade, votre application n'a rien à faire, car elle attend la réponse du serveur OAuth 2.0 de Google indiquant si un accès a été accordé. Cette réponse est expliquée à l'étape suivante.

Erreurs

Les requêtes envoyées au point de terminaison d'autorisation OAuth 2.0 de Google peuvent afficher des messages d'erreur visibles par les utilisateurs au lieu des flux d'authentification et d'autorisation attendus. Les codes d'erreur courants et les solutions suggérées sont répertoriés ci-dessous.

admin_policy_enforced

Le compte Google ne peut pas autoriser un ou plusieurs niveaux d'accès demandés en raison des règles de leur administrateur Google Workspace. Pour savoir comment un administrateur peut restreindre l'accès à tous les champs d'application ou les niveaux d'accès sensibles et restreints jusqu'à ce que l'accès soit explicitement accordé à votre ID client OAuth, consultez l'article d'aide destiné aux administrateurs Google Workspace Contrôler les applications tierces et les données internes ayant accès aux données Google Workspace.

disallowed_useragent

Le point de terminaison de l'autorisation est affiché dans un user-agent intégré interdit par les règles OAuth 2.0 de Google.

Android

Les développeurs Android peuvent rencontrer ce message d'erreur lorsqu'ils ouvrent des demandes d'autorisation dans android.webkit.WebView. Les développeurs doivent utiliser des bibliothèques Android telles que Google Sign-In pour Android ou OpenID Foundation pour AppAuth pour Android.

Les développeurs Web peuvent rencontrer cette erreur lorsqu'une application Android ouvre un lien Web général dans un user-agent intégré et qu'un utilisateur accède au point de terminaison d'autorisation OAuth 2.0 de Google à partir de votre site. Les développeurs doivent autoriser l'ouverture des liens généraux dans le gestionnaire de liens par défaut du système d'exploitation, qui inclut à la fois les gestionnaires Android App Links et l'application par défaut du navigateur. La bibliothèque Android Custom Tabs est également disponible.

iOS

Les développeurs iOS et macOS peuvent rencontrer cette erreur lors de l'ouverture des demandes d'autorisation dans WKWebView. Les développeurs doivent utiliser des bibliothèques iOS comme Google Sign-In pour iOS ou OpenID Foundation pour AppAuth pour iOS.

Les développeurs Web peuvent rencontrer cette erreur lorsqu'une application iOS ou macOS ouvre un lien Web général dans un user-agent intégré, et que l'utilisateur accède au point de terminaison d'autorisation OAuth 2.0 de Google à partir de votre site. Les développeurs doivent autoriser l'ouverture des liens généraux dans le gestionnaire de liens par défaut du système d'exploitation, qui comprend à la fois les gestionnaires Universal Links et l'application de navigateur par défaut. La bibliothèque SFSafariViewController est également une option compatible.

org_internal

L'ID client OAuth dans la requête fait partie d'un projet limitant l'accès aux comptes Google dans une organisation Google Cloud spécifique. Pour en savoir plus sur cette option de configuration, consultez la section Type d'utilisateur de la page "Configurer votre autorisation OAuth"

origin_mismatch

Le schéma, le domaine et/ou le port du code JavaScript à l'origine de la demande d'autorisation peuvent ne pas correspondre à un URI d'origine JavaScript autorisé enregistré pour l'ID client OAuth. Examinez les origines JavaScript autorisées dans Google API ConsoleCredentials page.

redirect_uri_mismatch

Le redirect_uri transmis dans la requête d'autorisation ne correspond pas à un URI de redirection autorisé pour l'ID client OAuth. Examinez les URI de redirection autorisés dans Google API Console Credentials page.

Le schéma, le domaine et/ou le port du code JavaScript à l'origine de la demande d'autorisation peuvent ne pas correspondre à un URI d'origine JavaScript autorisé enregistré pour l'ID client OAuth. Examinez les origines JavaScript autorisées dans Google API Console Credentials page.

Étape 4: Gérez la réponse du serveur OAuth 2.0

Bibliothèque cliente JS

La bibliothèque cliente JavaScript gère la réponse du serveur d'autorisation de Google. Si vous définissez un écouteur pour surveiller les modifications apportées à l'état de connexion de l'utilisateur actuel, cette fonction est appelée lorsque l'utilisateur accorde l'accès demandé à l'application.

Points de terminaison OAuth 2.0

Le serveur OAuth 2.0 envoie une réponse à la requête 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 illustré ci-dessous:

  • Réponse à un 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. 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 en cas 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 dans 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

Une fois le parcours OAuth 2.0 terminé, 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.

Appeler des API Google

Bibliothèque cliente JS

Une fois que votre application a obtenu un jeton d'accès, vous pouvez utiliser la bibliothèque cliente JavaScript pour effectuer des requêtes API au nom de l'utilisateur. La bibliothèque cliente gère le jeton d'accès pour vous, et vous n'avez rien à faire pour l'envoyer dans la requête.

La bibliothèque cliente accepte deux méthodes pour appeler des méthodes d'API. Si vous avez chargé un document de découverte, l'API définit les fonctions spécifiques à une méthode pour vous. Vous pouvez également utiliser la fonction gapi.client.request pour appeler une méthode API. Les deux extraits suivants illustrent ces options pour la méthode about.get de l'API Drive :

// Example 1: Use method-specific function
var request = gapi.client.drive.about.get({'fields': 'user'});

// Execute the API request.
request.execute(function(response) {
  console.log(response);
});


// Example 2: Use gapi.client.request(args) function
var request = gapi.client.request({
  'method': 'GET',
  'path': '/drive/v3/about',
  'params': {'fields': 'user'}
});
// Execute the API request.
request.execute(function(response) {
  console.log(response);
});

Points de terminaison OAuth 2.0

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour appeler des API Google au nom d'un compte utilisateur donné, si le ou les niveaux d'accès requis par l'API vous 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, il est préférable d'utiliser l'en-tête HTTP, car les chaînes de requête sont généralement 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 en consulter la portée sur OAuth 2.0 Playground.

Exemples de requêtes HTTP GET

Un appel vers le point de terminaison drive.files (API Drive Files) à 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 /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 (méthode recommandée):

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

Vous pouvez également sélectionner l'option du 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 le partage de ressources 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 d'assistance 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 le 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);

Exemple complet

Bibliothèque cliente JS

Exemple de code

Cette section contient une démonstration de l'exemple de code qui montre comment se comporte le code dans une application réelle. Une fois celle-ci autorisée, elle sera répertoriée parmi les applications associées à votre compte Google. Cette application est nommée Démonstration d'OAuth 2.0 pour les documents de l'API Google. De même, si vous révoquez l'accès à cette page et l'actualisez, cette application ne sera plus répertoriée.

Notez que cette application demande l'accès au champ d'application https://www.googleapis.com/auth/drive.metadata.readonly. L'accès ne sert qu'à démontrer comment lancer le flux OAuth 2.0 dans une application JavaScript. Cette application n'effectue aucune requête API.

Exemple de code JavaScript

Comme illustré ci-dessus, cet exemple de code concerne une page (une application) qui charge la bibliothèque cliente des API Google pour JavaScript et lance le flux OAuth 2.0. La page affiche l'un des éléments suivants:

  • Un bouton permettant à l'utilisateur de se connecter à l'application. Si l'utilisateur n'a pas déjà autorisé l'application, l'application lance le parcours OAuth 2.0.
  • Deux boutons permettant à l'utilisateur de se déconnecter de l'application ou de révoquer l'accès accordé précédemment

Vous pouvez également révoquer l'accès à l'application sur la page Autorisations de votre compte Google. L'application est répertoriée dans la version de démonstration du protocole OAuth 2.0 pour les documents de l'API Google.

<script>
  var GoogleAuth;
  var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
  function handleClientLoad() {
    // Load the API's client and auth2 modules.
    // Call the initClient function after the modules load.
    gapi.load('client:auth2', initClient);
  }

  function initClient() {
    // In practice, your app can retrieve one or more discovery documents.
    var discoveryUrl = 'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest';

    // Initialize the gapi.client object, which app uses to make API requests.
    // Get API key and client ID from API Console.
    // 'scope' field specifies space-delimited list of access scopes.
    gapi.client.init({
        'apiKey': 'YOUR_API_KEY',
        'clientId': 'YOUR_CLIENT_ID',
        'discoveryDocs': [discoveryUrl],
        'scope': SCOPE
    }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);

      // Handle initial sign-in state. (Determine if user is already signed in.)
      var user = GoogleAuth.currentUser.get();
      setSigninStatus();

      // Call handleAuthClick function when user clicks on
      //      "Sign In/Authorize" button.
      $('#sign-in-or-out-button').click(function() {
        handleAuthClick();
      });
      $('#revoke-access-button').click(function() {
        revokeAccess();
      });
    });
  }

  function handleAuthClick() {
    if (GoogleAuth.isSignedIn.get()) {
      // User is authorized and has clicked "Sign out" button.
      GoogleAuth.signOut();
    } else {
      // User is not signed in. Start Google auth flow.
      GoogleAuth.signIn();
    }
  }

  function revokeAccess() {
    GoogleAuth.disconnect();
  }

  function setSigninStatus() {
    var user = GoogleAuth.currentUser.get();
    var isAuthorized = user.hasGrantedScopes(SCOPE);
    if (isAuthorized) {
      $('#sign-in-or-out-button').html('Sign out');
      $('#revoke-access-button').css('display', 'inline-block');
      $('#auth-status').html('You are currently signed in and have granted ' +
          'access to this app.');
    } else {
      $('#sign-in-or-out-button').html('Sign In/Authorize');
      $('#revoke-access-button').css('display', 'none');
      $('#auth-status').html('You have not authorized this app or you are ' +
          'signed out.');
    }
  }

  function updateSigninStatus() {
    setSigninStatus();
  }
</script>

<button id="sign-in-or-out-button"
        style="margin-left: 25px">Sign In/Authorize</button>
<button id="revoke-access-button"
        style="display: none; margin-left: 25px">Revoke access</button>

<div id="auth-status" style="display: inline; padding-left: 25px"></div><hr>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script async defer src="https://apis.google.com/js/api.js"
        onload="this.onload=function(){};handleClientLoad()"
        onreadystatechange="if (this.readyState === 'complete') this.onload()">
</script>

Points de terminaison OAuth 2.0

Cet exemple de code montre comment effectuer la procédure OAuth 2.0 dans JavaScript sans utiliser la bibliothèque cliente des API Google pour JavaScript. Ce 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 parcours 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 sera répertoriée comme Démonstration d'OAuth 2.0 pour la documentation sur les API Google.

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 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és dans API Console Credentials page. Si cette valeur ne correspond pas à un URI autorisé, vous obtenez une erreur redirect_uri_mismatch. 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';
  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>

Règles de validation de l'origine JavaScript

Google applique les règles de validation suivantes aux origines JavaScript afin de permettre aux développeurs de sécuriser leurs applications. Vos origines JavaScript doivent respecter ces règles. Consultez la section 3 de la documentation RFC 3986 pour obtenir une définition du domaine, de l'hôte et du schéma mentionnés ci-dessous.

Règles de validation
Schéma

Les origines JavaScript doivent utiliser le schéma HTTPS, et non HTTP simple. Les URI Localhost (y compris les URI d'adresse IP de l'hôte local) sont exemptés de cette règle.

Organisateur

Les hôtes ne peuvent pas être des adresses IP brutes. Les adresses IP Localhost ne sont pas concernées par cette règle.

Domaine
  • Les domaines de premier niveau de l'hôte (domaines de premier niveau) doivent appartenir à la liste des suffixes publics.
  • Les domaines hôtes ne peuvent pas être “googleusercontent.com”.
  • Les origines JavaScript ne peuvent pas contenir de domaines raccourcis pour les URL (par exemple, goo.gl), sauf si l'application est propriétaire du domaine.
  • Infos sur l'utilisateur

    Les origines JavaScript ne peuvent pas contenir le sous-composant "infoinfo".

    Chemin d'accès

    Les origines JavaScript ne peuvent pas contenir le composant de chemin.

    Requête

    Les origines JavaScript ne peuvent pas contenir le composant de requête.

    Fragment

    Les origines JavaScript ne peuvent pas contenir le composant de fragment.

    Caractères Les origines JavaScript ne peuvent pas contenir certains caractères, y compris les suivants :
    • Caractères génériques ('*')
    • Caractères ASCII non imprimables
    • Encodages en pourcentage non valides (tout pourcentage d'encodage qui ne respecte pas la forme d'encodage URL en pourcentage suivi de deux chiffres hexadécimaux)
    • Caractères nuls (un caractère NULL encodé, par exemple : %00, %C0%80)

    Autorisation incrémentielle

    Dans le protocole OAuth 2.0, votre application demande l'autorisation d'accéder aux ressources, identifiées par des champs d'application. Il est recommandé d'offrir une expérience utilisateur de manière optimale pour demander une autorisation pour les ressources au moment où vous en avez besoin. Cette fonctionnalité est disponible sur le serveur d'autorisation de Google. Cette fonctionnalité vous permet de demander les champs d'application en fonction des besoins et, si l'utilisateur accorde les autorisations nécessaires, renvoie un code d'autorisation pouvant être échangé contre un jeton contenant tous les champs d'application accordés par l'utilisateur.

    Par exemple, une application qui permet aux utilisateurs d'écouter des titres et de créer des mix peut nécessiter très peu de ressources au moment de la connexion, peut-être rien de plus que le nom de la personne qui se connecte. Toutefois, pour enregistrer un mix terminé, il faudra accéder à leur Google Drive. La plupart des utilisateurs trouveront naturellement que l'accès à Google Drive est demandé uniquement au moment où l'application en a réellement besoin.

    Dans ce cas, au moment de la connexion, l'application peut demander les champs d'application openid et profile pour effectuer une connexion de base, puis demander le champ d'application https://www.googleapis.com/auth/drive.file au moment de la première requête pour enregistrer un mix.

    Les règles suivantes s'appliquent à un jeton d'accès obtenu à partir d'une autorisation incrémentielle:

    • Le jeton peut être utilisé pour accéder aux ressources correspondant à l'une des habilitations déployées dans la nouvelle autorisation combinée.
    • Lorsque vous utilisez le jeton d'actualisation pour obtenir l'autorisation combinée, le jeton d'accès représente l'autorisation combinée et peut être utilisé pour toute valeur scope incluse dans la réponse.
    • L'autorisation combinée inclut tous les niveaux d'accès que l'utilisateur a accordés au projet d'API, même si les subventions ont été demandées auprès de différents clients. Par exemple, si un utilisateur a accordé l'accès à un champ d'application à l'aide d'un client d'ordinateur de bureau, puis à un autre champ d'application à la même application via un client mobile, l'autorisation combinée incluait les deux champs d'application.
    • Si vous révoquez un jeton représentant une autorisation combinée, l'accès à toutes les habilitations de cette autorisation au nom de l'utilisateur associé est révoqué simultanément.

    Les exemples de code ci-dessous indiquent comment ajouter des niveaux d'accès à un jeton d'accès existant. Cette approche permet à votre application d'éviter de gérer plusieurs jetons d'accès.

    Bibliothèque cliente JS

    Pour ajouter des niveaux d'accès à un jeton d'accès existant, appelez la méthode GoogleUser.grant(options). L'objet options identifie les champs d'application supplémentaires auxquels vous souhaitez accorder l'accès.

    // Space-separated list of additional scope(s) you are requesting access to.
    // This code adds read-only access to the user's calendars via the Calendar API.
    var NEW_SCOPES = 'https://www.googleapis.com/auth/calendar.readonly';
    
    // Retrieve the GoogleUser object for the current user.
    var GoogleUser = GoogleAuth.currentUser.get();
    GoogleUser.grant({'scope': NEW_SCOPES});

    Points de terminaison OAuth 2.0

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

    L'extrait de code suivant montre comment procéder. L'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 complet stocke une liste de champs d'application pour laquelle le jeton d'accès est valide en définissant la propriété oauth2-test-params.scope dans le 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 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 (et décrite ultérieurement 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.
    }

    Révoquer un jeton

    Dans certains cas, l'utilisateur peut souhaiter révoquer l'accès accordé à une application. Un utilisateur peut révoquer l'accès dans les paramètres du compte. Pour en savoir plus, consultez la section Supprimer l'accès aux sites et aux applications depuis le site et les applications tiers ayant accès à votre compte.

    Il est également possible pour une application de révoquer par programmation l'accès qui lui est accordé. La révocation programmatique est importante dans les cas où un utilisateur se désabonne, supprime une application ou les ressources d'API requises par une application ont changé de manière significative. En d'autres termes, une partie du processus de suppression peut inclure une requête API pour garantir la suppression des autorisations précédemment accordées à l'application.

    Bibliothèque cliente JS

    Pour révoquer automatiquement un jeton, appelez GoogleAuth.disconnect() :

    GoogleAuth.disconnect();

    Points de terminaison OAuth 2.0

    Pour révoquer automatiquement un jeton, votre application envoie une requête à https://oauth2.googleapis.com/revoke et inclut ce 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 été traitée correctement, le code d'état HTTP de la réponse est 200. En cas d'erreurs, 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 d'origine croisée (CORS), le code crée un formulaire et l'envoie dans le 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();
    }