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

Authentification et autorisation dans le protocole de données Google

Avertissement : Cette page concerne les anciennes API Google, les API Google Data. Elle ne concerne que les API répertoriées dans l'annuaire des API Google Data, dont la plupart ont été remplacées par de nouvelles API. Pour en savoir plus sur une nouvelle API spécifique, consultez sa documentation. Pour en savoir plus sur l'autorisation des requêtes avec une API plus récente, consultez Authentification et autorisation des comptes Google.

Les applications tierces nécessitent souvent un accès limité au compte Google d'un utilisateur pour certains types d'activités. Pour éviter toute utilisation abusive des données utilisateur, toutes les demandes d'accès doivent être approuvées par le titulaire du compte. Le contrôle des accès comprend deux composants : l'authentification et l'autorisation.

Les services d'authentification permettent aux utilisateurs de se connecter à votre application à l'aide d'un compte Google.

Les services d'autorisation permettent aux utilisateurs de fournir à votre application l'accès aux données qu'ils ont stockées dans les applications Google. Google prend très au sérieux la confidentialité des données, et toute application nécessitant l'accès aux données d'un utilisateur doit être autorisée par ce dernier.

Les services d'authentification et d'autorisation sont souvent appelés collectivement auth.

L'authentification et l'autorisation des API Google permettent aux applications tierces d'obtenir un accès limité au compte Google d'un utilisateur pour certains types d'activités. Ce document présente les mécanismes d'authentification disponibles et décrit ce que chacun d'eux fournit pour votre application.

Google Sign-In permet aux internautes d'utiliser facilement leurs identifiants Google pour se connecter à votre site. Il comprend un ensemble d'outils faciles à intégrer sur différents appareils.
OAuth 2.0 est un protocole d'autorisation pour toutes les API Google. OAuth 2.0 repose sur SSL pour la sécurité au lieu d'exiger directement de votre application qu'elle effectue une signature cryptographique. Ce protocole permet à votre application de demander l'accès aux données associées au compte Google d'un utilisateur.
La connexion avec OAuth 2.0 (OpenID Connect) authentifie les utilisateurs en les obligeant à se connecter avec leur compte Google. Cette fonctionnalité remplace OpenID. Les utilisateurs d'OpenID doivent donc envisager de migrer vers le protocole de connexion OAuth 2.0.

