Google s'engage à promouvoir l'équité raciale pour les communautés noires. Regardez comment.

OAuth 2.0 pour les applications Web côté client

Ce document explique comment implémenter 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 de stocker des fichiers dans leurs Google Drives.

Ce flux OAuth 2.0 est appelé le flux de subvention implicite. Il est conçu pour les applications qui accèdent aux API uniquement lorsque l'utilisateur est présent sur 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 API requis par l'application. Vous pouvez ouvrir l'URL dans la fenêtre actuelle du navigateur ou dans une fenêtre contextuelle. L'utilisateur peut s'authentifier auprès de Google et accorder les autorisations demandées. Google redirige ensuite l'utilisateur vers votre application. La redirection comprend un jeton d'accès, que votre application vérifie et utilise ensuite pour effectuer des demandes d'API.

Conditions préalables

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 le Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Le API Library répertorie toutes les API disponibles, regroupées par famille de produits et de la popularité. Si l'API que vous souhaitez activer n'est pas visible dans la liste, utilisez la recherche pour le trouver, ou cliquez sur Afficher tout dans la famille de produits auquel il 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 informations d'identification pour votre projet. Vos applications peuvent ensuite utiliser les informations d'identification 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 informations d' identification> OAuth ID client.
  3. Sélectionnez le type d'application de l' application Web.
  4. Complétez le formulaire. Les applications qui utilisent JavaScript pour faire des demandes API Google autorisées doit préciser l' origine 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 étendues d'accès

Les étendues permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin tout en permettant également aux utilisateurs de contrôler la quantité d'accès qu'ils accordent à votre application. Ainsi, il peut exister une relation inverse entre le nombre de portées demandées et la probabilité d'obtenir le consentement de l'utilisateur.

Avant de commencer à implémenter l'autorisation OAuth 2.0, nous vous recommandons d'identifier les étendues auxquelles votre application aura besoin d'une autorisation pour accéder.

L' API OAuth 2.0 Scopes document contient une liste complète des champs que vous pouvez utiliser pour accéder à des API Google.

Obtention de jetons d'accès OAuth 2.0

Les étapes suivantes montrent comment votre application interagit avec le serveur OAuth 2.0 de Google pour obtenir le consentement d'un utilisateur afin d'effectuer une demande d'API au nom de l'utilisateur. Votre application doit disposer de ce consentement avant de pouvoir exécuter une requête d'API Google nécessitant l'autorisation de l'utilisateur.

Étape 1 : Configurer l'objet client

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

L'objet client identifie les étendues auxquelles votre application demande l'autorisation d'accéder. Ces valeurs informent 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. Il crée l'URL de redirection pour le serveur d'autorisation de Google et fournit une méthode pour diriger l'utilisateur vers cette URL.
  2. Il gère la redirection de ce serveur vers votre application.
  3. Il valide 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 par la suite des appels d'API autorisés.

L'extrait de code ci - dessous est un extrait de l' exemple complet plus tard dans ce document. Ce code initialise le gapi.client objet, que votre application utilisera plus tard pour faire des appels API. Lorsque l'objet est créé, le gapi.auth2 objet, que votre application utilise pour vérifier et surveiller l'état d'autorisation de l'utilisateur, est également initialisé.

L'appel à gapi.client.init précise les champs suivants:

  • Les apiKey et clientId valeurs spécifient les informations d'identification d'autorisation de votre application. Comme indiqué dans la création de API Consolepouvoirs d'autorisation section, ces valeurs peuvent être obtenues dans le API Console. Notez que le clientId est nécessaire si votre application effectue des requêtes API autorisées. Les applications qui ne font que des demandes non autorisées peuvent simplement spécifier une clé API.
  • Le scope champ spécifie une liste de l' espace délimité par l' accès étendues qui correspondent aux ressources que votre application peut accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google affiche à l'utilisateur.

    Nous recommandons que votre application demande l'accès aux étendues d'autorisation en contexte dans la mesure du possible. En demandant l' accès aux données de l' utilisateur dans le contexte, par autorisation supplémentaire , vous aider les utilisateurs à comprendre plus facilement pourquoi a besoin de votre demande l'accès qu'il demande.

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

