Utiliser OAuth avec les API Google Data

Introduction

C'est une période passionnante pour les développeurs. Nous commençons à voir un certain nombre de normes ouvertes adoptées sur le Web. Comme vous le savez, Google a toujours été un grand fan des normes et de la promotion de la communauté Open Source.

Récemment, toutes les API Google Data ont adopté la compatibilité avec OAuth, un protocole ouvert qui vise à standardiser la façon dont les applications de bureau et Web accèdent aux données privées d'un utilisateur. OAuth permet d'authentifier les API de manière standard et sécurisée. En tant que programmeurs, nous apprenons à réutiliser le code chaque fois que cela est possible. OAuth aidera les développeurs à réduire la quantité de code en double qu'ils écrivent et à créer plus facilement des outils fonctionnant avec plusieurs services de différents fournisseurs.

Audience

Cet article part du principe que vous connaissez au moins une des API Google Data, mais pas nécessairement les concepts d'OAuth. Si vous débutez ou que vous êtes simplement curieux d'en savoir plus sur OAuth, vous êtes au bon endroit. Cet article vous permettra d'acquérir des connaissances de base sur les concepts. Nous aborderons également les détails de l'implémentation OAuth de Google.

Ce document est également destiné aux développeurs qui connaissent l'utilisation d'AuthSub, en particulier en mode enregistré avec sécurité renforcée. Au fur et à mesure, j'essaierai de mettre en évidence les similitudes et les différences entre les deux protocoles. Si vous avez des applications qui utilisent AuthSub, vous pouvez utiliser ces informations pour migrer vers OAuth, un protocole plus ouvert et moderne.

Quelques termes

Pour comprendre OAuth, vous devez d'abord comprendre sa terminologie. La spécification OAuth et la documentation Google sur l'authentification OAuth pour les applications Web reposent fortement sur certaines définitions. Clarifions donc ce que chacune d'elles signifie dans le contexte de l'implémentation OAuth de Google.

1. "OAuth dance"

   Terme non officiel que j'utilise pour décrire l'ensemble du processus d'authentification/d'autorisation OAuth.

2. (OAuth) Jeton de requête

   Jeton initial qui indique à Google que votre application demande l'accès à l'une des API Google Data. La deuxième étape du processus OAuth consiste pour l'utilisateur à accorder manuellement l'accès à ses données. Si cette étape aboutit, le jeton de requête est autorisé.

3. Jeton d'accès (OAuth)

   La dernière étape consiste à échanger le jeton de requête autorisé contre un jeton d'accès. Une fois que votre application dispose de ce jeton, un utilisateur n'a plus besoin de suivre la procédure OAuth, sauf si le jeton est révoqué.

   Similitude avec AuthSub :
   Un jeton d'accès OAuth est identique à un jeton de session AuthSub sécurisé.

4. Points de terminaison (OAuth)

   Il s'agit des URI requis pour authentifier une application et obtenir un jeton d'accès. Il y en a trois au total, une pour chaque étape du processus OAuth. Voici les points de terminaison OAuth de Google :

   Obtenez un jeton de requête :	https://www.google.com/accounts/OAuthGetRequestToken
   Autorisez le jeton de requête :	https://www.google.com/accounts/OAuthAuthorizeToken
   Passer à un jeton d'accès :	https://www.google.com/accounts/OAuthGetAccessToken

   Similitude avec AuthSub :
   L'échange d'un jeton de requête autorisé contre un jeton d'accès est analogue à la mise à niveau d'un jeton AuthSub à usage unique en jeton de session de longue durée sur https://www.google.com/accounts/AuthSubRequestToken et https://www.google.com/accounts/AuthSubSessionToken, respectivement. La différence est qu'AuthSub ne dispose pas du concept de jeton de requête initial. L'utilisateur lance plutôt le processus de jeton à partir de la page d'autorisation AuthSubRequestToken.

5. Fournisseur de services (OAuth)

   Dans le cas des API Données Google, ce fournisseur est Google. En général, le fournisseur de services est utilisé pour décrire le site Web ou le service Web qui fournit les points de terminaison OAuth. MySpace est un autre exemple de fournisseur de services OAuth.

6. Consommateur (OAuth)

   Programme demandant l'autorisation d'accéder aux données d'un utilisateur (c'est-à-dire votre application). Le protocole OAuth est flexible et permet une grande variété de types de clients (Web, installés, pour ordinateur, mobiles).

Remarque : Bien que le protocole OAuth soit compatible avec le cas d'utilisation des applications de bureau/installées, Google n'accepte OAuth que pour les applications Web.

Premiers pas

Inscription

Avant de pouvoir utiliser OAuth avec les API Google Data, vous devez effectuer une petite configuration. Étant donné que toutes les requêtes OAuth doivent être signées numériquement, vous devez d'abord enregistrer votre domaine et importer un certificat public dans Google. Pour en savoir plus, consultez Registration for Web-Based Applications (Enregistrement pour les applications Web) et Generating keys and certificates for use with registered mode (Générer des clés et des certificats à utiliser avec le mode enregistré).

