Les API Google utilisent le protocole OAuth 2.0 pour l'authentification et l'autorisation. Google accepte les scénarios courants OAuth 2.0, tels que ceux relatifs au serveur Web, aux applications côté client, aux applications installées et aux applications sur des périphériques à saisie limitée applications.
Pour commencer, obtenez les identifiants client OAuth 2.0 depuis la console Google API. Votre application cliente demande ensuite un jeton d'accès au serveur d'autorisation Google, extrait le jeton de 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 la plate-forme 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. De manière générale, vous devez suivre les cinq étapes suivantes :
1. Obtenez les identifiants OAuth 2.0 depuis la console Google API.
Accédez à la console Google API pour obtenir les identifiants OAuth 2.0, tels qu'un ID client et un code secret du client, qui sont 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
Android . -
Pour les applications iOS et macOS, utilisez
le type de client iOS . -
code
Pour les applications Web côté serveur ou JavaScript, utilisez
le type de client
Application Web . N'utilisez pas ce type de client pour d'autres applications, telles que les applications natives ou mobiles. - chrome_extension Pour les extensions Chrome, utilisez le type de client Extension Chrome.
-
tv
Pour les périphériques à saisie limitée, tels que les téléviseurs ou les appareils intégrés, utilisez le type de client
Téléviseurs et périphériques à 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.
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 qui lui accorde l'accès à cette API. Un seul jeton d'accès peut accorder différents niveaux
d'accès à plusieurs API. Un paramètre variable appelé scope contrôle l'ensemble
des ressources et des opérations autorisées par un jeton d'accès. Lors de la demande de jeton d'accès,
votre application envoie une ou plusieurs valeurs dans le scope paramètre.
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 de 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'effectuer 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 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) et une liste des niveaux 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 les niveaux d'accès 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 d'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". Consultez 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 aux niveaux d'accès 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 niveau d'accès inclus dans votre requête peut ne pas correspondre à celui inclus dans votre réponse, même
si l'utilisateur a accordé tous les niveaux d'accès demandés. Consultez 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 niveau d'accès à un seul
niveau d'accès, en renvoyant la même chaîne de niveau d'accès pour toutes les valeurs autorisées dans la requête.
Exemple : l'API Google People peut renvoyer un niveau d'accès
https://www.googleapis.com/auth/contacts lorsqu'une application a demandé à un utilisateur d'autoriser
un niveau d'accès https://www.google.com/m8/feeds/. La méthode
people.updateContact de l'API Google People nécessite un niveau d'accès accordé 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. Il est possible d'envoyer des jetons en tant que paramètres de chaîne de requête URI, mais nous vous le déconseillons, car les paramètres URI peuvent se retrouver dans des fichiers journaux qui ne sont pas entièrement 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é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 a besoin d'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.
Scenarios
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 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 token.
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.
Pour plus d'informations, 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 via la console Google API, spécifiez qu'il s'agit d'une application installée, puis sélectionnez Application Android, Extension Chrome, Application 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 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 request. Lorsque le jeton expire, l'application répète le processus.
Vous pouvez également demander à un serveur backend d'échanger le code d'autorisation contre un jeton d'actualisation, et de le stocker dans un emplacement sécurisé. Une fois le jeton d'accès 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, et OAuth 2.0 pour les applications iOS et 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 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 périphériques à saisie limitée tels que les consoles de jeux, les caméras vidéo et les imprimantes.
La séquence d'autorisation commence par une requête de service Web envoyée par l'application à une URL Google pour obtenir un code d'autorisation. La réponse contient plusieurs paramètres, y compris 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 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.
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 pour le compte de votre application sans accéder aux informations utilisateur. Dans ce cas, votre application doit prouver sa propre identité auprès de l'API, mais aucun consentement utilisateur n'est 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. Votre application appelle les API Google pour le compte du compte de service, et le consentement utilisateur n'est pas requis. (Dans les scénarios sans compte de service, votre application appelle les API Google pour le compte des utilisateurs finaux, et le consentement utilisateur est parfois requis.)
Les identifiants d'un compte de service, que vous obtenez depuis la console Google API, 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 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.
Pour en savoir plus, consultez la documentation sur les comptes de service.
Taille des jetons
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 ont une structure semblable à celle des jetons d'accès OAuth 2.0 de l'API Google, mais des limites de taille de jeton différentes. Pour plus d'informations, 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 être compatible avec les tailles de jetons variables.
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 :
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 dans sept jours, sauf si les seuls niveaux d'accès OAuth demandés sont un sous-ensemble du nom, de l'adresse e-mail et du profil utilisateur (via les niveaux d'accès
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 sur le nombre total de jetons d'actualisation qu'un compte utilisateur ou compte de service peut avoir sur 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 peut le faire.
Si vous devez autoriser plusieurs programmes, machines ou appareils, vous pouvez limiter le nombre de clients que vous autorisez par compte Google à 15 ou 20. Si vous êtes administrateur Google Workspace, vous pouvez créer des utilisateurs supplémentaires avec des 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 des sessions Google Cloud. Cette règle a un impact sur l'accès à la console Google Cloud, au
Google Cloud SDK (également appelé gcloud
CLI) et à toute application OAuth tierce nécessitant le niveau d'accès Cloud Platform. Si un
utilisateur a une règle de contrôle des sessions en place, à l'expiration de la durée de la session, vos
appels d'API généreront une erreur semblable à celle qui se produirait si le jeton d'actualisation était révoqué. L'
appel échouera avec un type d'erreur invalid_grant. Le champ error_subtype
peut être utilisé pour faire la distinction entre un jeton révoqué et un échec dû à une règle de contrôle des
sessions (par exemple, "error_subtype": "invalid_rapt"). Étant donné que les durées de session
peuvent être très limitées (entre 1 et 24 heures), ce scénario doit être géré
correctement 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 des sessions à 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 courants, 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 Google Auth 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