Authentification et autorisation dans le protocole de données Google

Avertissement : Cette page concerne les anciennes API Google, les API Google Data. Elle n'est pertinente que pour les API listées dans le répertoire des API Google Data, dont beaucoup ont été remplacées par des API plus récentes. 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 ont souvent besoin d'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 comporte 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 d'accorder à votre application l'accès aux données qu'ils ont stockées dans les applications Google. Google prend la confidentialité au sérieux. Toute application qui nécessite d'accéder aux données d'un utilisateur doit être autorisée par celui-ci.

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

L'authentification et l'autorisation pour les 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 à votre application.

• Google Sign-In permet aux utilisateurs de se connecter facilement à votre site à l'aide de leurs identifiants Google. Il inclut 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 de demander à votre application de procéder directement à la 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 leur demandant de se connecter avec leur compte Google. Il s'agit d'un remplacement d'OpenID. Les utilisateurs d'OpenID doivent prévoir de migrer vers Se connecter avec OAuth 2.0.

Les services obsolètes AuthSub, ClientLogin et OAuth 1.0 sont disponibles comme alternatives à OAuth 2.0 pour certaines API Google. Comme nous l'avons annoncé en 2012, ces services obsolètes seront arrêtés le 20 avril 2015. Si vous possédez déjà des applications qui les utilisent, vous devez migrer vers OAuth 2.0.

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

Remarque : Ce document a pour objectif de présenter chaque méthode d'authentification. Pour obtenir des informations détaillées sur chaque méthode, consultez la documentation complète des API d'authentification du compte Google.

Consultez également le groupe de l'API Comptes Google pour discuter de l'utilisation des API Comptes Google.

OAuth : autorisation pour les applications Web et installées

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

Google accepte deux versions d'OAuth pour obtenir un accès autorisé aux données Google d'un utilisateur : OAuth 1.0 et OAuth 2.0. Les deux versions offrent 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 OAuth 2.0 simplifié pour autoriser l'accès aux données associées à un compte Google. Pour obtenir des informations et des exemples sur l'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 Google Apps peuvent utiliser l'implémentation de l'API OAuth de Google. 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 permettant d'autoriser l'utilisation des données dans les applications Web. Toutes les applications Web qui envoient des requêtes OAuth doivent importer un certificat de sécurité et s'enregistrer auprès de Google. Pour en savoir plus, consultez Enregistrement 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 requête, autoriser le jeton de requête 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 lors de l'envoi de requêtes à un service de données Google. Pour obtenir des exemples détaillés sur l'utilisation d'OAuth avec les bibliothèques clientes des Google Data APIs,consultez Utiliser OAuth avec les bibliothèques clientes des Google Data APIs.

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.

En termes simples, le processus est le suivant :

1. Votre application demande l'accès et obtient un jeton de requête non autorisée auprès du serveur d'autorisation de Google.
2. Google demande à l'utilisateur de vous autoriser à accéder aux données requises.
3. Votre application obtient un jeton de requête autorisé auprès du serveur d'autorisation.
4. Vous échangez le jeton de requête autorisé contre un jeton d'accès.
5. 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 fournit un jeton de requête non autorisée.

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 les données du service Google auxquelles 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 valable qu'une heure. Seul un jeton de requête autorisé peut être échangé contre un jeton d'accès, et 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 d'utilisateur indiqué dans la demande d'autorisation d'origine et n'accorde l'accès qu'aux services spécifiés dans cette demande. Votre application doit stocker le jeton d'accès de manière sécurisée, car il est requis pour tout accès aux données d'un utilisateur.

Se préparer à OAuth

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

Déterminer si vous devez enregistrer votre application Web

Pour rassurer davantage vos utilisateurs quant à la sécurité de leurs données, vous pouvez choisir d'enregistrer votre application Web auprès de Google et de signer vos requêtes avec le certificat de sécurité enregistré. Certains flux de l'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 envoie. Si vous choisissez d'utiliser une signature RSA-SHA1 pour signer vos requêtes, vous devez importer un certificat de sécurité lors de l'enregistrement.

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

Pour en savoir plus sur la procédure d'enregistrement, consultez Enregistrement des applications Web.

Déterminer le champ d'application des données auxquelles votre application accédera