Après les gapi.client.init finalise l' appel, le code définit la GoogleAuth variable 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 l'utilisateur vers le serveur OAuth 2.0 de Google.

Bibliothèque cliente JS

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

GoogleAuth.signIn();

Dans la pratique, l' application peut définir une valeur booléenne pour déterminer si d'appeler la signIn() méthode avant de tenter de faire un appel d'API.

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

  • Le GoogleAuth objet référencé dans le code est le même que la variable globale définie dans l'extrait de code dans l' étape 1 .

  • La updateSigninStatus fonction est un auditeur qui écoute les changements apportés au statut d'autorisation de l'utilisateur. Son rôle en tant qu'auditeur a également été défini dans l'extrait de code à l' étape 1:
    GoogleAuth.isSignedIn.listen(updateSigninStatus);
  • L'extrait définit deux variables globales supplémentaires :

    • isAuthorized est une variable booléenne qui indique si l'utilisateur est déjà connecté. Cette valeur peut être réglée lors du chargement d'applications et mises à jour si l'utilisateur se connecte dans ou hors de l'application.

      Dans cet extrait, la sendAuthorizedApiRequest fonction vérifie la valeur de la variable pour déterminer si l'application doit tenter une demande d'API qui requiert une autorisation ou demander à l'utilisateur d'autoriser l'application.

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

      Si l'utilisateur a autorisé l'application, la demande est exécutée immédiatement. Dans le cas contraire, la fonction redirige l'utilisateur de se connecter. Après les signes d' un utilisateur, la updateSignInStatus fonction appelle sendAuthorizedApiRequest , en passant dans la même requête qui a été tentée avant que le flux d'autorisation a commencé.

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érer une URL pour accéder à la demande du point de terminaison OAuth 2.0 de Google à 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 prend en charge les paramètres de chaîne de requête suivants pour les applications de serveur Web :

Paramètres
client_id Obligatoire

L'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 flux d'autorisation. La valeur doit correspondre exactement à un des URIs de redirection autorisés pour le client OAuth 2.0, qui vous avez configuré dans votre client de API ConsoleCredentials page. Si cette valeur ne correspond pas à un URI redirect autorisé pour la condition client_id vous obtiendrez une redirect_uri_mismatch erreur.

Notez que le http ou https système, cas et slash ( « / ») doit tout le match.

response_type Obligatoire

Applications JavaScript doivent définir la valeur du paramètre à token . Cette valeur indique au serveur d' autorisation Google de renvoyer l'jeton d' accès comme name=value paire dans l'identifiant de fragment de l'URI ( # ) auquel l'utilisateur est redirigé après avoir terminé le processus d'autorisation.

scope Obligatoire

Une liste d'étendues délimitées par des espaces qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google affiche à l'utilisateur.

Les étendues permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin tout en permettant également aux utilisateurs de contrôler la quantité d'accès qu'ils accordent à votre application. Ainsi, il existe une relation inverse entre le nombre de portées demandées et la probabilité d'obtenir le consentement de l'utilisateur.

Nous recommandons que votre application demande l'accès aux étendues d'autorisation en contexte dans la mesure du possible. En demandant l' accès aux données de l' utilisateur dans le contexte, par autorisation supplémentaire , vous aider les utilisateurs à comprendre plus facilement pourquoi a besoin de votre demande l'accès qu'il demande.

state conseillé

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

Vous pouvez utiliser ce paramètre à plusieurs fins, telles que diriger l'utilisateur vers la ressource appropriée dans votre application, envoyer des nonces et atténuer la falsification des demandes intersites. Étant donné que votre redirect_uri peut être deviné, en utilisant un state valeur peut augmenter votre assurance qu'une connexion entrante est le résultat d'une demande d'authentification. Si vous générez une chaîne aléatoire ou encodez le hachage d'un cookie ou une autre valeur qui capture l'état du client, vous pouvez valider la réponse pour vous assurer en outre que la demande et la réponse proviennent du même navigateur, offrant une protection contre les attaques telles que les attaques intersites. demande de contrefaçon. Voir la OpenID Connect documentation pour un exemple de la façon de créer et de confirmer un state jeton.

