Utiliser OAuth 2.0 pour accéder aux API Google

Les API Google utilisent le protocole OAuth 2.0 pour l'authentification et l'autorisation. Google accepte les scénarios OAuth 2.0 courants, tels que ceux pour les applications de serveur Web, côté client, installées et dont l'entrée est limitée.

Pour commencer, obtenez les identifiants client OAuth 2.0 à partir de Google API Console. Votre application cliente demande ensuite un jeton d'accès au serveur d'autorisation Google, en extrait un jeton dans la réponse et l'envoie à l'API Google à laquelle vous souhaitez accéder. Pour obtenir une démonstration interactive de l'utilisation du protocole OAuth 2.0 avec Google (et de l'utilisation de vos propres identifiants client), testez OAuth 2.0 Playground.

Cette page présente les scénarios d'autorisation OAuth 2.0 compatibles avec Google et fournit des liens vers des informations plus détaillées. Pour savoir comment utiliser OAuth 2.0 pour l'authentification, consultez OpenID Connect.

Procédure générale

Toutes les applications suivent un schéma de base lorsqu'elles accèdent à une API Google à l'aide du protocole OAuth 2.0. De manière générale, vous devez suivre cinq étapes:

1. Obtenez les identifiants OAuth 2.0 à partir de Google API Console.

Accédez à Google API Console pour obtenir des identifiants OAuth 2.0 (tels qu'un ID et un code secret client) connus de Google et de votre application. L'ensemble de valeurs dépend du type d'application que vous créez. Par exemple, une application JavaScript ne nécessite pas de secret, contrairement à une application de serveur Web.

2. Obtenez un jeton d'accès auprès du serveur d'autorisation de Google.

Pour que votre application puisse accéder à des données privées à l'aide d'une API Google, elle doit obtenir un jeton d'accès accordant l'accès à cette API. Un même jeton d'accès peut accorder différents niveaux d'accès à plusieurs API. Un paramètre de variable appelé scope contrôle l'ensemble des ressources et des opérations autorisées par un jeton d'accès. Pendant la requête de jeton d'accès, votre application envoie une ou plusieurs valeurs dans le paramètre scope.

Il existe plusieurs façons d'envoyer cette requête, qui varient selon le type d'application que vous créez. Par exemple, une application JavaScript peut demander un jeton d'accès à l'aide d'une redirection de navigateur vers Google, tandis qu'une application installée sur un appareil sans navigateur utilise des requêtes de service Web.

Certaines requêtes nécessitent une étape d'authentification où l'utilisateur se connecte avec son compte Google. Une fois connecté, l'utilisateur est invité à indiquer s'il souhaite accorder une ou plusieurs autorisations demandées par votre application. Ce processus est appelé consentement de l'utilisateur.

Si l'utilisateur accorde au moins une autorisation, le serveur d'autorisation Google envoie à votre application un jeton d'accès (ou un code d'autorisation permettant à votre application d'obtenir un jeton d'accès) et une liste des champs d'application d'accès accordés par ce jeton. Si l'utilisateur n'accorde pas l'autorisation, le serveur renvoie une erreur.

En règle générale, il est recommandé de demander des champs d'application de manière incrémentielle, au moment de l'accès, plutôt que de les envoyer à l'avance. Par exemple, une application qui souhaite enregistrer un événement dans un agenda ne doit pas demander l'accès à Google Agenda tant que l'utilisateur n'a pas appuyé sur le bouton "Ajouter à l'agenda". Reportez-vous à la section Autorisation incrémentielle.

3. Examiner les niveaux d'accès accordés par l'utilisateur

Comparez les niveaux d'accès inclus dans la réponse du jeton d'accès avec ceux qui sont requis pour accéder aux fonctionnalités de votre application qui dépendent de l'accès à une API Google associée. Désactivez toutes les fonctionnalités de votre application qui ne pourraient pas fonctionner sans accès à l'API associée.

