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 des applications de serveur Web, côté client, installées et d'appareils à entrée limitée.
Pour commencer, obtenez des identifiants client OAuth 2.0 à partir de la console Google APIs. Ensuite, votre application cliente demande un jeton d'accès au serveur d'autorisation Google, extrait un jeton 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'option permettant d'utiliser 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'utilisation d'OAuth 2.0 pour l'authentification, consultez OpenID Connect.
Procédure générale
Toutes les applications suivent un modèle de base lorsqu'elles accèdent à une API Google à l'aide d'OAuth 2.0. En règle générale, vous devez suivre cinq étapes :
1. Obtenez des identifiants OAuth 2.0 à partir de la console Google APIs.
Accédez à la console Google APIs pour obtenir des identifiants OAuth 2.0, tels qu'un ID client et un code secret du client, connus à la fois 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 code secret, contrairement à une application de serveur Web.
Vous devez créer un client OAuth adapté à la plate-forme sur laquelle votre application s'exécutera, par exemple :
- Pour les applications Android, utilisez le type d'application Android.
-
Pour les applications iOS, utilisez le type d'application iOS.
- desktop_windows Pour les applications de bureau (telles que les applications Windows, macOS ou Linux, ou les outils CLI), utilisez le type d'application Application de bureau.
- code Pour les applications Web côté serveur ou JavaScript, utilisez le type d'application Application Web. N'utilisez pas ce type d'application pour d'autres applications, telles que des applications natives ou mobiles.
- chrome_extension : pour les extensions Chrome, utilisez le type d'application Extension Chrome.
- tv Pour les périphériques d'entrée limités, tels que les téléviseurs ou les appareils intégrés, utilisez le type d'application Téléviseurs et appareils à saisie limitée.
- host Pour les interactions de serveur à serveur, utilisez des comptes de service. Aucun ID client OAuth n'est requis.
2. Obtenez un jeton d'accès auprès du serveur d'autorisation Google.
Avant 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 qui lui accorde 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 qu'un jeton d'accès autorise. Lors de la demande de jeton d'accès, 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 en utilisant une redirection du navigateur vers Google, tandis qu'une application installée sur un appareil sans navigateur utilise des requêtes de service Web. Pour en savoir plus sur la façon d'envoyer la requête, consultez Scenarios et les guides d'implémentation détaillés pour chaque type d'application.
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é à accorder une ou plusieurs autorisations demandées par votre application. Ce processus est appelé consentement 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) et une liste des champs d'application de l'accès accordé 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 où l'accès est requis, plutôt qu'à l'avance. 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 Autorisation incrémentielle.
3. Examinez 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 aux champs d'application 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 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 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 un champ d'application https://www.googleapis.com/auth/contacts lorsqu'une application demande à un utilisateur d'autoriser un champ d'application https://www.google.com/m8/feeds/. La méthode people.updateContact de l'API Google People nécessite un champ d'application https://www.googleapis.com/auth/contacts accordé.
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. Il est possible d'envoyer des jetons en tant que paramètres de chaîne de requête d'URI, mais nous ne le recommandons pas, car les paramètres d'URI peuvent se retrouver dans des fichiers journaux qui ne sont pas complètement sécurisés. De plus, il est recommandé d'é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écrites dans le scope de la requête de jeton. Par exemple, si un jeton d'accès est émis pour l'API Google Agenda, 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 doit accéder à une API Google au-delà de la durée de vie d'un seul 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
Ces scénarios décrivent comment utiliser OAuth 2.0 pour demander des codes d'autorisation, et obtenir des jetons d'accès et d'actualisation pour différents types d'applications.
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 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 se servir du 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.
Pour en savoir plus, consultez 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 dans la console Google APIs, indiquez qu'il s'agit d'une application installée, puis sélectionnez "Android", "Extension Chrome", "iOS" 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 au 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. 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 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. L'application doit valider le jeton d'accès avant de l'inclure dans une requête d'API Google. Lorsque le jeton expire, l'application répète le processus.
Un serveur backend peut éventuellement échanger le code d'autorisation contre un jeton d'actualisation et le stocker dans un emplacement sécurisé. Une fois que le jeton d'accès a expiré, le serveur backend utilise le jeton d'actualisation pour en obtenir un nouveau pour l'application.
Pour en savoir plus, consultez Autoriser l'accès aux données utilisateur Google pour Android, Accéder aux API Google dans une application iOS et OAuth 2.0 pour les applications de bureau.
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.
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 session et le consentement de l'utilisateur.
Le résultat est un jeton d'accès, que le client doit valider avant de l'inclure dans une requête d'API Google. Lorsque le jeton expire, l'application répète le processus.
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 appareils à saisie limitée, tels que les consoles de jeu, les caméras vidéo 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 affiche à l'utilisateur.
L'utilisateur obtient l'URL et le code à partir de l'appareil, puis passe à un autre appareil ou ordinateur doté de fonctionnalités de saisie 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 se servir du jeton d'accès pour accéder à une API Google. Lorsque le jeton d'accès expire, l'application utilise le jeton d'actualisation pour en obtenir un nouveau.
Pour en savoir plus, consultez Utiliser OAuth 2.0 pour les appareils.
Comptes de service
Les API Google telles que l'API Prediction et Google Cloud Storage peuvent agir au nom de votre application sans accéder aux informations utilisateur. Dans ce cas, votre application doit prouver sa propre identité à l'API, mais le consentement 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 entre serveurs, vous avez besoin d'un compte de service, qui est un compte appartenant à 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 sans 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 la console Google APIs, incluent une adresse e-mail générée unique, un ID client et au moins une paire de clés publique/privée. Vous 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 demande 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.
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 :
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 ont des limites de taille 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 jeton variables en conséquence.
Expiration du jeton d'actualisation
Vous devez écrire votre code de manière à 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 :
Un projet Google Cloud Platform avec un écran de consentement OAuth configuré pour un type d'utilisateur externe et un état de publication "Test" reçoit un jeton d'actualisation expirant au bout de sept jours, sauf si les seules habilitations OAuth demandées sont un sous-ensemble de nom, d'adresse e-mail et de profil utilisateur (via les habilitations
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 et que vous créez un autre jeton d'actualisation, l'ancien jeton d'actualisation est automatiquement révoqué sans avertissement préalable. Cette limite ne s'applique pas aux comptes de service.
Il existe également une limite plus élevée concernant le nombre total de jetons d'actualisation qu'un compte utilisateur ou un compte de service peut avoir sur l'ensemble des clients. La plupart des utilisateurs standards ne dépasseront pas cette limite, mais un compte de développeur utilisé pour tester une implémentation pourrait le faire.
Si vous devez autoriser plusieurs programmes, machines ou appareils, une solution consiste à limiter à 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 disposant de droits d'administrateur et les utiliser pour autoriser certains clients.
Gérer les règles de contrôle des sessions pour les organisations Google Cloud Platform (GCP)
Les administrateurs des 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 un impact 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 Cloud Platform. Si une règle de contrôle de session est en place pour un utilisateur, vos appels d'API échoueront à l'expiration de la session, comme si le jeton d'actualisation avait été révoqué. L'appel échouera avec un type d'erreur invalid_grant. Le champ error_subtype peut être utilisé pour distinguer un jeton révoqué d'un échec dû à une règle de contrôle de session (par exemple, "error_subtype": "invalid_rapt"). Étant donné que la durée des sessions peut être très limitée (entre 1 heure et 24 heures), ce scénario doit être géré de manière appropriée en redémarrant une session d'authentification.
De même, 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 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 durée de la session.
Pour en savoir plus sur la façon d'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 aux bibliothèques au fil du temps.
- Bibliothèque d'authentification Google pour Java
- Bibliothèque cliente des API Google pour Python
- Bibliothèque cliente des API Google pour Dart
- Bibliothèque cliente des API Google pour Go
- Bibliothèque cliente des API Google pour .NET
- Bibliothèque cliente des API Google pour Ruby
- Bibliothèque cliente des API Google pour PHP
- Bibliothèque cliente des API Google pour JavaScript
- GTMAppAuth : bibliothèque cliente OAuth pour Mac et iOS