Cette page a été traduite par l'API Cloud Translation.

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 est compatible avec les scénarios OAuth 2.0 courants, tels que ceux pour les applications de serveur Web, côté client, installées et avec périphériques d'entrée limités.

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, extrait un jeton de la réponse, puis l'envoie à l'API Google à laquelle vous souhaitez accéder. Pour voir une démonstration interactive de l'utilisation d'OAuth 2.0 avec Google (y compris la possibilité d'utiliser vos propres identifiants client), testez OAuth 2.0 Playground.

Cette page présente les scénarios d'autorisation OAuth 2.0 acceptés par Google et fournit des liens vers des contenus plus détaillés. Pour plus d'informations sur l'utilisation du protocole OAuth 2.0 pour l'authentification, consultez la page OpenID Connect.

Procédure générale

Toutes les applications suivent un schéma de base pour accéder à une API Google avec 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 à la Google API Console pour obtenir des identifiants OAuth 2.0, tels qu'un ID et un code secret du client, connus à la fois par Google et par votre application. L'ensemble de valeurs varie selon le type d'application que vous créez. Par exemple, une application JavaScript ne nécessite pas de code secret, contrairement à une application de serveur Web.

Vous devez créer un client OAuth adapté à la plate-forme sur laquelle votre application sera exécutée, par exemple:

Pour les applications côté serveur ou les applications Web JavaScript, utilisez le type de client "web". N'utilisez pas ce type de client pour d'autres applications, telles que des applications natives ou mobiles.
Pour les applications Android, utilisez le type de client "Android".
Pour les applications iOS et macOS, utilisez le type de client "iOS".
Pour les applications de plate-forme Windows universelle, utilisez le type de client "Plate-forme Windows universelle".
Pour les périphériques d'entrée limités, tels que les téléviseurs ou les périphériques intégrés, utilisez le type de client "Téléviseurs et périphériques d'entrée limités".
Pour les interactions de serveur à serveur, utilisez des comptes de service.

2. Procurez-vous un jeton d'accès auprès du serveur d'autorisation 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 seul 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 des opérations autorisées par un jeton d'accès. Lors de 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 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 n'utilise pas de requêtes de services Web.

Certaines requêtes nécessitent une étape d'authentification au cours de laquelle 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 que votre application peut utiliser pour obtenir un jeton d'accès) ainsi qu'une liste des niveaux d'accès accordés par ce jeton. Si l'utilisateur n'accorde pas cette autorisation, le serveur renvoie une erreur.

Il est généralement recommandé de demander des niveaux d'accès de manière incrémentielle, au moment où l'accès est requis, plutôt que dès le départ. Par exemple, une application qui souhaite permettre l'enregistrement d'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". Consultez la section Autorisation incrémentielle.

3. Examinez 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 à 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è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 à un seul champ d'application, 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 un champ d'application de https://www.googleapis.com/auth/contacts lorsqu'une application demande à un utilisateur d'autoriser un champ d'application de https://www.google.com/m8/feeds/. La méthode people.updateContact de l'API Google People nécessite un champ d'application autorisé de https://www.googleapis.com/auth/contacts.

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

Une fois qu'une application a obtenu un jeton d'accès, elle l'envoie à une API Google dans un en-tête de requête d'autorisation HTTP. Vous pouvez envoyer des jetons en tant que paramètres de chaîne de requête d'URI, mais nous vous le déconseillons, car les paramètres d'URI peuvent se retrouver dans des fichiers journaux qui ne sont pas complètement sécurisés. En outre, une bonne pratique REST consiste à éviter de créer des noms de paramètres d'URI inutiles.

Les jetons d'accès ne sont valides que pour l'ensemble des opérations et des ressources décrit dans la section scope de la requête de jeton. Par exemple, si un jeton d'accès est émis pour l'API Google Calendar, il n'accorde pas l'accès à l'API Google Contacts. Vous pouvez toutefois envoyer ce jeton d'accès à l'API Google Agenda plusieurs fois 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, Go, 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 de l'utilisateur, la sélection de la session et le consentement de l'utilisateur. Le résultat est 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 l'utiliser 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, l'échange contre un jeton et utilise le jeton pour appeler un point de terminaison de l'API Google.