Si votre application est un gadget (pour utilisation dans iGoogle ou d'autres conteneurs OpenSocial), consultez la section Authentification pour les gadgets.

Remarque: Ce document vise à fournir un aperçu de chaque méthode d'authentification. Pour en savoir plus sur chaque méthode, consultez la documentation complète sur les API d'authentification de compte Google.

Pour en savoir plus sur l'utilisation des API Google Accounts, consultez également le groupe dédié aux API Comptes Google.

OAuth – Autorisation pour les applications Web et installées

De nombreux services Google autorisent l'accès tiers aux données générées par les utilisateurs, telles que les données d'agenda ou de documents, à condition que l'accès soit autorisé par l'utilisateur. Cette fonctionnalité permet aux utilisateurs de partager et d'échanger des données entre leurs applications Google et des applications tierces à diverses fins.

Google prend en charge deux versions d'OAuth pour obtenir un accès autorisé aux données Google d'un utilisateur: OAuth 1.0 et OAuth 2.0, offrant tous deux un accès aux applications Web et aux applications installées.

OAuth 2.0 pour les applications Web et installées

Les applications Web ou installées peuvent utiliser le nouveau protocole simplifié OAuth 2.0 pour autoriser l'accès aux données associées à un compte Google. Pour en savoir plus et obtenir des exemples d'implémentation d'OAuth 2.0 avec Google, consultez notre documentation sur OAuth 2.0.

OAuth 1.0 pour les applications Web

Les applications Web qui ont besoin d'un accès autorisé aux données associées à un compte Google ou à un compte Google Apps peuvent utiliser l'implémentation Google de l'API OAuth. Pour obtenir des informations complètes sur l'implémentation d'OAuth pour les applications Web, y compris des exemples, consultez le guide OAuth pour les applications Web ou la présentation de ce document.

OAuth 1.0 pour les applications installées

Les applications installées sur les ordinateurs et les appareils mobiles des utilisateurs peuvent utiliser OAuth pour autoriser l'accès aux données associées à un compte Google. Pour obtenir des informations complètes sur l'implémentation d'OAuth pour les applications installées, consultez le guide OAuth pour les applications installées ou la présentation de ce document.

Utiliser OAuth avec des applications Web

Toutes les API Google Data sont compatibles avec OAuth, une norme ouverte qui autorise l'utilisation de données dans les applications Web. Toutes les applications Web qui effectuent des requêtes OAuth doivent importer un certificat de sécurité et s'enregistrer auprès de Google. Pour plus d'informations, consultez la page Inscription pour les applications Web.

Les bibliothèques clientes des API Google Data fournissent des méthodes pour vous aider à utiliser OAuth dans votre application Web. Plus précisément, il existe des méthodes pour créer le jeton de demande, autoriser le jeton de demande et échanger le jeton de requête autorisé contre un jeton d'accès. Les bibliothèques gèrent également les algorithmes de signature nécessaires lorsqu'elles envoient des requêtes à un service de données Google. Pour obtenir des exemples complets d'utilisation d'OAuth avec les bibliothèques clientes des API Google Data,consultez Utiliser OAuth avec les bibliothèques clientes des API Google Data.

Processus d'autorisation OAuth

Le processus d'autorisation OAuth implique une série d'interactions entre votre application Web, les serveurs d'autorisation de Google et l'utilisateur final.

Le processus de base est le suivant:

Votre application demande l'accès et reçoit un jeton de requête non autorisé du serveur d'autorisation de Google.
Google demande à l'utilisateur de vous accorder l'accès aux données requises.
Votre application obtient un jeton de requête autorisé du serveur d'autorisation.
Vous échangez le jeton de requête autorisé contre un jeton d'accès.
Vous utilisez le jeton d'accès pour demander des données aux serveurs d'accès aux services de Google.

Lorsque votre application demande initialement l'accès aux données d'un utilisateur, Google lui envoie un jeton de requête non autorisé.

Si l'utilisateur n'est pas déjà connecté, Google l'invite à le faire. Google affiche ensuite une page d'autorisation qui permet à l'utilisateur de voir à quelles données de service Google votre application demande l'accès.

Si l'utilisateur approuve la demande d'accès de votre application, Google émet un jeton de requête autorisé. Chaque jeton de requête n'est valide que pendant une heure. Seul un jeton de requête autorisé peut être échangé contre un jeton d'accès. Cet échange ne peut être effectué qu'une seule fois par jeton de requête autorisé.

Par défaut, les jetons d'accès ont une longue durée de vie. Chaque jeton d'accès est spécifique au compte utilisateur spécifié dans la demande d'autorisation initiale et n'accorde l'accès qu'aux services spécifiés dans cette demande. Votre application doit stocker le jeton d'accès en toute sécurité, car il est requis pour tout accès aux données d'un utilisateur.

Se préparer pour OAuth

Avant de pouvoir configurer votre application pour utiliser le service d'autorisation de Google avec OAuth, vous devez effectuer les tâches suivantes.

Décider d'enregistrer ou non votre application Web

Pour fournir à vos utilisateurs des garanties supplémentaires concernant la sécurité de leurs données, vous pouvez enregistrer votre application Web auprès de Google et signer vos requêtes avec le certificat de sécurité enregistré. Certains flux d'API Google Data ne sont disponibles que pour les applications enregistrées. Consultez la documentation de l'API Google Data qui vous intéresse pour déterminer si elle ne fonctionne qu'avec les applications enregistrées.

Votre application doit signer chaque requête OAuth qu'elle effectue. Si vous choisissez d'utiliser une signature RSA-SHA1 pour signer vos requêtes, vous devez importer un certificat de sécurité dans le cadre du processus d'enregistrement.

Vous pouvez également utiliser une signature HMAC-SHA1 pour signer vos requêtes. Aucun certificat n'est requis pour les signatures HMAC-SHA1. Au lieu de cela, Google génère une valeur OAuth consumer secret, qui s'affiche sur la page d'enregistrement de votre domaine une fois celui-ci enregistré.

Pour en savoir plus sur le processus d'enregistrement, consultez la section Inscription pour les applications Web.

Déterminer la portée des données auxquelles votre application accédera

Chaque service Google limite les accès qu'il autorise via les API Google Data. Cet accès est exprimé sous la forme d'une valeur de champ d'application. Certains services fournissent diverses valeurs de champ d'application pour permettre à un utilisateur de choisir quelles applications doivent avoir accès à quelles données. Pour en savoir plus sur les valeurs de champ d'application disponibles pour le service Google auquel vous souhaitez accéder, consultez la documentation de ce service.

En général, vous devez demander un jeton pour le champ d'application le plus étroit incluant les données dont vous avez besoin. Par exemple, si votre application a besoin d'accéder au flux "Tous les agendas" de l'utilisateur, vous devez demander un jeton pour le champ d'application http://www.google.com/calendar/feeds/default/allcalendars/full.

Configurer un mécanisme pour gérer les jetons OAuth

Lorsque vous obtenez un jeton d'accès OAuth pour les données d'un utilisateur, vous devez utiliser ce jeton pour toutes les interactions futures avec le service Google spécifié au nom de l'utilisateur.

Votre application doit gérer le stockage des jetons de manière sécurisée, y compris en surveillant le service Google pour lequel chaque jeton est valide. Si vous avez besoin d'accéder à plusieurs services Google, vous pouvez obtenir plusieurs jetons d'accès, mais pas plus de dix jetons d'accès par utilisateur et par application à tout moment.

Si votre application est compatible avec plusieurs comptes utilisateur, vous devez savoir à quel compte chaque jeton est associé. Chaque jeton OAuth est spécifique à l'utilisateur qui a autorisé l'accès. Votre application doit pouvoir associer un jeton à l'utilisateur approprié. Pour gérer cette opération, vous pouvez par exemple envoyer un cookie à l'utilisateur avant d'envoyer la requête de jeton. Une fois que l'utilisateur a accordé l'accès aux données demandées, Google envoie un jeton de requête autorisé et redirige l'utilisateur vers votre application. Vous pouvez ensuite utiliser le cookie de votre application pour associer le jeton à l'utilisateur approprié.

Configurer un mécanisme pour demander l'accès à un service Google

Chaque requête adressée à un service Google doit être signée et inclure un jeton d'accès OAuth valide. En général, chaque requête est effectuée sous la forme d'une requête HTTP GET, avec le jeton d'accès et la signature inclus dans l'en-tête. Les requêtes qui écrivent de nouvelles données doivent utiliser HTTP POST.

Pour plus d'informations sur le format de requête approprié pour chaque API Google Data, consultez la documentation de l'API concernée.

Implémenter OpenID (facultatif)

Si vous mettez en œuvre OpenID pour l'authentification des utilisateurs, envisagez d'utiliser le protocole hybride pour combiner les deux processus. Avec OpenID+OAuth, les tâches d'obtention et d'autorisation d'un jeton de requête sont gérées dans le cadre de la requête OpenID avec extensions OAuth. Comme pour OAuthGetRequestToken, ces extensions permettent d'identifier les services Google auxquels l'utilisateur accède. Une réponse positive à la requête OpenID contient un jeton de requête autorisé. Une fois ce jeton reçu, utilisez OAuthGetAccessToken pour l'échanger contre un jeton d'accès.

Utiliser des jetons OAuth

Pour utiliser OAuth, votre application doit générer des appels de requête signés et correctement formés, et gérer les réponses, pour la séquence suivante:

Obtenir un jeton de requête non autorisé (OAuthGetRequestToken)
Autoriser le jeton de requête (OAuthAuthorizeToken)
Échanger le jeton de requête autorisé contre un jeton d'accès (OAuthGetAccessToken)

Toutes les requêtes OAuth doivent être signées, que votre application soit enregistrée ou non. Pour en savoir plus, consultez Signer des requêtes OAuth.

Vous pouvez tester la demande et la réception de jetons d'autorisation dans OAuth Playground.

Pour obtenir de la documentation détaillée, consultez la documentation de référence de l'API OAuth.

Définir une URL de rappel

Vous pouvez spécifier une valeur pour oauth_callback dans une requête OAuthGetRequestToken afin de déterminer où Google redirige l'utilisateur après avoir autorisé votre demande d'accès. L'URL de rappel peut inclure des paramètres de requête. La redirection inclura les mêmes paramètres de requête, ainsi que le jeton de requête autorisé, que votre application doit pouvoir analyser.

Par exemple, si plusieurs langues sont disponibles, vous pouvez inclure un paramètre de requête qui identifie la version de l'application consultée par l'utilisateur. Si la valeur oauth_callback de "http://www.yoursite.com/Retrievetoken?Lang=de génère la redirection "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE", L'analyse du jeton et du paramètre de langue garantit que l'utilisateur est redirigé vers la version appropriée du site.

Si le paramètre oauth_callback n'est pas inclus, Google redirigera l'utilisateur vers une page Web affichant un numéro de validation (voir un exemple) après avoir autorisé votre demande d'accès. L'utilisateur doit revenir manuellement à votre application et saisir le numéro de validation pour que vous puissiez obtenir un jeton de requête autorisé.

Identifier votre application auprès des utilisateurs

Google affiche normalement le nom d'une application lorsque l'utilisateur demande son autorisation d'accès (voir un exemple).

Si votre application n'est pas enregistrée, utilisez le paramètre xoauth_displayname dans votre requête OAuthGetRequestToken pour spécifier le nom de votre application. Si ce paramètre n'est pas spécifié, Google affiche le nom de domaine de l'URL fournie par le paramètre oauth_callback. Si aucune URL de rappel n'est fournie, Google affiche la chaîne "anonyme".

Ne définissez pas ce paramètre si votre application est enregistrée. Par défaut, Google affiche le nom à afficher spécifié lors de l'enregistrement. Si vous définissez un nom à afficher dans votre requête OAuthGetRequestToken, Google l'utilisera à la place du nom à afficher enregistré, et inclura un message indiquant que l'identité de votre application ne peut pas être validée.

Remarque:Pour définir le paramètre xoauth_displayname dans OAuth Playground, cochez la case "Avancé" avant de récupérer le jeton de requête.

Utilisation des domaines Google Apps

Si votre application est conçue pour les utilisateurs d'un domaine de comptes Google hébergé, envisagez d'utiliser le paramètre hd lorsque vous autorisez un jeton. Pour en savoir plus sur le paramètre hd, consultez la page Gérer des utilisateurs disposant de plusieurs comptes.

En savoir plus sur OAuth

Pour obtenir des informations détaillées sur la mise en œuvre du protocole OAuth par Google, y compris sur la manière d'enregistrer votre application et de créer les paramètres OAuth nécessaires, consultez les ressources supplémentaires suivantes:

Utiliser OAuth avec les bibliothèques clientes des API Google Data
Article : Utiliser OAuth avec les API Google Data, y compris Description d'OAuth Playground, un outil interactif permettant de tester OAuth
OAuth pour les applications Web (documentation complète)
Inscription pour les applications Web
Générer des clés et des certificats
Spécification OAuth

Haut de page

Utiliser OAuth avec les applications installées

Toutes les API Google Data sont compatibles avec OAuth, une norme ouverte qui autorise l'utilisation de données dans les applications. Les applications installées ne doivent pas être enregistrées auprès de Google pour utiliser OAuth.

Processus d'autorisation OAuth

Le processus d'autorisation OAuth implique une série d'interactions entre votre application, les serveurs d'autorisation de Google et l'utilisateur final.

Le processus de base est le suivant:

Votre application demande l'accès et reçoit un jeton de requête non autorisé du serveur d'autorisation de Google.
Google demande à l'utilisateur de vous accorder l'accès aux données requises.
Votre application obtient un jeton de requête autorisé du serveur d'autorisation.
Vous échangez le jeton de requête autorisé contre un jeton d'accès.
Vous utilisez le jeton d'accès pour demander des données aux serveurs d'accès aux services de Google.

Lorsque votre application demande initialement l'accès aux données d'un utilisateur, Google lui envoie un jeton de requête non autorisé.

OAuth est compatible avec les applications installées à l'aide du mode non enregistré. Étant donné qu'il existe différentes méthodes pour obtenir un jeton de requête autorisé, votre application peut utiliser OAuth pour autoriser une application, même si l'appareil sur lequel elle est installée ne dispose pas d'un navigateur Web.

Se préparer pour OAuth

Avant de pouvoir configurer votre application pour utiliser le service d'autorisation de Google avec OAuth, vous devez effectuer les tâches suivantes.

Déterminer la portée des données auxquelles votre application accédera

Configurer un mécanisme pour gérer les jetons OAuth

Votre application doit gérer le stockage des jetons de manière sécurisée, y compris en surveillant le service Google pour lequel chaque jeton est valide.

Si votre application est compatible avec plusieurs comptes utilisateur, vous devez savoir à quel compte chaque jeton est associé.

Configurer un mécanisme pour demander l'accès à un service Google

Pour plus d'informations sur le format de requête approprié pour chaque API Google Data, consultez la documentation de l'API concernée.

Utiliser des jetons OAuth

Pour utiliser OAuth, votre application doit générer des appels de requête signés et correctement formés, et gérer les réponses, pour la séquence suivante:

Obtenir un jeton de requête non autorisé (OAuthGetRequestToken)
Autoriser le jeton de requête (OAuthAuthorizeToken)
Échanger le jeton de requête autorisé contre un jeton d'accès (OAuthGetAccessToken)

Toutes les requêtes OAuth doivent être signées, que votre application soit enregistrée ou non. Pour en savoir plus, consultez Signer des requêtes OAuth. Les applications installées doivent suivre les instructions pour une application non enregistrée.

Vous pouvez tester la demande et la réception de jetons d'autorisation dans OAuth Playground.

Pour obtenir de la documentation détaillée, consultez la documentation de référence de l'API OAuth.

Identifier votre application auprès des utilisateurs

Google affiche normalement le nom d'une application lorsque l'utilisateur demande son autorisation d'accès (voir un exemple).

Utilisez le paramètre xoauth_displayname dans votre requête OAuthGetRequestToken pour spécifier le nom de votre application. Si ce paramètre n'est pas spécifié, Google affiche le nom de domaine de l'URL fournie par le paramètre oauth_callback. Si aucune URL de rappel n'est fournie, Google affiche la chaîne "anonyme".

Remarque:Pour définir le paramètre xoauth_displayname dans OAuth Playground, cochez la case "Avancé" avant de récupérer le jeton de requête.

Lancer un navigateur Web

Dans le cadre du processus d'autorisation OAuth, votre application doit envoyer une requête OAuthAuthorizeToken. L'utilisateur doit alors se connecter à une page Web Google et autoriser la demande d'accès de votre application.

Le mode de détection automatique doit être utilisé pour la plupart des applications
Le mode Appareil doit être utilisé pour les applications qui ne peuvent pas lancer un navigateur Web complet.
Le mode Développement ne doit être utilisé qu'au début du développement.

Mode de détection automatique

Si possible, votre application doit lancer une fenêtre de navigateur et effectuer une requête OAuthAuthorizeToken pour ouvrir la page Google. Lorsque Google renvoie le jeton autorisé, votre application doit le détecter et se reconnecter au navigateur Web.

Pour ce mode, vous devez fournir une URL de rappel vers laquelle l'utilisateur est redirigé après avoir autorisé votre demande d'accès. Cette URL doit être fournie comme paramètre oauth_callback de la requête OAuthGetRequestToken et comme paramètre verifier de la requête OAuthGetAccessToken.

Pour améliorer l'expérience utilisateur, votre application doit tenter de détecter automatiquement lorsque l'utilisateur est redirigé vers cette URL, et de se placer immédiatement au premier plan et d'effectuer une requête OAuthGetAccessToken pour terminer le processus OAuth.

Pour en savoir plus et connaître les bonnes pratiques, consultez la section Détection automatique des approbations.

Si votre application ne peut pas détecter automatiquement que l'utilisateur est redirigé vers l'URL de rappel ou ne peut pas se placer au premier plan, l'URL de rappel doit afficher une page expliquant comment mettre votre application au premier plan et comment lancer la requête OAuthGetAccessToken à partir de votre application.

Mode de l'appareil

Si votre application ne peut pas lancer de navigateur Web complet, il est également possible pour les appareils clients rich media d'autoriser l'accès sans navigateur Web.

Ce mode permet à un développeur de configurer un site Web sur lequel un utilisateur peut autoriser la demande d'accès. Après autorisation, l'utilisateur reçoit un code généré par Google et est redirigé vers le site du développeur. Ce site doit expliquer à l'utilisateur comment saisir le code sur son appareil pour terminer le processus d'autorisation.

Mode de développement

Ce mode est recommandé uniquement pour le développement précoce d'une application.

Comme dans le mode AutoDetect, votre application doit lancer un navigateur et l'utilisateur doit autoriser votre requête. Toutefois, au lieu de créer une page Web pour l'URL de rappel, vous pouvez définir la valeur du paramètre oauth_callback sur "oob" (hors bande).

Dans ce cas, une fois que l'utilisateur a autorisé votre requête, Google le dirige vers une page "Comptes Google" affichant un numéro de validation (voir exemple).

L'utilisateur doit revenir dans votre application et saisir le numéro de validation avant que vous puissiez effectuer une requête OAuthGetAccessToken.

En savoir plus sur OAuth

Utiliser OAuth avec les bibliothèques clientes des API Google Data
Article: Utiliser OAuth avec les API Google Data, y compris Description d'OAuth Playground, un outil interactif permettant de tester OAuth
OAuth pour les applications installées (documentation complète)
Générer des clés et des certificats
Spécification OAuth

Haut de page

Utiliser AuthSub pour l'autorisation

AuthSub est une API d'autorisation propriétaire de Google, disponible à la place d'OAuth pour la plupart des API Google. Si possible, évitez d'utiliser AuthSub. Si vous possédez déjà des applications qui utilisent AuthSub, vous devez migrer vers OAuth ou le protocole hybride.

Processus d'autorisation AuthSub

L'autorisation avec AuthSub implique une séquence d'interactions entre trois entités: l'application Web, les services Google et l'utilisateur. Le schéma suivant illustre la séquence:

Processus d'autorisation

Lorsque l'application Web doit accéder au service Google d'un utilisateur, elle effectue un appel AuthSub au service Proxy d'autorisation de Google.
Le service d'autorisation répond en envoyant une page de demande d'accès. Cette page gérée par Google invite l'utilisateur à accorder ou à refuser l'accès à son service Google. L'utilisateur peut d'abord être invité à se connecter à son compte.
L'utilisateur décide d'accorder ou de refuser l'accès à l'application Web. Si l'utilisateur refuse l'accès, il est redirigé vers une page Google plutôt que vers l'application Web.
Si l'utilisateur autorise l'accès, le service d'autorisation le redirige vers l'application Web. La redirection contient un jeton d'autorisation à usage unique qui peut être échangé contre un jeton de longue durée.
L'application Web contacte le service Google avec une requête et utilise le jeton d'autorisation pour agir en tant qu'agent pour l'utilisateur.
Si le service Google reconnaît le jeton, il fournit les données demandées.

Utiliser AuthSub

L'intégration d'AuthSub dans votre application Web nécessite les tâches suivantes:

Décidez si votre application Web doit être enregistrée ou non.
Les applications Web enregistrées ont l'avantage d'être reconnues par Google. La mise en garde standard affichée pour les utilisateurs sur la page de connexion Google est modifiée ou omise. De plus, les applications Web enregistrées sont identifiées à l'aide d'un nom descriptif, au lieu de simplement l'URL d'appel. N'oubliez pas que certains services Google n'autorisent qu'un accès limité aux applications Web non enregistrées. Si vous choisissez de vous inscrire, utilisez ce processus d'inscription automatisé.

Si vous vous inscrivez, vous pouvez également fournir un certificat et des clés de sécurité. Les applications Web enregistrées qui possèdent un certificat enregistré peuvent obtenir des jetons sécurisés à utiliser lorsque vous demandez des données à un service Google. Ils peuvent également utiliser des jetons non sécurisés si nécessaire.
Déterminer le type de jetons à utiliser et la façon de les gérer
Un jeton d'autorisation reçu de Google est destiné à être utilisé pour toutes les interactions futures avec cet utilisateur pour le service Google spécifié. Le type de jeton à utiliser (session à usage unique ou session) dépend du type d'interaction de votre application Web avec un service Google. Par exemple, un jeton à usage unique peut suffire si l'interaction est ponctuelle ou rare.

Si vous choisissez d'obtenir des jetons de session et de les utiliser régulièrement pour accéder au service Google, votre application Web devra gérer le stockage des jetons, y compris le suivi de l'utilisateur et du service Google pour lesquels le jeton est valide. Les comptes Google ne sont pas configurés pour gérer un grand nombre de jetons et ne permettent pas l'utilisation de plus de 10 jetons valides par utilisateur et par application Web à la fois. Cette limitation permet à une application Web d'obtenir plusieurs jetons pour couvrir différents services, si nécessaire. Elle ne permet pas d'obtenir un nouveau jeton chaque fois que l'application Web doit accéder à un service Google. Si vous décidez de stocker des jetons de session, ceux-ci doivent être traités de manière aussi sécurisée que les autres informations sensibles stockées sur le serveur.

Vous pouvez également choisir de recevoir régulièrement de nouveaux jetons, à condition de configurer un mécanisme de révocation de jetons. Votre application doit révoquer le jeton existant avant d'en demander un autre. Dans ce scénario, l'utilisateur doit se connecter et accorder l'accès chaque fois qu'un nouveau jeton est demandé.
Déterminez le champ d'application requis pour accéder au service Google.
Chaque service Google détermine le niveau et le type d'accès qu'il autorise. Cet accès est exprimé sous la forme d'une valeur de champ d'application. Le champ d'application d'un service peut correspondre à une simple URL identifiant l'intégralité du service ou spécifier un accès plus restreint. Certains services limitent sévèrement l'accès, par exemple en autorisant l'accès en lecture seule à certaines informations. Pour connaître les champs d'application autorisés pour le service Google auquel vous souhaitez accéder, reportez-vous à la documentation de ce service. Vous devez demander le jeton le plus restreint possible. Par exemple, si vous essayez d'accéder à la fonctionnalité de flux Atom de Gmail, utilisez le champ d'application "http://www.google.com/calendar/feeds/", et non "http://www.google.com/calendar/". Les services Google sont beaucoup plus restrictifs avec les requêtes à champ d'application élevé.
Configurez un mécanisme pour demander et recevoir un jeton d'autorisation.
Le mécanisme doit générer un appel AuthSubRequest correctement formé, en spécifiant les valeurs d'URL next et scope appropriées (déterminées à l'étape 3). Si vous utilisez des jetons sécurisés et/ou gérez des jetons de session, la demande doit également inclure des valeurs pour ces variables.