Chaque service Google définit des limites d'accès via les API Google Data. Cet accès est exprimé sous la forme d'une valeur de champ d'application. Certains services fournissent différentes valeurs de portée pour permettre à un utilisateur de choisir les applications qui 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 règle générale, vous devez demander un jeton pour le champ d'application le plus restreint qui inclut 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 de gestion des jetons OAuth

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

Votre application doit gérer le stockage des jetons de manière sécurisée, y compris en suivant 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 ne peuvent être en attente à un moment donné.

Si votre application accepte plusieurs comptes utilisateur, vous devez suivre le compte auquel chaque jeton est associé. Chaque jeton OAuth est spécifique à l'utilisateur qui a autorisé l'accès. Votre application doit être en mesure d'associer un jeton à l'utilisateur approprié. Une façon de gérer cela consiste à émettre un cookie pour l'utilisateur avant d'envoyer la demande 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 envoyé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 en savoir plus sur le format de requête approprié pour chaque API Google Data, consultez la documentation de cette API.

Implémenter OpenID (facultatif)

Si vous implémentez 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 les extensions OAuth. Comme pour OAuthGetRequestToken, ces extensions permettent d'identifier les services Google auxquels accéder. Une réponse positive à la requête OpenID contient un jeton de requête autorisée. 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 demande de jeton signés et bien formés, et gérer les réponses, pour la séquence suivante :

1. Obtenir un jeton de requête non autorisé (OAuthGetRequestToken)
2. Autoriser le jeton de requête (OAuthAuthorizeToken)
3. Échangez 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 une documentation détaillée, consultez la documentation de référence sur 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 qu'il a 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, lorsque vous prenez en charge plusieurs langues, vous pouvez inclure un paramètre de requête qui identifie la version de l'application que l'utilisateur consulte. Une valeur oauth_callback de "http://www.yoursite.com/Retrievetoken?Lang=de" entraînerait la redirection "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". L'analyse du jeton et du paramètre de langue permet de s'assurer que l'utilisateur est redirigé vers la bonne version 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 l'exemple) après avoir autorisé votre demande d'accès. L'utilisateur doit revenir manuellement à votre application et saisir le numéro de validation avant 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 lorsqu'il demande l'autorisation d'accès à l'utilisateur (voir l'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 "anonymous".

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 de votre nom à afficher enregistré et inclura un message indiquant que l'identité de votre application ne peut pas être vérifiée.

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

Utiliser 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 lors de l'autorisation d'un jeton. Pour en savoir plus sur le paramètre hd, consultez Gérer les utilisateurs disposant de plusieurs comptes.

En savoir plus sur OAuth

Pour en savoir plus sur l'implémentation d'OAuth par Google, y compris sur l'enregistrement de votre application et la création des 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 une description d'OAuth Playground, un outil interactif pour tester OAuth.
• OAuth pour les applications Web (documentation complète)
• S'inscrire aux applications Web
• Générer des clés et des certificats
• Spécification OAuth

Haut de page

Utiliser OAuth avec des applications installées

Toutes les API Google Data sont compatibles avec OAuth, une norme ouverte permettant d'autoriser l'utilisation des données dans les applications. Les applications installées n'ont pas besoin d'ê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.

En termes simples, le processus est le suivant :

1. Votre application demande l'accès et obtient un jeton de requête non autorisée auprès du serveur d'autorisation de Google.
2. Google demande à l'utilisateur de vous autoriser à accéder aux données requises.
3. Votre application obtient un jeton de requête autorisé auprès du serveur d'autorisation.
4. Vous échangez le jeton de requête autorisé contre un jeton d'accès.
5. 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 fournit un jeton de requête non autorisée.

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 les données du service Google auxquelles 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 valable qu'une heure. Seul un jeton de requête autorisé peut être échangé contre un jeton d'accès, et cet échange ne peut être effectué qu'une seule fois par jeton de requête autorisé.

OAuth est compatible avec les applications installées en mode non enregistré. Comme 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 de navigateur Web.

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 d'utilisateur indiqué dans la demande d'autorisation d'origine et n'accorde l'accès qu'aux services spécifiés dans cette demande. Votre application doit stocker le jeton d'accès de manière sécurisée, car il est requis pour tout accès aux données d'un utilisateur.

Se préparer à OAuth

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

Déterminer le champ d'application des données auxquelles votre application accédera