Pour en savoir plus, consultez la page Utiliser 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 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 Android, application Chrome, iOS, plate-forme Windows universelle (UWP) ou application de bureau comme type d'application.

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 considéré comme un secret.)

Pour en savoir plus, consultez Utiliser 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 qui s'exécutent dans un navigateur.

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 JavaScript 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 de l'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 à entrée limitée tels que les consoles de jeu, les caméras et les imprimantes.

La séquence d'autorisation commence lorsque l'application 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 doté de 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 l'utiliser 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 Predictions et Google Cloud Storage peuvent agir au nom de votre application sans accéder aux informations utilisateur. 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 ce type 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 des API Google au nom du compte de service, et le consentement de l'utilisateur n'est pas requis. (Dans les scénarios sans compte de service, votre application appelle des 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 unique, un ID client 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 construire 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 ce 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 Google, puis utilise ce jeton pour appeler un point de terminaison de l'API Google. Aucun utilisateur final n'est impliqué.

Pour en savoir plus, consultez la documentation sur 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

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 des API Google, mais ils ont des limites de taille de jeton différentes. Pour en savoir plus, consultez la documentation de l'API.

Google se réserve le droit de modifier la taille du jeton dans ces limites. Votre application doit prendre en charge des tailles de jeton variables en conséquence.

Expiration du jeton d'actualisation

Vous devez écrire votre code de façon à 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 à votre application.
Le jeton d'actualisation n'a pas été utilisé depuis six mois.
L'utilisateur a modifié des mots de passe, et le jeton d'actualisation contient des habilitations Gmail.
Le compte utilisateur a dépassé le nombre maximal de jetons d'actualisation accordés (en direct).
Si un administrateur a défini l'un des services demandés dans les champs d'application de votre application sur "Limité" (l'erreur est admin_policy_enforced).
Pour les API Google Cloud Platform, la durée de session définie par l'administrateur aurait pu être dépassée.

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" reçoit un jeton d'actualisation qui expire dans sept jours, sauf si les seuls champs d'application OAuth demandés sont un sous-ensemble de nom, d'adresse e-mail et de profil utilisateur (via les champs d'application userinfo.email, userinfo.profile, openid ou leurs équivalents OpenID Connect).

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

Il existe également une limite plus élevée pour le nombre total de jetons d'actualisation qu'un compte utilisateur ou un compte de service peut avoir pour tous les clients. La plupart des utilisateurs normaux ne dépassent pas cette limite, contrairement à un compte de développeur utilisé pour tester une implémentation.

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

Gérer les stratégies de contrôle de session pour les organisations Google Cloud Platform (GCP)

Les administrateurs d'organisations GCP peuvent exiger une réauthentification fréquente des utilisateurs lorsqu'ils accèdent aux ressources GCP, à l'aide de la fonctionnalité de contrôle de session Google Cloud. Cette règle a une incidence sur l'accès à la console Google Cloud, au SDK Google Cloud (également appelé gcloud CLI) et à toute application OAuth tierce nécessitant le champ d'application de Cloud Platform. Si un utilisateur a mis en place une règle de contrôle de session, à l'expiration de la durée de session, vos appels d'API généreront des erreurs de la même manière que si le jeton d'actualisation était révoqué. L'appel échouera avec le type d'erreur invalid_grant. Le champ error_subtype permet de faire la distinction entre un jeton révoqué et un échec dû à une règle de contrôle de session (par exemple, "error_subtype": "invalid_rapt"). La durée de session peut être très limitée (entre 4 heures et 2).

De même, vous ne devez pas utiliser d'identifiants utilisateur 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 n'y aura aucun moyen de réauthentifier l'utilisateur à l'expiration de la session.

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 aux bibliothèques au fil du temps.