Google s'est engagé à promouvoir l'équité raciale pour les communautés noires. Regardez comment.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

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 prend en charge les scénarios OAuth 2.0 courants, tels que ceux des applications de serveur Web, côté client, installées et à entrée limitée.

Pour commencer, obtenez les informations d'identification du client OAuth 2.0 à partir du 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 et envoie le jeton à l'API Google à laquelle vous souhaitez accéder. Pour une démonstration interactive de l'utilisation d'OAuth 2.0 avec Google (y compris la possibilité d'utiliser vos propres informations d'identification client), testez OAuth 2.0 Playground .

Cette page donne un aperçu des scénarios d'autorisation OAuth 2.0 pris en charge par Google et fournit des liens vers un contenu plus détaillé. Pour plus d'informations sur l'utilisation d'OAuth 2.0 pour l'authentification, consultez OpenID Connect .

Etapes de base

Toutes les applications suivent un modèle de base lors de l'accès à une API Google à l'aide d'OAuth 2.0. À un niveau élevé, vous suivez cinq étapes:

1. Obtenez les informations d'identification OAuth 2.0 du Google API Console.

Accédez au Google API Console pour obtenir des informations d'identification OAuth 2.0, telles qu'un ID client et un secret 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.

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 autorise 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 variable appelé scope contrôle l'ensemble des ressources et des opérations autorisées par un jeton d'accès. Pendant la demande de jeton d'accès, votre application envoie une ou plusieurs valeurs dans le paramètre d' scope .

Il existe plusieurs façons de faire cette demande, et elles 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 demandes de service Web.

Certaines demandes nécessitent une étape d'authentification où l'utilisateur se connecte avec son compte Google. Une fois connecté, il est demandé à l'utilisateur s'il souhaite accorder une ou plusieurs autorisations demandées par votre application. Ce processus s'appelle le 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 portées d'accès accordées par ce jeton. Si l'utilisateur n'accorde pas l'autorisation, le serveur renvoie une erreur.

Il est généralement recommandé de demander des étendues de manière incrémentielle, au moment où l'accès est requis, plutôt qu'initialement. Par exemple, une application qui souhaite prendre en charge l'enregistrement d'un événement dans un calendrier ne doit pas demander l'accès à Google Agenda tant que l'utilisateur n'a pas appuyé sur le bouton "Ajouter au calendrier"; voir Autorisation incrémentielle .

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

Comparez les portées incluses dans la réponse du jeton d'accès aux portées requises pour accéder aux fonctionnalités et 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.

L'étendue incluse dans votre demande peut ne pas correspondre à l'étendue incluse dans votre réponse, même si l'utilisateur a accordé toutes les étendues demandées. Reportez-vous à la documentation de chaque API Google pour connaître les champs d'application requis pour l'accès. Une API peut mapper plusieurs valeurs de chaîne d'étendue à une seule étendue d'accès, renvoyant la même chaîne d'étendue pour toutes les valeurs autorisées dans la demande. Exemple: l'API Google People peut renvoyer une étendue de https://www.googleapis.com/auth/contacts lorsqu'une application a demandé à un utilisateur d'autoriser une étendue de https://www.google.com/m8/feeds/ ; la méthode de l'API Google People people.updateContact nécessite une portée accordée 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 envoie le jeton à une API Google dans un en-tête de demande 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 les paramètres URI peuvent se retrouver dans des fichiers journaux qui ne sont pas complètement sécurisés. En outre, il est recommandé d'éviter de créer des noms de paramètres URI inutiles. Notez que la prise en charge des chaînes de requête sera obsolète le 1er juin 2021.

Les jetons d'accès ne sont valides que pour l'ensemble des opérations et des ressources décrites dans la scope de la demande 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 cependant envoyer ce jeton d'accès à l'API Google Calendar 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.

Scénarios

Applications serveur Web

Le point de terminaison Google OAuth 2.0 prend en charge 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; l'URL comprend 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 future 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 demande 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 serveur Web .

Applications installées

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

Le processus aboutit à 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 comprend 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 future 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 demande 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 de détails, consultez Utilisation d'OAuth 2.0 pour les applications installées .

Applications côté client (JavaScript)

Le point de terminaison Google OAuth 2.0 prend en charge 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 comprend 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.

Votre application JS envoie une demande de jeton au serveur d'autorisation Google, reçoit un jeton, valide le 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 côté client .

Applications sur des appareils à entrée limitée

Le point de terminaison Google OAuth 2.0 prend en charge les applications qui s'exécutent sur des périphériques à entrée limitée tels que les consoles de jeux, les caméras vidéo et les imprimantes.

La séquence d'autorisation commence lorsque l'application envoie une demande de service Web à une URL Google pour un code d'autorisation. La réponse contient plusieurs paramètres, dont une URL et un code que l'application montre à l'utilisateur.

L'utilisateur obtient l'URL et le code de l'appareil, puis bascule vers un appareil ou un ordinateur distinct avec des capacités d'entrée plus riches. L'utilisateur lance un navigateur, accède à l'URL spécifiée, se connecte et entre 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 future 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 appareil distinct doté d'un navigateur

Pour plus d'informations, consultez Utilisation d'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 ces situations, votre application doit prouver sa propre identité à l'API, mais aucun consentement de l'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 est un compte 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 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 informations d'identification d'un compte de service, que vous obtenez du Google API Console, incluent une adresse e-mail générée qui est 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 JWT signé et créer une demande 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.

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

Pour plus de détails, consultez la documentation du compte de service .

Taille du jeton

Les jetons peuvent varier en taille, dans les limites suivantes:

  • Codes d'autorisation: 256 octets
  • Jetons d'accès: 2048 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 ont des limites de taille de jeton différentes. Pour plus de détails, 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 prendre en charge des tailles de jetons variables en conséquence.

Actualiser l'expiration du jeton

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 à 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 des champs d'application Gmail.
  • Le compte utilisateur a dépassé le nombre maximal de jetons d'actualisation accordés (en direct).
  • L'utilisateur appartient à une organisation Google Cloud Platform qui applique 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 un statut de publication de "Test" reçoit un jeton d'actualisation expirant dans 7 jours.

Il existe actuellement une limite de 50 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 sur le nombre total de jetons d'actualisation qu'un compte d'utilisateur ou un compte de service peut avoir sur tous les clients. La plupart des utilisateurs normaux ne dépasseront pas cette limite, mais le compte d'un développeur utilisé pour tester une implémentation pourrait le faire.

Si vous devez autoriser plusieurs programmes, machines ou appareils, une solution de contournement 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 privilèges administratifs utilisez-les pour autoriser certains clients.

Gérer les règles de contrôle de session 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 de Google Cloud. Cette politique a un impact sur l'accès à Google Cloud Console, au SDK google cloud (également appelé interface de ligne de commande gcloud) et à toute application OAuth tierce qui nécessite le champ d'application Cloud Platform. Si un utilisateur a mis en place une stratégie de contrôle de session, à l'expiration de la durée de la session, vos appels d'API entraîneront une erreur similaire à ce qui se passerait si le jeton d'actualisation était révoqué. Comme les durées de session peuvent être très limitées (entre 1 heure 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 ou encourager l'utilisation des informations d'identification de l'utilisateur pour le déploiement de serveur à serveur. Si les informations d'identification de l'utilisateur sont déployées sur un serveur pour des travaux ou des opérations de longue durée et qu'un client applique des stratégies 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 session.

Pour plus d'informations sur la manière d'aider vos clients à déployer cette fonctionnalité, reportez-vous à cet article d'aide axé sur les 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. Plus de fonctionnalités seront ajoutées aux bibliothèques au fil du temps.