Chaque service Google définit des limites d'accès via les API Google Data. Cet accès est exprimé sous la forme d'une valeur de champ d'application. Certains services fournissent différentes valeurs de portée pour permettre à un utilisateur de choisir les applications qui 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 règle générale, vous devez demander un jeton pour le champ d'application le plus restreint qui inclut 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 de gestion des jetons OAuth

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

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

Si votre application accepte plusieurs comptes utilisateur, vous devez suivre le compte auquel chaque jeton est associé.

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

Chaque requête envoyé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 en savoir plus sur le format de requête approprié pour chaque API Google Data, consultez la documentation de cette API.

Utiliser des jetons OAuth

Pour utiliser OAuth, votre application doit générer des appels de demande de jeton signés et bien formés, et gérer les réponses, pour la séquence suivante :

1. Obtenir un jeton de requête non autorisé (OAuthGetRequestToken)
2. Autoriser le jeton de requête (OAuthAuthorizeToken)
3. Échangez 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 une documentation détaillée, consultez la documentation de référence sur l'API OAuth.

Identifier votre application auprès des utilisateurs

Google affiche normalement le nom d'une application lorsqu'il demande l'autorisation d'accès à l'utilisateur (voir l'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 "anonymous".

Remarque : Pour définir le paramètre xoauth_displayname dans OAuth Playground, cochez la case "Advanced" (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 ensuite se connecter à une page Web Google et autoriser la demande d'accès de votre application.

• Le mode AutoDetect 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 Détection automatique

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

Ce mode nécessite que vous fournissiez une URL de rappel vers laquelle l'utilisateur est redirigé après avoir autorisé votre demande d'accès. Cette URL doit être fournie en tant que paramètre oauth_callback de la requête OAuthGetRequestToken et en tant que 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, puis se mettre immédiatement au premier plan et envoyer une requête OAuthGetAccessToken pour terminer le processus OAuth.

Pour en savoir plus et découvrir les bonnes pratiques, consultez Détection automatique de l'approbation.

Si votre application ne peut pas détecter automatiquement quand l'utilisateur est redirigé vers l'URL de rappel, ou ne peut pas se mettre 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 depuis votre application.

Mode de l'appareil

Si votre application ne peut pas lancer un navigateur Web complet, il est également possible pour les appareils client riche d'autoriser 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. Une fois l'autorisation accordée, 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é pour les premières étapes du développement d'une application uniquement.

Comme en mode AutoDetect, votre application doit lancer un navigateur et l'utilisateur doit autoriser votre demande. 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 demande, Google le redirige vers une page de compte Google affichant un numéro de validation (voir l'exemple).

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

En savoir plus sur OAuth

Pour en savoir plus sur l'implémentation d'OAuth par Google, y compris sur l'enregistrement de votre application et la création des 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 une description d'OAuth Playground, un outil interactif pour 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 comme alternative à OAuth pour la plupart des API Google. Si possible, évitez d'utiliser AuthSub. Si vous avez 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 :

1. Lorsque l'application Web doit accéder à un service Google d'un utilisateur, elle effectue un appel AuthSub au service de proxy d'autorisation de Google.
2. Le service d'autorisation répond en affichant une page de demande d'accès. Cette page gérée par Google invite l'utilisateur à autoriser ou refuser l'accès à son service Google. Il peut d'abord être demandé à l'utilisateur de se connecter à son compte.
3. 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 au lieu de revenir à l'application Web.
4. Si l'utilisateur accorde l'accès, le service d'autorisation le redirige vers l'application Web. La redirection contient un jeton d'autorisation valable pour une seule utilisation, qui peut être échangé contre un jeton de longue durée.
5. L'application Web contacte le service Google avec une requête, en utilisant le jeton d'autorisation pour agir en tant qu'agent pour l'utilisateur.
6. Si le service Google reconnaît le jeton, il fournit les données demandées.

Utiliser AuthSub

Pour intégrer AuthSub à votre application Web, vous devez effectuer les tâches suivantes :