L'URL suivante peut inclure des paramètres de requête. Par exemple, si plusieurs langues sont disponibles, incluez un paramètre de requête qui identifie la version de l'application Web consultée par l'utilisateur. Si la valeur de next était http://www.yoursite.com/Retrievetoken?Lang=de, la redirection serait http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. L'analyse du jeton et du paramètre Lang garantit que l'utilisateur est redirigé vers la version correcte du site.

Dans certains cas, l'utilisation du paramètre hd permet de simplifier l'expérience utilisateur lorsqu'on vous demande d'accorder l'accès sur le site Comptes Google. Dans la plupart des cas, le processus consiste à se connecter à son compte et à choisir d'accorder ou non l'accès. Les utilisateurs qui possèdent plusieurs comptes Google (un compte Gmail standard et/ou un ou plusieurs comptes hébergés Google Apps) peuvent toutefois avoir besoin de suivre la procédure de "connexion universelle" supplémentaire pour identifier le compte auquel ils souhaitent accéder. Si votre application est conçue pour un domaine géré particulier, vous pouvez éliminer ces étapes supplémentaires en identifiant ce domaine à l'aide de ce paramètre. Vous pouvez également utiliser le paramètre hd si votre application accède à des services qui ne sont pas disponibles sur les comptes hébergés. Si vous définissez la valeur sur "default", l'autorisation sera limitée aux comptes standards. Lorsque la valeur hd est définie, Google sélectionne automatiquement le compte d'autorisation approprié.