include_granted_scopes Optionnel

Permet aux applications d'utiliser une autorisation incrémentielle pour demander l'accès à des étendues supplémentaires en contexte. Si vous définissez cette valeur du paramètre à true et la demande d'autorisation est accordée, le nouveau jeton d'accès couvrira également tous les champs d' application auquel l'utilisateur avait précédemment accordé l'accès aux applications. Voir l' autorisation supplémentaire section des exemples.

login_hint Optionnel

Si votre application sait quel utilisateur essaie de s'authentifier, elle peut utiliser ce paramètre pour fournir un indice au serveur d'authentification Google. Le serveur utilise l'indice pour simplifier le flux de connexion, soit en préremplissant le champ e-mail dans le formulaire de connexion, soit en sélectionnant la session multi-connexion appropriée.

Réglez la valeur du paramètre à une adresse e - mail ou sub identifiant, ce qui équivaut à Google ID de l'utilisateur.

prompt Optionnel

Une liste d'invites, délimitée par des espaces et sensible à la casse, à présenter à l'utilisateur. Si vous ne spécifiez pas ce paramètre, l'utilisateur sera invité uniquement la première fois que votre projet demande l'accès. Voir Incitation un nouveau consentement pour plus d' informations.

Les valeurs possibles sont :

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

Exemple de redirection vers le serveur d'autorisation de Google

Un exemple d'URL est présenté ci-dessous, avec des sauts de ligne et des espaces pour plus de 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

Après avoir créé l'URL de demande, 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 ne prend pas en charge le partage de ressources d'origine croisée (CORS), l'extrait de code crée un formulaire qui ouvre la demande à 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 invite l'utilisateur à donner son consentement

Dans cette étape, l'utilisateur décide s'il accorde à votre application l'accès demandé. À ce stade, Google affiche une fenêtre de consentement qui indique le nom de votre application et les services d'API Google auxquels il demande l'autorisation d'accéder avec les identifiants d'autorisation de l'utilisateur et un résumé des étendues d'accès à accorder. L'utilisateur peut alors consentir à accorder l'accès à un ou plusieurs périmètres demandés par votre application ou refuser la demande.

Votre application n'a rien à faire à ce stade 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.

les erreurs

Les demandes adressées au point de terminaison d'autorisation OAuth 2.0 de Google peuvent afficher des messages d'erreur destinés à l'utilisateur au lieu des flux d'authentification et d'autorisation attendus. Les codes d'erreur courants et les résolutions suggérées sont répertoriés ci-dessous.

admin_policy_enforced

Le compte Google n'est pas en mesure d'autoriser un ou plusieurs champs d'application demandés en raison des politiques de son administrateur Google Workspace. Voir l'article d'aide Administrateur Google Espace de travail de contrôle qui tiers et des applications internes accéder aux données Google espace de travail pour plus d' informations sur la façon dont un administrateur peut restreindre l' accès à toutes les étendues ou les domaines sensibles et restreints jusqu'à ce que l' accès est explicitement accordé à votre ID client OAuth.

disallowed_useragent

Le point final d'autorisation est affiché à l' intérieur d' un agent utilisateur intégré rejeté par Google Politiques OAuth 2.0 .

Android

Les développeurs Android peuvent rencontrer ce message d'erreur lors de l' ouverture des demandes d'autorisation dansandroid.webkit.WebView . Les développeurs doivent plutôt utiliser les bibliothèques Android telles que Google Sign-In pour Android ou de la Fondation OpenID AppAuth pour Android .

Les développeurs Web peuvent rencontrer cette erreur lorsqu'une application Android ouvre un lien Web général dans un agent utilisateur 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 devraient permettre des liens généraux d'ouvrir dans le gestionnaire de liaison par défaut du système d'exploitation, qui comprend les applications Android Links gestionnaires ou l'application du navigateur par défaut. Les onglets personnalisés Android bibliothèque est également une option prise en charge.