1. Décidez d'enregistrer ou non votre application Web.

   Les applications Web enregistrées ont l'avantage d'être reconnues par Google. L'avertissement standard affiché aux utilisateurs sur la page de connexion Google est modifié ou omis. De plus, les applications Web enregistrées sont identifiées par un nom descriptif plutôt que par l'URL appelante. 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 cette procédure d'inscription automatisée.

   Si vous vous inscrivez, vous pouvez également fournir un certificat et des clés de sécurité. Les applications Web enregistrées avec un certificat dans le fichier peuvent acquérir des jetons sécurisés à utiliser lors de la demande de données à un service Google. (Ils peuvent également utiliser des jetons non sécurisés si nécessaire.)

2. Décidez du type de jetons à utiliser et de la façon de les gérer.

   Un jeton d'autorisation reçu de Google est destiné à être utilisé pour toutes les futures interactions avec le service Google spécifié pour cet utilisateur. Le type de jeton que vous choisissez d'utiliser (à usage unique ou de session) dépend du type d'interactions que votre application Web aura avec un service Google. Par exemple, un jeton à usage unique peut suffire si l'interaction est un événement ponctuel 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 lequel le jeton est valide. Les comptes Google ne sont pas conçus pour gérer un grand nombre de jetons. En fait, ils n'autorisent pas plus de dix jetons valides (par utilisateur et par application Web) en même temps. Cette limite 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, ils doivent être traités avec le même niveau de sécurité que toute autre information sensible stockée sur le serveur.

   Vous pouvez également choisir d'obtenir de nouveaux jetons régulièrement, à condition de configurer un mécanisme de révocation des jetons. Votre application devra révoquer le jeton existant avant d'en demander un autre. Dans ce cas, l'utilisateur devra se connecter et accorder l'accès chaque fois qu'un nouveau jeton sera demandé.

3. Déterminez le champ d'application requis par le service Google auquel vous souhaitez accéder.

   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 être une simple URL identifiant l'ensemble du service ou il peut spécifier un accès plus restreint. Certains services limitent considérablement l'accès, par exemple en autorisant l'accès en lecture seule à des informations limitées. Pour obtenir les niveaux d'accès autorisés pour le service Google auquel vous souhaitez accéder, consultez la documentation de ce service. Vous devez demander le jeton le plus limité possible. Par exemple, si vous tentez 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 demandes à grande portée.

4. Configurez un mécanisme pour demander et recevoir un jeton d'autorisation.

   Le mécanisme doit générer un appel AuthSubRequest bien formé, y compris 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 requête doit également inclure des valeurs pour ces variables.

   L'URL suivante peut inclure des paramètres de requête. Par exemple, lorsque vous prenez en charge plusieurs langues, incluez un paramètre de requête qui identifie la version de l'application Web que l'utilisateur consulte. Une valeur next de http://www.yoursite.com/Retrievetoken?Lang=de entraînerait la redirection http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. L'analyse du jeton et du paramètre "Lang" permet de s'assurer que l'utilisateur est redirigé vers la bonne version du site.

   Dans certains cas, l'utilisation du paramètre hd peut aider à simplifier l'expérience de vos utilisateurs lorsqu'ils sont invités à accorder l'accès sur le site des comptes Google. Dans la plupart des cas, il leur suffit de se connecter à leur compte et de choisir d'accorder ou non l'accès. Toutefois, les utilisateurs qui possèdent plusieurs comptes Google (un compte Gmail standard et/ou un ou plusieurs comptes hébergés Google Apps) devront peut-être 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é spécifique, vous pouvez éliminer ces étapes supplémentaires en utilisant ce paramètre pour identifier ce domaine. 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 uniquement. Lorsque la valeur hd est définie, Google sélectionne automatiquement le bon compte pour l'autorisation.

   Le mécanisme de jeton doit être en mesure d'analyser la redirection reçue de Google, qui contient le jeton à usage unique, et d'agir en conséquence. Étant donné que les jetons d'autorisation sont spécifiques à un utilisateur, votre application doit être en mesure d'associer un jeton à son utilisateur. L'option recommandée consiste à émettre un cookie pour 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 de l'utilisateur appropriée.

5. Configurez des mécanismes pour demander des jetons de session, et les stocker ou les révoquer, le cas échéant.

   En fonction des décisions que vous avez prises concernant la gestion des jetons à l'étape 2, 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 elle stocke des jetons, l'application doit suivre à la fois l'ID utilisateur et le service (champ d'application) couvert par le jeton.