Le mécanisme de jetons doit être équipé pour analyser la redirection reçue de Google, qui contient le jeton à usage unique, et pour exécuter des actions. Les jetons d'autorisation étant spécifiques à un utilisateur, votre application doit pouvoir associer un jeton à cet utilisateur. Il est préférable d'envoyer un cookie à l'utilisateur avant d'envoyer la demande de jeton. Ensuite, lorsque Google redirige l'utilisateur vers votre site avec un jeton ajouté, votre application peut lire le cookie et associer le jeton à l'identification utilisateur correcte.
Configurez des mécanismes pour demander des jetons de session, et stockez ou révoquez ces jetons, le cas échéant.
En fonction des décisions que vous avez prises à l'étape 2 concernant la gestion des jetons, vous devrez peut-être créer des mécanismes pour obtenir et révoquer les jetons de session (AuthSubSessionToken et AuthSubRevokeToken). Pour tester les mécanismes de session et de révocation, utilisez AuthSubTokenInfo, qui indique si un jeton donné est valide ou non. Si vous stockez des jetons, l'application doit suivre à la fois l'ID utilisateur et le service (champ d'application) couvert par le jeton.
Configurez un mécanisme pour demander l'accès à un service Google.
Consultez la documentation du service Google pour en savoir plus sur le format de requête approprié. Toutes les requêtes adressées à un service Google doivent inclure un jeton d'autorisation valide. En général, une requête adressée à un service Google se présente sous la forme d'une requête HTTP GET (ou POST si l'écriture de nouvelles données) est effectuée, le jeton étant référencé dans l'en-tête de la requête.

L'en-tête de requête doit se présenter sous la forme suivante:
```
Authorization: AuthSub token="token"
```
où token est le jeton d'autorisation, à usage unique ou de session, que Google a reçu en réponse à une requête AuthSub. Si le jeton est sécurisé, il doit être accompagné d'une signature numérique. Pour obtenir des instructions et des exemples, consultez Signer des requêtes.

L'exemple ci-dessous illustre un en-tête de requête pour un appel au service de flux Google Agenda. Cette requête contient un jeton non sécurisé:
```
GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
```

En savoir plus sur AuthSub

Pour en savoir plus sur AuthSub, y compris pour enregistrer votre application auprès de Google et obtenir des explications détaillées sur l'échange d'un jeton unique contre un jeton de session, consultez les ressources suivantes:

Authentification AuthSub pour les applications Web (documentation complète)
Utiliser AuthSub avec les bibliothèques clientes des API Google Data
Générer des clés et des certificats (AuthSub sécurisé)
Signer des requêtes avec AuthSub (AuthSub sécurisé)
Inscription pour les applications Web

Haut de page

Utiliser ClientLogin pour l'autorisation

ClientLogin est une API d'autorisation propriétaire de Google, disponible à la place d'OAuth pour la plupart des API Google. Dans la mesure du possible, évitez d'utiliser ClientLogin. Si certaines de vos applications utilisent déjà ClientLogin, nous vous recommandons de passer à OAuth ou au protocole hybride.

Authentification pour les applications installées: ClientLogin

ClientLogin permet à vos utilisateurs de se connecter à leur compte Google depuis votre application. L'application contacte ensuite Google avec les données de connexion et demande l'accès à une API de données Google spécifique. Une fois les informations de connexion authentifiées, Google renvoie un jeton que votre application référence chaque fois qu'elle demande l'accès au compte de l'utilisateur, par exemple pour obtenir ou publier des données. Le jeton reste valide pendant une période définie, définie par le service Google avec lequel vous travaillez.

Remarque: Les bibliothèques clientes des API Google Data fournissent des méthodes pour vous aider à utiliser ClientLogin dans vos applications installées. Plus précisément, il existe des méthodes pour acquérir un jeton d'authentification, gérer les tests CAPTCHA, rappeler le jeton d'authentification pour une utilisation ultérieure et envoyer l'en-tête Authorization approprié à chaque requête. Si vous utilisez l'une des bibliothèques, consultez la page Utiliser ClientLogin avec les bibliothèques clientes des API Google Data.

Processus d'autorisation ClientLogin

L'autorisation avec ClientLogin implique une séquence d'interactions entre trois entités: l'application installée, les services Google et l'utilisateur. Le schéma suivant illustre la séquence:

Processus d'autorisation

Lorsque l'application tierce doit accéder au service Google d'un utilisateur, elle récupère son nom et son mot de passe de connexion.
L'application tierce passe ensuite un appel ClientLogin au service d'autorisation de Google.
Si le service d'autorisation de Google décide qu'une évaluation supplémentaire est nécessaire, il renvoie une réponse d'échec avec un jeton CAPTCHA et une question d'authentification, sous la forme d'une URL pour une image CAPTCHA.
Si un test CAPTCHA est reçu, l'application tierce affiche une image CAPTCHA pour l'utilisateur et lui demande une réponse.
Si nécessaire, l'utilisateur envoie une réponse au test CAPTCHA.
L'application tierce effectue un nouvel appel ClientLogin, cette fois avec la réponse CAPTCHA et le jeton (reçu avec la réponse d'échec).
Lors d'une tentative de connexion réussie (avec ou sans test CAPTCHA), le service d'autorisation de Google renvoie un jeton à l'application.
L'application contacte le service Google avec une demande d'accès aux données, en référençant le jeton reçu du service d'autorisation de Google.
Si le service Google reconnaît le jeton, il fournit l'accès aux données demandé.

