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 liés aux applications de serveur Web, côté client, installés et aux entrées limitées.

Pour commencer, obtenez les identifiants du client OAuth 2.0 à partir de Google API Console. Ensuite, votre application cliente demande un jeton d'accès au serveur d'autorisation Google, en extrait un jeton à partir de la réponse et l'envoie à l'API Google à laquelle vous souhaitez accéder. Pour une démonstration interactive de l'utilisation d'OAuth 2.0 avec Google (y compris 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 contenus plus détaillés. Pour en savoir plus sur l'authentification avec OAuth 2.0, consultez la section OpenID Connect.

Procédure générale

Toutes les applications suivent un schéma de base lors de l'accès à une API Google à l'aide du protocole OAuth 2.0. Voici les cinq grandes étapes à suivre:

1. Obtenez des 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 client et un code secret du client, connus de Google et de votre application. L'ensemble de valeurs varie en fonction 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 Google.

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

Il existe plusieurs façons d'effectuer cette requête, qui varient en fonction du 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 services 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é à accepter 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 que votre application peut utiliser pour obtenir un jeton d'accès), ainsi qu'une liste des champs d'application d'accès accordés par ce jeton. Si l'utilisateur n'accorde pas l'autorisation, le serveur affiche une erreur.

Il est généralement recommandé de demander des champs d'application de manière incrémentielle, au moment où l'accès est requis, plutôt que de commencer. Par exemple, une application qui permet d'enregistrer un événement dans un agenda ne doit pas demander d'accès à Google Agenda tant que l'utilisateur n'a pas appuyé sur le bouton "Ajouter à l'agenda". Consultez la section Autorisation incrémentielle.

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

Comparez les champs d'application inclus dans la réponse du jeton d'accès à ceux requis pour accéder aux fonctionnalités de votre application en fonction de l'accès à une API Google associée. Désactivez toutes les fonctionnalités de votre application qui ne peuvent pas fonctionner sans accéder à 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 pour l'accès. Une API peut mapper plusieurs valeurs de chaîne de portée sur un seul champ d'accès en renvoyant la même chaîne de portée pour toutes les valeurs autorisées dans la requête. Exemple: L'API Google People peut renvoyer un champ d'application de https://www.googleapis.com/auth/contacts lorsqu'une application a demandé un utilisateur en autorisant le champ d'application https://www.google.com/m8/feeds/. La méthode d'API Google People people.updateContact requiert un champ d'application accordé https://www.googleapis.com/auth/contacts.

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

Une fois qu'une application a obtenu un jeton d'accès, il 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 d'URI, mais nous ne vous le conseillons pas, car ils peuvent se retrouver dans des fichiers journaux non sécurisés. De plus, nous vous recommandons de ne pas créer de noms d'URI inutiles.

Les jetons d'accès ne sont valides que pour l'ensemble des opérations et des ressources décrits dans la propriété 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. Vous pouvez toutefois envoyer ce jeton d'accès à l'API Google Calendar plusieurs fois pour effectuer 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 seul jeton, il 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 serveurs 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. L'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 de l'utilisateur. Le résultat correspond à 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 le jeton pour appeler un point de terminaison d'API Google.

Pour plus d'informations, consultez Utilisation d'OAuth 2.0 pour les applications de serveur Web.

Applications installées