6. 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 envoyée à un service Google se présente sous la forme d'une requête HTTP GET (ou POST si vous écrivez de nouvelles données), avec le jeton référencé dans l'en-tête de la requête.

   L'en-tête de la requête doit se présenter comme suit :

   Authorization: AuthSub token="token"

   où token est le jeton d'autorisation, à usage unique ou de session, reçu de Google 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 sur l'enregistrement de votre application auprès de Google et sur l'échange d'un jeton à usage unique contre un jeton de session, consultez les ressources supplémentaires 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é)
• S'inscrire aux applications Web

Haut de page

Utiliser ClientLogin pour l'autorisation

ClientLogin est une API d'autorisation propriétaire de Google, disponible comme alternative à OAuth pour la plupart des API Google. Si possible, évitez d'utiliser ClientLogin. Si vous disposez déjà d'applications qui utilisent ClientLogin, vous devez migrer vers OAuth ou le 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 Google Data spécifique. Une fois les informations de connexion authentifiées, Google renvoie un jeton auquel votre application fera référence chaque fois qu'elle demandera l'accès au compte de l'utilisateur, par exemple pour obtenir ou publier des données. Le jeton reste valide pendant une durée déterminée, définie par le service Google que vous utilisez.

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 obtenir 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 correct avec chaque requête. Si vous utilisez l'une des bibliothèques, consultez 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 :

1. Lorsque l'application tierce doit accéder à un service Google d'un utilisateur, elle récupère son nom d'utilisateur et son mot de passe.
2. L'application tierce effectue ensuite un appel ClientLogin au service d'autorisation de Google.
3. Si le service d'autorisation Google décide qu'une validation supplémentaire est nécessaire, il renvoie une réponse d'échec avec un jeton et un test CAPTCHA, sous la forme d'une URL pour une image CAPTCHA.
4. Si un test CAPTCHA est reçu, l'application tierce affiche l'image CAPTCHA pour l'utilisateur et lui demande de répondre.
5. Si demandé, l'utilisateur envoie une réponse au test CAPTCHA.
6. L'application tierce effectue un nouvel appel ClientLogin, cette fois en incluant la réponse et le jeton CAPTCHA (reçus avec la réponse d'échec).
7. Lors d'une tentative de connexion réussie (avec ou sans test CAPTCHA), le service d'autorisation Google renvoie un jeton à l'application.
8. L'application contacte le service Google avec une demande d'accès aux données, en faisant référence au jeton reçu du service d'autorisation Google.
9. 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 de manière programmatique au compte Google d'un utilisateur. Après avoir collecté les informations de connexion de l'utilisateur, appelez ClientLogin pour demander l'accès à son compte. Une fois les informations de connexion authentifiées, Google renvoie un jeton auquel votre application fera référence chaque fois qu'elle demandera l'accès au compte de l'utilisateur. Le jeton reste valide pendant une durée définie par le service Google que vous utilisez.

Pour intégrer ClientLogin à votre application, vous devez effectuer les tâches suivantes :

1. Créez un élément d'interface utilisateur pour capturer les données de connexion de l'utilisateur.

   L'UI doit demander un nom d'utilisateur (adresse e-mail incluant le domaine) et un mot de passe. L'UI doit également être capable d'afficher une image CAPTCHA à l'aide de l'URL reçue de Google, si nécessaire, et de demander à l'utilisateur de fournir la bonne réponse. Dans l'idéal, votre UI inclura un lien vers la page de connexion aux comptes Google ("https://www.google.com/accounts/Login") au cas où l'utilisateur aurait besoin de créer un compte ou d'effectuer d'autres opérations de maintenance sur son compte.

2. Écrivez du code pour générer une requête HTTPS POST ClientLogin bien formée et la transmettre.

   Ce code doit contenir une logique permettant de gérer un test CAPTCHA et inclure les paramètres logintoken et logincaptcha. L'application doit également être en mesure de détecter lorsque l'utilisateur omet des 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.