Utiliser ClientLogin

Utilisez cette interface dans votre application installée pour accéder par programmation au compte Google d'un utilisateur. Après avoir collecté les informations de connexion de l'utilisateur, appelez ClientLogin pour demander l'accès au compte de l'utilisateur. Une fois les informations de connexion authentifiées, Google renvoie un jeton que votre application référence à chaque demande d'accès au compte de l'utilisateur. Le jeton reste valide pendant une période définie, qui est définie par le service Google avec lequel vous travaillez.

L'intégration de ClientLogin dans votre application nécessite les tâches suivantes:

Créez un élément d'interface utilisateur pour capturer les données de connexion de l'utilisateur.
L'interface utilisateur doit demander le nom d'utilisateur (adresse e-mail incluant le domaine) et le mot de passe. L'interface utilisateur doit également pouvoir afficher une image CAPTCHA à l'aide de l'URL reçue de Google, le cas échéant, et demander une réponse correcte de l'utilisateur. Idéalement, votre UI doit inclure un lien vers la page de connexion aux comptes Google ("https://www.google.com/accounts/Login") dans le cas où l'utilisateur doit créer un autre compte ou effectuer d'autres opérations de maintenance.
Écrivez le code permettant de générer une requête HTTPS POST ClientLogin bien formatée et de la transmettre.
Ce code doit contenir une logique pour gérer un test CAPTCHA, et inclure les paramètres logintoken et logincaptcha. L'application doit également être en mesure de détecter quand l'utilisateur omet les informations requises ou répète des données incorrectes après un échec de connexion, et d'afficher une erreur sans envoyer de requête superflue.
Gérer les réponses de Google
Il existe quatre réponses possibles à une demande de connexion:
- success (HTTP 200)
- échec (HTTP 403) avec un code d'erreur explicatif
- requête non valide, généralement résultant d'une requête incorrecte
- échec du test CAPTCHA
Une réponse de réussite contient un jeton d'autorisation intitulé "Auth". Ce jeton doit être inclus dans toutes les requêtes ultérieures adressées au service Google pour ce compte. Les jetons d'autorisation doivent être étroitement protégés et ne doivent être attribués à aucune autre application, car ils représentent l'accès au compte de l'utilisateur. La limite de temps associée au jeton varie en fonction du service qui l'a émis.