Le champ d'application inclus dans votre requête peut ne pas correspondre à celui inclus dans votre réponse, même si l'utilisateur a accordé tous les champs d'application demandés. Reportez-vous à la documentation de chaque API Google pour connaître les niveaux d'accès requis. Une API peut mapper plusieurs valeurs de chaîne de champ d'application sur un seul champ d'application d'accès, en renvoyant la même chaîne de champ d'application pour toutes les valeurs autorisées dans la requête. Exemple: l'API Google People peut renvoyer le champ d'application https://www.googleapis.com/auth/contacts lorsqu'une application demande à un utilisateur d'autoriser un champ d'application défini sur https://www.google.com/m8/feeds/. La méthode API Google People people.updateContact requiert quant à elle le champ d'application accordé https://www.googleapis.com/auth/contacts.

4. Envoyez le jeton d'accès à une API.

Une fois qu'une application obtient un jeton d'accès, elle l'envoie à une API Google dans un en-tête de requête d'autorisation HTTP. Il est possible d'envoyer des jetons en tant que paramètres de chaîne de requête URI, mais nous ne le recommandons pas, car ces paramètres peuvent se retrouver dans des fichiers journaux non sécurisés. De plus, il est recommandé d'éviter de créer des noms de paramètres URI inutiles.

Les jetons d'accès ne sont valides que pour l'ensemble des opérations et des ressources décrit dans l'élément scope de la requête de jeton. Par exemple, si un jeton d'accès est émis pour l'API Google Calendar, il ne donne pas accès à l'API Google Contacts. Toutefois, vous pouvez envoyer ce jeton d'accès à l'API Google Calendar à plusieurs reprises pour des opérations similaires.

5. Actualisez le jeton d'accès, si nécessaire.

Les jetons d'accès ont une durée de vie limitée. Si votre application a besoin d'accéder à une API Google au-delà de la durée de vie d'un jeton d'accès, elle peut obtenir un jeton d'actualisation. Un jeton d'actualisation permet à votre application d'obtenir de nouveaux jetons d'accès.

Scénarios

Applications de serveur Web

Le point de terminaison Google OAuth 2.0 est compatible avec les applications de serveur Web qui utilisent des langages et des frameworks tels que PHP, Java, Python, Ruby et ASP.NET.

La séquence d'autorisation commence lorsque votre application redirige un navigateur vers une URL Google. Cette URL inclut des paramètres de requête qui indiquent le type d'accès demandé. Google gère l'authentification des utilisateurs, la sélection des sessions et le consentement des utilisateurs. Il en résulte un code d'autorisation que l'application peut échanger contre un jeton d'accès et un jeton d'actualisation.

L'application doit stocker le jeton d'actualisation pour une utilisation ultérieure et utiliser le jeton d'accès pour accéder à une API Google. Une fois le jeton d'accès expiré, l'application utilise le jeton d'actualisation pour en obtenir un nouveau.

Votre application envoie une requête de jeton au serveur d'autorisation Google, reçoit un code d'autorisation, échange le code contre un jeton et utilise ce jeton pour appeler un point de terminaison d'API Google.

Pour en savoir plus, consultez Utiliser OAuth 2.0 pour les applications de serveur Web.

Applications installées

Le point de terminaison OAuth 2.0 de Google accepte les applications installées sur des appareils tels que les ordinateurs, les appareils mobiles et les tablettes. Lorsque vous créez un ID client via Google API Console, indiquez qu'il s'agit d'une application installée, puis sélectionnez le type d'application Android, Chrome, iOS, Universal Windows Platform (UWP) ou de bureau.