3. Gérez les réponses de Google.

   Il existe quatre réponses possibles à une demande de connexion :

   • réussite (HTTP 200)
   • échec (HTTP 403) avec un code d'erreur explicatif.
   • Demande incorrecte, généralement due à une requête mal formée
   • Échec d'un test CAPTCHA

   Une réponse positive contient un jeton d'autorisation intitulé "Auth". Ce jeton doit être inclus dans toutes les requêtes ultérieures envoyées au service Google pour ce compte. Les jetons d'autorisation doivent être protégés et ne doivent pas être fournis à d'autres applications, car ils représentent l'accès au compte de l'utilisateur. La limite de temps du jeton varie en fonction du service qui l'a émis.

   Une réponse d'échec inclut un ou plusieurs codes d'erreur et une URL avec le message d'erreur qui peut être affiché pour l'utilisateur. Veuillez noter que ClientLogin ne fait pas la différence entre un échec dû à un mot de passe incorrect et un échec dû à un nom d'utilisateur non reconnu (par exemple, si l'utilisateur n'a pas encore créé de compte). Votre application doit gérer tous les messages d'erreur possibles de manière appropriée.

   Une réponse d'échec avec un test CAPTCHA signifie que Google a décidé, pour une raison quelconque, 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 spécifique.

4. Répondez à 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 la préfixant avec l'URL des comptes Google : "http://www.google.com/accounts/". Une fois que l'utilisateur a fourni une réponse, l'application doit renvoyer la demande de connexion, cette fois en incluant 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 le processus d'obtention et de transmission de la réponse CAPTCHA d'un utilisateur. En réponse à un test 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 au défi, le serveur Google fait confiance à l'ordinateur utilisé. L'application peut ensuite renvoyer la demande de connexion d'origine pour obtenir le jeton d'autorisation.

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

* CAPTCHA est une marque déposée de la Carnegie Mellon University.

Haut de page

Authentification pour les gadgets

Proxy OAuth

Si vous créez un gadget à l'aide de l'API 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 dans un service d'hébergement de gadgets tel qu'iGoogle, MySpace ou Orkut, ou de partager leurs données avec un autre site Web ou gadget. Le proxy OAuth est conçu pour faciliter le développement des gadgets en masquant de nombreux détails d'authentification OAuth. Le proxy est basé sur un projet Open Source appelé Shindig, qui est une implémentation de la spécification des gadgets.

Remarque : Le proxy OAuth n'est compatible qu'avec les gadgets qui utilisent l'API gadgets.* et qui 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 avant de 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 se déroule :

1. 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 Google Data.
2. La requête échoue, car l'utilisateur n'a pas accordé l'accès. L'objet de réponse contient une URL (dans response.oauthApprovalUrl) pour la page d'approbation OAuth. Votre gadget doit fournir une méthode pour lancer une nouvelle fenêtre avec cette URL.
3. 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.
4. L'utilisateur ferme ensuite la fenêtre pop-up. Pour informer votre gadget que l'utilisateur a approuvé l'accès, vous pouvez utiliser un gestionnaire de pop-up pour détecter la fermeture de la fenêtre d'approbation. Vous pouvez é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.
5. Votre gadget tente d'accéder à l'API Google Data une deuxième fois en demandant à nouveau les données de l'utilisateur. Cette tentative réussit.
6. Votre gadget est authentifié et peut commencer à fonctionner normalement.

Configuration du gadget

Pour accéder à une ou plusieurs API Google Data, vous devez d'abord indiquer à votre gadget d'utiliser OAuth comme méthode d'authentification. Ajoutez un élément <OAuth> dans la section <ModulePrefs> du fichier 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, ne modifiez que 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 des scope utilisés dans ce paramètre. Dans cet exemple, le gadget peut accéder aux données Blogger et Agenda. Un gadget peut demander des données pour un ou plusieurs niveaux d'accès, comme dans cet exemple.

oauth_callback

 : paramètre facultatif dans l'URL d'autorisation. La page d'approbation OAuth redirige vers cette URL une fois que l'utilisateur a approuvé l'accès aux données. Vous devez définir ce paramètre sur http://oauth.gmodules.com/gadgets/oauthcallback pour 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 pour qu'il pointe vers votre propre page "approuvée" ou le laisser vide.

Accéder à un flux authentifié de l'API Google Data

Une fois que votre gadget a authentifié l'utilisateur, l'accès à une API Google Data est simple avec la bibliothèque cliente JavaScript des API Google Data. Pour savoir comment utiliser 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 Google Data API, y compris des détails sur le proxy OAuth, un article sur la façon de commencer et la spécification gadgets.*, consultez les ressources supplémentaires suivantes :

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

Haut de page