Une réponse d'échec comprend un ou plusieurs codes d'erreur, ainsi qu'une URL avec le message d'erreur pouvant s'afficher pour l'utilisateur. Veuillez noter que ClientLogin ne fait pas de différence entre un échec dû à un mot de passe incorrect ou un mot de passe non reconnu (par exemple, si l'utilisateur ne s'est pas encore inscrit). Votre application doit traiter tous les messages d'erreur possibles, le cas échéant.
Une réponse indiquant un échec CAPTCHA signifie que Google a décidé, pour une raison ou une autre, que des mesures de sécurité supplémentaires devaient être prises. Cette réponse est accompagnée d'une URL d'image CAPTCHA et d'un jeton représentant le test CAPTCHA.
Relevez un test CAPTCHA de Google.
Pour relever le défi, l'application doit afficher l'image CAPTCHA et demander une réponse à l'utilisateur. Pour afficher l'image CAPTCHA, utilisez la valeur de CaptchaUrl renvoyée avec la réponse d'échec, en lui ajoutant l'URL suivante : "http://www.google.com/accounts/". Une fois que l'utilisateur a fourni une réponse, l'application doit renvoyer la demande de connexion, en incluant cette fois le jeton CAPTCHA (logintoken) et la réponse de l'utilisateur (logincaptcha). Google valide la réponse de l'utilisateur avant d'autoriser l'accès au compte.