Le point de terminaison Google OAuth 2.0 est compatible avec les applications installées sur les appareils, tels que les ordinateurs, les appareils mobiles et les tablettes. Lorsque vous créez un ID client via le 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 secret client que vous intégrez dans le code source de votre application. (Dans ce contexte, le secret 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. L'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 de l'utilisateur. Le résultat correspond à 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 le jeton pour appeler un point de terminaison d'API Google.

Pour plus d'informations, 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. L'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 de l'utilisateur.

Le résultat obtenu est un jeton d'accès, que le client doit valider avant de l'inclure dans une requête API Google. Une fois le jeton expiré, 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, la valide et l'utilise pour appeler un point de terminaison d'API Google.

Pour plus d'informations, consultez Utilisation d'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 exécutées sur des appareils à saisie limitée, tels que les consoles de jeu, les caméras vidéo et les imprimantes.

La séquence d'autorisations commence par l'envoi d'une requête de service Web à une URL Google par 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 sur l'appareil, puis passe à un autre appareil ou ordinateur avec des fonctionnalités de saisie plus riches. L'utilisateur lance un navigateur, accède à l'URL spécifiée, se connecte, puis saisit le code.

En parallèle, 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 plus d'informations, consultez Utilisation d'OAuth 2.0 pour les appareils.

Comptes de service

Les API Google, comme l'API Prediction et Google Cloud Storage, peuvent agir au nom de votre application sans accéder aux informations utilisateur. Dans ces cas de figure, votre application doit prouver sa propre identité à l'API, mais aucun consentement de l'utilisateur n'est nécessaire. De même, dans les entreprises, 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 plutôt qu'à 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 qu'un compte 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, que vous obtenez à partir de Google API Console, incluent une adresse e-mail générée, un ID client unique et au moins une paire de clés publique/privée. Utilisez l'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. Une fois le jeton expiré, l'application répète le processus.

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

Pour plus d'informations, consultez la documentation sur les comptes de service.

Taille du jeton

La taille des jetons peut varier dans la limite des limites suivantes:

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

Les jetons d'accès renvoyés par l'API Security Token Service de Google Cloud sont structurés de la même manière que les jetons d'accès OAuth 2.0 de l'API Google, mais leurs limites de taille sont différentes. Pour en savoir plus, consultez la documentation de l'API.

Google se réserve le droit de modifier la taille de jeton dans ces limites, et votre application doit prendre en charge les tailles de jeton 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 de ces raisons:

  • 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 accordés.
  • L'utilisateur appartient à une organisation Google Cloud Platform qui a défini des règles de contrôle de session.

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" est attribué à un jeton d'actualisation qui expire dans sept jours.

Il existe actuellement une limite de 50 jetons d'actualisation par compte Google par ID client OAuth 2.0. Si la limite est atteinte, la création d'un jeton d'actualisation est automatiquement annulée pour le plus ancien. Cette limite ne s'applique pas aux comptes de service.

Le nombre total de jetons d'actualisation dont dispose un utilisateur ou un compte de service sur l'ensemble des clients est également plus élevé. La plupart des utilisateurs normaux ne dépasseront pas cette limite, mais le compte de développeur utilisé pour tester une implémentation pourrait l'être.

Si vous avez besoin d'autoriser plusieurs programmes, machines ou appareils, l'une des solutions consiste à limiter le nombre de clients que vous autorisez par compte Google à 15 ou 20. Si vous êtes un administrateur Google Workspace, vous pouvez créer des utilisateurs supplémentaires avec des 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 réauthentification fréquente 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é CLI gcloud) et à toute application OAuth tierce nécessitant le champ d'application Cloud Platform. Si un utilisateur a mis en place une règle de contrôle de session, puis à l'expiration de la durée de la session, vos appels d'API renvoient une erreur semblable à ce qui se passerait si le jeton d'actualisation a été révoqué. L'appel échoue avec un type d'erreur invalid_token. Le type de sous-erreur peut être utilisé pour faire la distinction entre un jeton de révocation et un échec dû à une règle de contrôle de session. La durée des sessions pouvant être très limitée (entre une et 24 heures), vous devez gérer ce scénario en redémarrant une session d'authentification.

De plus, vous ne devez pas utiliser ni encourager l'utilisation d'identifiants utilisateur pour le déploiement de serveur à serveur. Si des identifiants utilisateur sont déployés sur un serveur pour des tâches ou opérations de longue durée, et qu'un client applique des règles de contrôle de session à ces utilisateurs, l'application serveur échoue, car il ne sera pas possible de s'authentifier à nouveau auprès de 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 populaires, ce qui simplifie l'implémentation d'OAuth 2.0. D'autres fonctionnalités seront ajoutées ultérieurement aux bibliothèques.