iOS

les développeurs iOS et Mac OS peuvent rencontrer cette erreur lors de l' ouverture des demandes d'autorisation dansWKWebView . Les développeurs doivent utiliser à la place des bibliothèques iOS tels que Google Sign-In pour iOS ou de la Fondation OpenID 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 agent utilisateur 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 devraient permettre des liens généraux d'ouvrir dans le gestionnaire de liaison par défaut du système d'exploitation, qui comprend les liens Universal gestionnaires ou l'application du navigateur par défaut. LaSFSafariViewController bibliothèque est également une option prise en charge.

org_internal

Le client OAuth ID dans la demande fait partie d'un projet limitant l' accès aux comptes Google dans un spécifique Google Organisation nuage . Pour plus d' informations sur cette option de configuration voir le type utilisateur section dans la Configuration de votre écran consentement OAuth article d'aide.

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. Origines Revue JavaScript autorisée dans le Google API ConsoleCredentials page.

redirect_uri_mismatch

Le redirect_uri passé dans la demande d'autorisation ne correspond pas à une redirection autorisé URI pour l'ID client OAuth. Examen autorisé URIs Rediriger à la 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. Origines Revue JavaScript autorisée dans le Google API Console Credentials page.

Étape 4 : gérer 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 de 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 au redirect_uri spécifié dans votre demande d' accès jeton.

Si l'utilisateur approuve la demande, la réponse contient un jeton d'accès. Si l'utilisateur n'approuve pas la demande, 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 de jeton d'accès :

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

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

  • Une réponse d'erreur:
    https://oauth2.example.com/callback#error=access_denied

Exemple de réponse de 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

Après avoir terminé le flux OAuth 2.0, vous serez redirigé vers http://localhost/oauth2callback . Cette URL donnera une 404 NOT FOUND erreur à moins que votre machine locale se servir d' 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.

Appel 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 demandes d'API au nom de l'utilisateur. La bibliothèque cliente gère le jeton d'accès pour vous et vous n'avez rien de spécial à faire pour l'envoyer dans la demande.

La bibliothèque cliente prend en charge deux manières d'appeler des méthodes API. Si vous avez chargé un document de découverte, l'API définira pour vous des fonctions spécifiques à la méthode. Vous pouvez également utiliser la gapi.client.request fonction pour appeler une méthode API. Les deux extraits montrent ces options suivantes pour l'API d' entraînement about.get méthode.

// 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 utiliser le jeton pour passer des appels à une API Google au nom d'un compte utilisateur donné si la ou les étendues d'accès requises par l'API ont été accordées. Pour ce faire, ajoutez le jeton d' accès dans une requête à l'API en incluant soit un access_token paramètre de requête ou une Authorization en- tête HTTP Bearer valeur. Lorsque cela 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 client pour configurer vos appels aux API Google (par exemple, lorsque l' appel de l'API des fichiers Drive ).

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

Exemples HTTP GET