Il existe une alternative pour les développeurs qui ne souhaitent pas gérer l'obtention et la transmission d'une réponse CAPTCHA. En réponse à une question CAPTCHA, l'application peut rediriger l'utilisateur vers la page hébergée par Google : "https://www.google.com/accounts/DisplayUnlockCaptcha". Une fois que l'utilisateur a répondu correctement, le serveur Google fait confiance à l'ordinateur utilisé. L'application peut ensuite renvoyer la requête de connexion d'origine pour obtenir le jeton d'autorisation.

Remarque : Google ne valide pas la tentative de connexion avant d'envoyer une question CAPTCHA. Cela signifie qu'une tentative de connexion peut échouer même après un test CAPTCHA.

* CAPTCHA est une marque de l'université Carnegie-Mellon.

Haut de page

Authentification pour les gadgets

Proxy OAuth

Si vous créez un gadget à l'aide de l'API Google Gadgets standard, vous pouvez utiliser une fonctionnalité de la plate-forme de gadgets appelée proxy OAuth pour accéder aux API Google Data. OAuth (décrit ci-dessus) est une norme d'authentification qui permet aux utilisateurs d'accéder à leurs données privées via un service d'hébergement de gadgets tel que iGoogle, MySpace ou Orkut, ou de partager leurs données avec un autre site Web ou un autre gadget. Le proxy OAuth est conçu pour faciliter le développement des développeurs de gadgets en masquant de nombreuses informations d'authentification OAuth. Le proxy est basé sur un projet Open Source appelé Shindig, qui est une mise en œuvre de la spécification du gadget.