Le processus génère un ID client et, dans certains cas, un code secret du client, que vous intégrez dans le code source de votre application. (Dans ce contexte, le code secret du client n'est évidemment pas traité comme un secret.)

La séquence d'autorisation commence lorsque votre application redirige un navigateur vers une URL Google. Cette URL inclut des paramètres de requête qui indiquent le type d'accès demandé. Google gère l'authentification des utilisateurs, la sélection des sessions et le consentement des utilisateurs. Il en résulte un code d'autorisation que l'application peut échanger contre un jeton d'accès et un jeton d'actualisation.

L'application doit stocker le jeton d'actualisation pour une utilisation ultérieure et utiliser le jeton d'accès pour accéder à une API Google. Une fois le jeton d'accès expiré, l'application utilise le jeton d'actualisation pour en obtenir un nouveau.

Votre application envoie une requête de jeton au serveur d'autorisation Google, reçoit un code d'autorisation, échange le code contre un jeton et utilise ce jeton pour appeler un point de terminaison d'API Google.

Pour en savoir plus, consultez Utilisation d'OAuth 2.0 pour les applications installées.

Applications côté client (JavaScript)

Le point de terminaison Google OAuth 2.0 est compatible avec les applications JavaScript exécutées dans un navigateur.

La séquence d'autorisation commence lorsque votre application redirige un navigateur vers une URL Google. Cette URL inclut des paramètres de requête qui indiquent le type d'accès demandé. Google gère l'authentification des utilisateurs, la sélection des sessions et le consentement des utilisateurs.

Il en résulte un jeton d'accès que le client doit valider avant de l'inclure dans une requête API Google. Lorsque le jeton expire, l'application répète le processus.

Votre application JS envoie une requête de jeton au serveur d'autorisation Google, reçoit un jeton, le valide et l'utilise pour appeler un point de terminaison d'API Google.

Pour en savoir plus, consultez Utiliser OAuth 2.0 pour les applications côté client.

Applications sur des périphériques à saisie limitée

Le point de terminaison Google OAuth 2.0 est compatible avec les applications qui s'exécutent sur des périphériques à saisie limitée tels que des consoles de jeu, des caméras vidéo et des imprimantes.

La séquence d'autorisation commence par l'application qui envoie une requête de service Web à une URL Google pour obtenir un code d'autorisation. La réponse contient plusieurs paramètres, dont une URL et un code que l'application présente à l'utilisateur.

L'utilisateur obtient l'URL et le code de l'appareil, puis passe à un autre appareil ou ordinateur avec des fonctionnalités d'entrée plus riches. L'utilisateur lance un navigateur, accède à l'URL spécifiée, se connecte et saisit le code.

Pendant ce temps, l'application interroge une URL Google à un intervalle spécifié. Une fois que l'utilisateur a approuvé l'accès, la réponse du serveur Google contient un jeton d'accès et un jeton d'actualisation. L'application doit stocker le jeton d'actualisation pour une utilisation ultérieure et utiliser le jeton d'accès pour accéder à une API Google. Une fois le jeton d'accès expiré, l'application utilise le jeton d'actualisation pour en obtenir un nouveau.

L'utilisateur se connecte sur un autre appareil doté d'un navigateur.

Pour en savoir plus, consultez Utiliser OAuth 2.0 pour les appareils.

Comptes de service

Les API Google telles que Prediction API et Google Cloud Storage peuvent agir au nom de votre application sans accéder aux informations sur les utilisateurs. Dans ces situations, votre application doit prouver sa propre identité à l'API, mais le consentement de l'utilisateur n'est pas nécessaire. De même, dans les scénarios d'entreprise, votre application peut demander un accès délégué à certaines ressources.

Pour ces types d'interactions de serveur à serveur, vous avez besoin d'un compte de service, qui appartient à votre application et non à un utilisateur final individuel. Votre application appelle les API Google au nom du compte de service, et le consentement de l'utilisateur n'est pas requis. Dans les scénarios autres que des comptes de service, votre application appelle les API Google au nom des utilisateurs finaux, et le consentement de l'utilisateur est parfois requis.

Les identifiants d'un compte de service, obtenus à partir de Google API Console, comprennent une adresse e-mail générée unique, un ID client et au moins une paire de clés publique/privée. Vous allez utiliser un ID client et une clé privée pour créer un jeton JWT signé et créer une requête de jeton d'accès au format approprié. Votre application envoie ensuite la requête de jeton au serveur d'autorisation Google OAuth 2.0, qui renvoie un jeton d'accès. L'application utilise le jeton pour accéder à une API Google. Lorsque le jeton expire, l'application répète le processus.

Votre application de serveur utilise un jeton JWT pour demander un jeton au serveur d'autorisation de Google, puis utilise ce jeton pour appeler un point de terminaison d'API Google. Aucun utilisateur final n'est impliqué.

Pour en savoir plus, consultez la documentation concernant les comptes de service.

Taille du jeton

La taille des jetons peut varier, dans les limites suivantes:

  • Codes d'autorisation: 256 octets
  • Jetons d'accès: 2 048 octets
  • Jetons d'actualisation: 512 octets

La structure des jetons d'accès renvoyés par l'API Security Token Service de Google Cloud est semblable à celle des jetons d'accès OAuth 2.0 de l'API Google, mais les limites de taille des jetons sont différentes. Pour en savoir plus, consultez la documentation de l'API.

Google se réserve le droit de modifier la taille des jetons dans ces limites, et votre application doit accepter les tailles de jetons variables en conséquence.

Expiration du jeton d'actualisation

Vous devez écrire votre code pour anticiper la possibilité qu'un jeton d'actualisation accordé ne fonctionne plus. Un jeton d'actualisation peut cesser de fonctionner pour l'une des raisons suivantes:

  • L'utilisateur a révoqué l'accès de votre application.
  • Le jeton d'actualisation n'a pas été utilisé depuis six mois.
  • L'utilisateur a modifié les mots de passe, et le jeton d'actualisation contient les champs d'application Gmail.
  • Le compte utilisateur a dépassé le nombre maximal de jetons d'actualisation autorisés.
  • L'utilisateur appartient à une organisation Google Cloud Platform ayant des règles de contrôle de session en vigueur.

Un projet Google Cloud Platform avec un écran de consentement OAuth configuré pour un type d'utilisateur externe et dont l'état de publication est "Test" se voit émettre un jeton d'actualisation qui expire dans sept jours.

Le nombre de jetons d'actualisation est actuellement limité à 100 par compte Google et par ID client OAuth 2.0. Si la limite est atteinte, la création d'un nouveau jeton d'actualisation désactive automatiquement le plus ancien des jetons d'actualisation sans avertissement. Cette limite ne s'applique pas aux comptes de service.

En outre, le nombre total de jetons d'actualisation autorisé par compte utilisateur ou compte de service est plus élevé pour tous les clients. La plupart des utilisateurs normaux ne dépasseront pas cette limite, mais un compte de développeur utilisé pour tester une implémentation pourrait l'être.

Si vous devez autoriser plusieurs programmes, machines ou appareils, vous pouvez contourner le problème en limitant le nombre de clients à 15 ou 20 par compte Google. Si vous êtes un administrateur Google Workspace, vous pouvez créer des utilisateurs supplémentaires disposant de droits d'administrateur et les utiliser pour autoriser certains des clients.

Gérer les règles de contrôle de session pour les organisations Google Cloud Platform (GCP)

Les administrateurs d'organisations GCP peuvent nécessiter une nouvelle authentification des utilisateurs lorsqu'ils accèdent aux ressources GCP, à l'aide de la fonctionnalité de contrôle de session de Google Cloud. Cette règle affecte l'accès à Google Cloud Console, au SDK Google Cloud (également appelé gcloud CLI) et à toute application OAuth tierce nécessitant le champ d'application Cloud Platform. Si un utilisateur dispose d'une stratégie de contrôle de session, à la fin de la durée de la session, vos appels d'API renverront une erreur semblable à ce qui se passerait si le jeton d'actualisation était révoqué : l'appel échoue avec un type d'erreur invalid_token. Le type de sous-erreur peut être utilisé pour distinguer un jeton de révocation d'un échec en raison d'une règle de contrôle de session. Étant donné que les durées de session peuvent être très limitées (entre 1 heure et 24 heures), ce scénario doit être géré de manière optimale en redémarrant une session d'authentification.

De même, vous ne devez pas utiliser ni encourager l'utilisation d'identifiants utilisateur pour un déploiement de serveur à serveur. Si des identifiants utilisateur sont déployés sur un serveur pour des tâches ou des opérations de longue durée, et qu'un client applique des règles de contrôle de session à ces utilisateurs, l'application serveur échouera, car il ne sera plus possible d'authentifier à nouveau l'utilisateur une fois la durée de session expirée.

Pour savoir comment aider vos clients à déployer cette fonctionnalité, consultez cet article d'aide destiné aux administrateurs.

Bibliothèques clientes

Les bibliothèques clientes suivantes s'intègrent aux frameworks courants, ce qui facilite l'implémentation d'OAuth 2.0. D'autres fonctionnalités seront ajoutées ultérieurement.