Un appel au drive.files point final (l'API des fichiers Drive) en utilisant l' Authorization: Bearer - tête HTTP pourrait ressembler à ce qui 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 à la même API pour l'utilisateur authentifié à l' aide du access_token paramètre de chaîne de requête:

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

curl exemples

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

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

Ou, alternativement, l'option de 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 ne l' utilisez la bibliothèque client, les CORS soutiennent Guide dans la documentation de cette bibliothèque va probablement vous aider à mieux comprendre ces demandes.

Dans cet extrait de code, la access_token variable représente le jeton que vous avez obtenu pour faire des demandes de l' API pour le compte de l'utilisateur autorisé. L' exemple complet montre comment stocker ce jeton dans le stockage local du navigateur et le récupérer lors de la demande d' une 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 démonstration de code

Cette section contient une démonstration fonctionnelle de l'exemple de code qui suit pour montrer comment le code se comporte dans une application réelle. Une fois que vous autorisez l'application, il sera répertorié parmi les applications connectées à votre compte Google . L'application est nommé OAuth 2.0 Demo pour Google Docs API. De même, si vous révoquez l'accès et actualisez cette page, cette application ne sera plus répertoriée.

Notez que cette application demande l' accès à la https://www.googleapis.com/auth/drive.metadata.readonly portée. L'accès est demandé uniquement pour montrer comment lancer le flux OAuth 2.0 dans une application JavaScript. Cette application ne fait aucune demande d'API.

Exemple de code JavaScript

Comme indiqué 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 soit :

  • Un bouton qui permet à l'utilisateur de se connecter à l'application. Si l'utilisateur n'a pas préalablement autorisé l'application, l'application lance le flux OAuth 2.0.
  • Deux boutons qui permettent à l'utilisateur de se déconnecter de l'application ou de révoquer l'accès précédemment accordé à l'application. Si vous vous déconnectez d'une application, vous n'avez pas révoqué l'accès accordé à l'application. Vous devrez vous reconnecter avant que l'application puisse effectuer d'autres demandes autorisées en votre nom, mais vous n'aurez pas à accorder à nouveau l'accès la prochaine fois que vous utiliserez l'application. Cependant, si vous révoquez l'accès, vous devez à nouveau accorder l'accès.

Vous pouvez également révoquer l' accès à l'application par la Permission page de votre compte Google. L'application est répertorié comme OAuth 2.0 Demo pour Google Docs API.

<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 terminer le flux OAuth 2.0 en JavaScript sans utiliser la bibliothèque cliente des API Google pour JavaScript. Le code est pour une page HTML qui affiche un bouton pour 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 API dans le stockage local de votre navigateur. Si tel est le cas, il exécute la requête API. Sinon, il initie le flux OAuth 2.0.

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

  1. Il dirige l'utilisateur vers le serveur OAuth 2.0 de Google, qui demande l' accès à la https://www.googleapis.com/auth/drive.metadata.readonly portée.
  2. Après avoir accordé (ou refusé) l'accès à une ou plusieurs étendues demandées, 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 demande d'API.

    La demande de l' API appelle l'API lecteur about.get méthode pour récupérer des informations sur le compte Google Drive de l'utilisateur autorisé.

  4. Si la requête s'exécute avec succès, 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 par la Permission page de votre compte Google. L'application sera répertorié comme OAuth 2.0 Demo pour Google Docs API.

Pour exécuter ce code localement, vous devez valeurs pour les YOUR_CLIENT_ID et YOUR_REDIRECT_URI variables qui correspondent à vos informations d'identification d'autorisation . La YOUR_REDIRECT_URI variable doit être réglé sur la même URL où la page est servi. La valeur doit correspondre exactement à un des URIs de redirection autorisés pour le client OAuth 2.0, qui vous avez configuré dans le API Console Credentials page. Si cette valeur ne correspond pas à un URI autorisé, vous obtiendrez une redirect_uri_mismatch erreur. Votre projet doit également avoir permis à l'API appropriée pour cette demande.

<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 d'origine JavaScript

Google applique les règles de validation suivantes aux origines JavaScript afin d'aider les développeurs à sécuriser leurs applications. Vos origines JavaScript doivent respecter ces règles. Voir la section RFC 3986 3 pour la définition du domaine, hôte et système, mentionné ci - dessous.

Règles de validation
Schème

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

Hôte

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

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

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

    Chemin

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

    Mettre en doute

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

    Fragment

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

    Personnages Les origines JavaScript ne peuvent pas contenir certains caractères, notamment :
    • Les caractères génériques ( '*' )
    • Caractères ASCII non imprimables
    • Encodages de pourcentage non valides (tout codage de pourcentage qui ne suit pas la forme de codage d'URL d'un signe de pourcentage suivi de deux chiffres hexadécimaux)
    • Caractères nuls (un caractère codé NULL, par exemple, %00 , %C0%80 )

    Autorisation incrémentielle

    Dans le protocole OAuth 2.0, votre application demande l'autorisation d'accéder aux ressources, qui sont identifiées par des étendues. Il est considéré comme une meilleure pratique d'expérience utilisateur de demander une autorisation pour les ressources au moment où vous en avez besoin. Pour permettre cette pratique, le serveur d'autorisation de Google prend en charge l'autorisation incrémentielle. Cette fonctionnalité vous permet de demander des étendues selon leurs besoins et, si l'utilisateur accorde l'autorisation pour la nouvelle étendue, renvoie un code d'autorisation qui peut être échangé contre un jeton contenant toutes les étendues que l'utilisateur a accordées au projet.

    Par exemple, une application qui permet aux utilisateurs d'échantillonner des morceaux de musique et de créer des mixages 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. Cependant, l'enregistrement d'un mixage terminé nécessiterait l'accès à son Google Drive. . La plupart des gens trouveraient naturel qu'on leur demande seulement l'accès à leur Google Drive au moment où l'application en avait réellement besoin.

    Dans ce cas, lors de l' inscription dans le temps l'application peut demander aux openid et le profile des étendues d'effectuer de connexion de base, puis demander plus tard , la https://www.googleapis.com/auth/drive.file portée au moment de la première demande d'enregistrement d'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 étendues intégrées à la nouvelle autorisation combinée.
    • Lorsque vous utilisez l'actualisation du jeton pour l'autorisation combinée pour obtenir un jeton d'accès, l'accès symbolique représente l'autorisation combinée et peut être utilisé pour l' une des scope valeurs incluses dans la réponse.
    • L'autorisation combinée inclut toutes les étendues que l'utilisateur a accordées au projet d'API, même si les autorisations ont été demandées à différents clients. Par exemple, si un utilisateur accordait l'accès à une étendue à l'aide du client de bureau d'une application, puis accordait une autre étendue à la même application via un client mobile, l'autorisation combinée inclurait les deux étendues.
    • Si vous révoquez un jeton qui représente une autorisation combinée, l'accès à toutes les étendues de cette autorisation au nom de l'utilisateur associé est révoqué simultanément.

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

    Bibliothèque cliente JS

    Pour ajouter des étendues à un jeton d'accès existant, appelez le GoogleUser.grant(options) méthode. Les options de objet 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 étendues à un jeton d'accès existant, inclure le include_granted_scopes paramètre dans votre demande au serveur OAuth 2.0 de Google .

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

    L'extrait de code compare les étendues pour lesquelles le jeton d'accès est valide à l'étendue que vous souhaitez utiliser pour une requête particulière. Si le jeton d'accès ne couvre pas cette étendue, le flux OAuth 2.0 démarre. Ici, la oauth2SignIn fonction est le même que celui qui a été fourni à l' étape 2 (et qui est 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.
    }

    Révoquer un jeton

    Dans certains cas, un utilisateur peut souhaiter révoquer l'accès donné à une application. Un utilisateur peut révoquer l' accès en visitant les paramètres du compte . Voir la section d'accès au site Supprimer ou l' application des sites tiers et des applications avec accès à votre compte document de support pour plus d' informations.

    Il est également possible pour une application de révoquer par programmation l'accès qui lui est donné. La révocation par programmation est importante dans les cas où un utilisateur se désabonne, supprime une application ou les ressources API requises par une application ont considérablement changé. En d'autres termes, une partie du processus de suppression peut inclure une demande d'API pour s'assurer que les autorisations précédemment accordées à l'application sont supprimées.

    Bibliothèque cliente JS

    Pour révoquer un programme jeton, appel GoogleAuth.disconnect() :

    GoogleAuth.disconnect();

    Points de terminaison OAuth 2.0

    Pour révoquer un programme jeton, votre application fait une demande de https://oauth2.googleapis.com/revoke et comprend le jeton comme paramètre:

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

    The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

    If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

    The following JavaScript snippet shows how to revoke a token in JavaScript without using the Google APIs Client Library for JavaScript. Since the Google's OAuth 2.0 endpoint for revoking tokens does not support Cross-origin Resource Sharing (CORS), the code creates a form and submits the form to the endpoint rather than using the XMLHttpRequest() method to post the request.

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