Remarque: Le proxy OAuth n'est pris en charge que pour les gadgets qui utilisent l'API gadgets.* et s'exécutent dans des conteneurs OpenSocial. Elle n'est pas compatible avec l'ancienne API Gadgets.

Flux d'authentification

Votre gadget doit obtenir un jeton OAuth pour pouvoir accéder aux données d'un utilisateur. Le proxy OAuth gère le flux d'authentification pour vous. La première fois qu'un utilisateur installe votre gadget, le processus suivant a lieu:

Votre gadget se charge pour la première fois et tente d'accéder aux données de l'utilisateur à l'aide de l'une des API de données Google.
La requête échoue, car l'utilisateur n'a pas accordé l'accès. L'objet de la réponse contient une URL (en response.oauthApprovalUrl) pour la page d'approbation OAuth. Votre gadget doit fournir une méthode pour lancer une nouvelle fenêtre avec cette URL.
Sur la page d'approbation, l'utilisateur choisit d'accorder ou de refuser l'accès à votre gadget. Si l'opération réussit, l'utilisateur est redirigé vers la page oauth_callback que vous spécifiez. Pour une expérience utilisateur optimale, utilisez http://oauth.gmodules.com/gadgets/oauthcallback.
L'utilisateur ferme ensuite la fenêtre pop-up. Pour avertir votre gadget que l'utilisateur a approuvé, vous pouvez utiliser un gestionnaire de pop-ups pour détecter la fermeture de la fenêtre d'approbation. Votre gadget peut également afficher un lien (par exemple, J'ai approuvé l'accès) sur lequel l'utilisateur peut cliquer après la fermeture de cette fenêtre.
Votre gadget tente à nouveau d'accéder à l'API de données Google en redemandant les données de l'utilisateur. Cette tentative a réussi.
Votre gadget est authentifié et peut fonctionner normalement.

Configuration du gadget

Pour accéder à une ou plusieurs de ces API, vous devez d'abord demander à votre gadget d'utiliser OAuth comme méthode d'authentification. Ajoutez un élément <OAuth> dans la section <ModulePrefs> du code XML de votre gadget:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

Dans cette section, modifiez uniquement les paramètres de requête suivants:

scope: Paramètre obligatoire dans l'URL de la requête. Votre gadget peut accéder aux données du ou des scope utilisés dans ce paramètre. Dans cet exemple, le gadget peut accéder aux données de Blogger et d'Agenda. Un gadget peut demander des données pour un ou plusieurs champs d'application, comme dans cet exemple.
oauth_callback: Paramètre facultatif dans l'URL d'autorisation. La page d'approbation OAuth redirige l'utilisateur vers cette URL une fois que l'utilisateur a approuvé l'accès aux données. Définissez ce paramètre sur http://oauth.gmodules.com/gadgets/oauthcallback afin d'offrir la meilleure expérience utilisateur possible lorsque les utilisateurs installent votre gadget. Cette page fournit un extrait de code JavaScript qui ferme automatiquement la fenêtre pop-up. Vous pouvez également définir ce paramètre de sorte qu'il renvoie vers votre propre page "approuvée", ou vous pouvez simplement laisser le paramètre vide.

Accéder à un flux d'API Google Data authentifié

Une fois que votre gadget a authentifié l'utilisateur, vous pouvez facilement accéder à une API Google Data grâce à la bibliothèque cliente JavaScript des API Google Data. Pour en savoir plus sur l'utilisation de la bibliothèque dans le proxy OAuth, consultez Utiliser la bibliothèque cliente JavaScript.

En savoir plus sur les gadgets

Pour obtenir des informations complètes sur la création de gadgets pour l'API Google Data, y compris des informations sur le proxy OAuth, un article de mise en route et la spécification gadgets.*, consultez les ressources supplémentaires suivantes:

Utiliser la bibliothèque cliente JavaScript
Créer un gadget d'API Google Data (article)
Écriture des gadgets OAuth (documentation complète sur les gadgets)
Documentation de l'API Gadgets

Haut de page