Signer les requêtes

Une fois votre domaine enregistré, vous pouvez commencer à signer des requêtes. L'un des concepts les plus difficiles d'OAuth est de savoir comment construire correctement le oauth_signature et la notion de chaîne de base de signature. La chaîne de base correspond aux données que vous signez avec votre clé privée (à l'aide de RSA_SHA1). Le résultat est la valeur que vous définissez pour oauth_signature.

Exemple de requête

GET une liste des agendas Google d'un utilisateur à l'adresse http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime ;

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Remarque : Il s'agit uniquement d'une représentation. Votre oauth_signature sera beaucoup plus long.

Remarques sur la chaîne de base :

• Le paramètre de requête orderby=starttime est trié avec le reste des paramètres oauth_* selon l'ordre lexicographique des valeurs d'octet.
• Cette chaîne ne contient pas non plus le caractère "?".
• La partie base-http-request-url ne contient que l'URL de base encodée au format URL : http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
• oauth_token est encodé deux fois au format URL.

Remarques sur l'en-tête Authorization :

• L'ordre des paramètres oauth_* n'a pas d'importance dans l'en-tête Authorization.
• L'en-tête n'inclut pas orderby=starttime comme la chaîne de base. Ce paramètre de requête est conservé dans l'URL de la requête.

Pour en savoir plus sur la signature des requêtes à l'aide d'OAuth, consultez Signer des requêtes OAuth.

Différence avec AuthSub :
À titre de comparaison, voici le même exemple utilisant AuthSub sécurisé :

GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Pour en savoir plus sur la signature des requêtes à l'aide d'AuthSub, consultez Signer des requêtes AuthSub.

Outil OAuth Playground

Essayez !

Objectif

Certains utilisateurs ont suggéré qu'OAuth avait une courbe d'apprentissage élevée. Je suis d'accord avec cette affirmation par rapport aux autres API d'authentification de Google. L'avantage d'OAuth deviendra évident lorsque vous étendrez votre application pour utiliser d'autres services (non Google). Écrire un seul code d'authentification qui fonctionne avec différents fournisseurs de services et leurs API, ça me semble plutôt bien. Vous vous féliciterez d'avoir appris le protocole maintenant.

Le bac à sable OAuth est un outil que j'ai créé pour aider les développeurs à résoudre leurs problèmes OAuth. Vous pouvez utiliser le Playground pour déboguer des problèmes, vérifier votre propre implémentation ou tester les API Google Data.

Quel est le rôle de cette solution ?

1. Illustre le flux d'authentification OAuth : récupération d'un jeton de requête, autorisation du jeton et conversion en jeton d'accès.
2. Affiche la chaîne de base de signature correcte pour chaque requête.
3. Affiche l'en-tête Authorization approprié pour chaque requête.
4. Montre comment utiliser un oauth_token pour interagir avec un flux de données Google authentifié. Vous pouvez accéder aux données GET/POST/PUT/DELETE.
5. Affichez un flux authentifié directement dans votre navigateur.
6. Vous permet de tester votre propre oauth_consumer_key (votre domaine enregistré) et votre clé privée.
7. Découvrez les services de flux de données Google disponibles pour votre oauth_token.

Exécution de la démo

Étape 1 : Choisissez vos Scopes Commencez par choisir les API que vous souhaitez utiliser en sélectionnant un ou plusieurs scopes. Dans cette démonstration, je demande un jeton qui fonctionnera avec Blogger et Google Contacts. Similitude avec AuthSub : AuthSub nécessite également le paramètre scope pour contrôler la plage de données auxquelles un jeton peut accéder. Google a implémenté ce paramètre comme suggéré dans la spécification OAuth.
Étape 2 : Modifiez les paramètres OAuth Pour le moment, ne modifiez aucun paramètre dans la zone "Modifier les paramètres OAuth". Vous pourrez ensuite effectuer des tests avec votre propre clé privée en remplaçant oauth_consumer_key par votre domaine enregistré et en saisissant votre clé privée en cliquant sur "Utiliser votre propre clé privée". Veuillez n'utiliser qu'une clé privée TEST. Remarque : Seuls les champs oauth_signature_method et oauth_consumer_key peuvent être modifiés ici. Les oauth_timestamp, oauth_nonce et oauth_token seront générés automatiquement pour vous. En plus de RSA-SHA1, vous pouvez choisir d'utiliser HMAC-SHA1 pour oauth_signature_method. Dans ce cas, le Playground affichera des zones supplémentaires dans lesquelles vous devrez saisir votre propre oauth_consumer_key et votre code secret client. Vous trouverez ces valeurs sur la page https://www.google.com/accounts/ManageDomains de votre domaine enregistré. Différence par rapport à AuthSub : Dans AuthSub sécurisé, il n'existe aucun paramètre permettant de définir explicitement un nom de domaine. Le domaine est inclus dans le paramètre d'URL next. Il existe un paramètre de ce type dans OAuth : oauth_consumer_key. Définissez-le sur votre domaine enregistré.
Étapes 3 à 5 : Obtenez le jeton d'accès Pour obtenir un jeton d'accès OAuth, vous devez suivre trois étapes. La première étape consiste à récupérer un jeton de requête. Cela indique à Google que votre application démarre le flux OAuth. Tout d'abord, cliquez sur le bouton "Request token" (Demander un jeton) dans la section "Get the Token" (Obtenir le jeton). Certains champs seront préremplis avec des données. La section "Chaîne de base de la signature" affiche la forme appropriée de la chaîne de base utilisée pour créer le paramètre oauth_signature. L'en-tête "Authorization" affiche l'en-tête Authorization correspondant à la requête. La zone "Modifier les paramètres OAuth" est remplie avec les valeurs oauth_nonce et oauth_timestamp envoyées dans la requête. L'entrée oauth_token a été renseignée avec la valeur correspondante renvoyée dans le corps de la réponse. L'atelier de programmation affiche également le type de oauth_token dont nous disposons actuellement. Il s'agit actuellement d'un jeton de requête.
Cliquez ensuite sur le bouton "Authorize" (Autoriser) dans la zone "Get the token" (Obtenir le jeton). Sur cette page d'autorisation, cliquez sur le bouton "Grant Access" (Accorder l'accès) pour autoriser le jeton de requête et être redirigé vers OAuth Playground. Similitude avec AuthSub : Cette page d'autorisation est la même pour AuthSub. Différence par rapport à AuthSub : Le paramètre d'URL next d'AuthSub est analogue au paramètre oauth_callback. La différence est que dans OAuth, oauth_callback est facultatif. Une fois que l'utilisateur a cliqué sur le bouton "Accorder l'accès", le jeton de requête est autorisé et la mise à niveau du jeton vers https://www.google.com/accounts/OAuthGetAccessToken peut être effectuée de manière asynchrone. Conseil : Il est préférable de spécifier une URL oauth_callback si vous écrivez une application Web, car cela améliore l'expérience utilisateur.
Enfin, cliquez sur le bouton "Access token" (Jeton d'accès) dans la section "Get the Token" (Obtenir le jeton). Cette action met à niveau le jeton de requête autorisé (comme indiqué par le libellé rouge "jeton d'accès"). Si vous souhaitez récupérer un nouveau jeton, cliquez sur "Recommencer" pour relancer le processus OAuth. Nous pouvons maintenant faire quelque chose d'intéressant !

Utiliser le jeton d'accès

Vous êtes maintenant prêt à interroger les flux, à insérer, mettre à jour ou supprimer des données. Veuillez faire attention lorsque vous effectuez ces trois dernières méthodes HTTP, car vous travaillez avec vos données réelles.

Remarque : Pour découvrir les flux disponibles pour votre jeton d'accès, cliquez sur le bouton "Flux disponibles".

Voici un exemple de requête : GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Cet exemple renvoie au maximum trois posts sur un blog spécifique. Vous pouvez également afficher le flux/l'entrée renvoyé directement dans votre navigateur en cliquant sur le lien "Afficher dans le navigateur" sous la zone de syntaxe mise en surbrillance.

Exemple : Modifier un post

1. Localisez l'élément <link> avec un rel="edit" dans le post que vous souhaitez modifier. Il devrait ressembler à ceci :

   <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

   Collez l'URL href dans le champ "Saisissez un flux de données Google".

2. Copiez le code XML de l'entrée existante en cliquant sur "Afficher le texte brut" en haut du panneau de mise en surbrillance de la syntaxe. Ne copiez que le corps de la réponse, pas les en-têtes.
3. Définissez la méthode HTTP sur PUT dans le menu déroulant.
4. Cliquez sur "enter post data" (saisir les données du post) sous ce menu déroulant, puis collez le code XML <entry> dans le pop-up.
5. Cliquez sur le bouton "Exécuter".

Le serveur répondra avec un code 200 OK.

Conseil : Au lieu de copier manuellement le lien edit, décochez la case "Syntax Highlight?" (Mise en surbrillance de la syntaxe ?). Après une requête, vous pourrez cliquer sur les liens dans les corps de réponse XML.

Conclusion

Des technologies telles que le protocole de publication AtomPub/Atom (protocole sous-jacent des API Google Data) et OAuth contribuent à faire progresser le Web. À mesure que de plus en plus de sites adoptent ces normes, nous, les développeurs, sommes gagnants. Créer une application révolutionnaire devient soudainement moins intimidant.

Si vous avez des questions ou des commentaires sur OAuth Playground ou sur l'utilisation d'OAuth avec les API Google, veuillez nous contacter sur le forum d'assistance des API G Suite et Marketplace.

Ressources

• Authentification OAuth pour les applications Web
• Liste des API Google Data
• Forum de discussion sur les API Comptes Google
• Spécification principale OAuth 1.0