Utiliser OAuth avec les API Google Data

Eric Bidelman, équipe Google Data APIs
Septembre 2008

Introduction

C'est une période passionnante pour les développeurs. Un certain nombre de normes ouvertes commencent à être adoptées sur le Web, et comme vous le savez, Google s'est toujours appliqué à l'utilisation de normes et encourageait la communauté Open Source.

Récemment, toutes les API Google Data ont pris en charge OAuth, un protocole ouvert qui vise à standardiser l'accès des applications Web et de bureau aux données privées des utilisateurs. OAuth permet d'authentifier les API de manière standard et sécurisée. En tant que programmeurs, nous apprenons à réutiliser le code autant que possible. OAuth aidera les développeurs à réduire la quantité de code en double qu'ils écrivent et facilitera la création d'outils fonctionnant avec plusieurs services de différents fournisseurs.

Audience

Cet article suppose que vous connaissiez une ou plusieurs des API Google Data, mais pas nécessairement les concepts qui sous-tendent OAuth. Si vous débutez, ou si vous êtes curieux de savoir OAuth, ne cherchez plus. Cet article vous donnera les bases. Je vous présenterai également en détail la mise en œuvre du protocole OAuth de Google.

Ce document est également destiné aux développeurs qui maîtrisent l'utilisation d'AuthSub, en particulier dans le mode enregistré avec la sécurité renforcée. Tout au long du processus, j'essaierai de souligner 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 plus moderne.

Un peu de terminologie

Pour comprendre OAuth, vous devez comprendre sa terminologie. La spécification OAuth et la documentation de Google concernant l'authentification OAuth pour les applications Web reposent en grande partie sur certaines définitions. Nous allons donc clarifier la signification de chacune d'entre elles dans le contexte de la mise en œuvre OAuth de Google.

  1. "Danse OAuth"

    Mon terme non officiel décrivant le processus complet d'authentification/d'autorisation OAuth

  2. Jeton de requête (OAuth)

    Jeton initial qui indique à Google que votre application demande l'accès à l'une des API Google Data. La deuxième étape de la danse OAuth consiste à accorder manuellement à l'utilisateur l'accès à ses données. Si cette étape réussit, le jeton de demande devient autorisé.

  3. Jeton d'accès (OAuth)

    La dernière étape de la danse consiste à échanger le jeton de demande autorisé contre un jeton d'accès. Une fois que l'application dispose de ce jeton, l'utilisateur n'a pas besoin de recommencer la procédure de danse OAuth, à moins que le jeton ne soit révoqué.

    Similarité à AuthSub:
    Un jeton d'accès OAuth correspond à 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 a trois au total : une pour chaque étape du processus OAuth. Les points de terminaison OAuth de Google sont les suivants:

    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

    Similarité à AuthSub :
    L'échange d'un jeton de requête autorisé contre un jeton d'accès est semblable à la mise à niveau d'un jeton AuthSub à utilisation unique vers un jeton de session à longue durée de vie, respectivement dans https://www.google.com/accounts/AuthSubRequestToken et https://www.google.com/accounts/AuthSubSessionToken. La différence est qu'AuthSub n'a pas de concept de jeton de requête initial. Au lieu de cela, l'utilisateur lance le processus de jeton à partir de la page d'autorisation AuthSubRequestToken.

  5. Fournisseur de services (OAuth)

    Dans le cas des API Google Data, 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 également un fournisseur de services OAuth.

  6. (OAuth) Consommateur

    Programme demandant l'autorisation d'accéder aux données d'un utilisateur (c'est-à-dire votre application) Le protocole OAuth est flexible en ce sens qu'il autorise une grande variété de types de clients différents (Web, installés, bureau, mobile).

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

Premiers pas

Inscription

Vous devez effectuer quelques configurations avant de pouvoir utiliser OAuth avec les API Google Data. É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 sur la procédure à suivre, consultez les pages Enregistrer des applications Web et 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 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 avez définie 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

Format de chaîne de base base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Exemple de chaîne de base GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Exemple de requête HTTP 
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 de représentation. Votre oauth_signature sera beaucoup plus long.

Remarques concernant la chaîne de base:

  • Le paramètre de requête orderby=starttime est trié avec les autres paramètres oauth_* dans 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é au format URL double.

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 l'a fait. 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 OAuth, consultez Signer des requêtes OAuth.

Différence avec AuthSub
À titre de comparaison, voici un exemple illustrant l'utilisation d'AuthSub :

Format de chaîne de base base_string = http-method http-request-URL timestamp nonce
Exemple de chaîne de base 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Exemple de requête HTTP 
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 la page Signer des requêtes AuthSub.

Outil OAuth Playground

Objectif

Certains utilisateurs ont suggéré que le protocole OAuth présente une courbe d'apprentissage élevée. Je suis d'accord avec les autres API d'authentification de Google. L'avantage d'OAuth est évident lorsque vous développez votre application pour utiliser des services autres que Google. Rédiger un seul extrait de code d'authentification qui fonctionne avec différents fournisseurs de services et leurs API me semble assez intéressant. Vous vous remercierez plus tard pour votre apprentissage du protocole.

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

Quelles sont ses fonctionnalités ?

  1. Illustre le flux d'authentification OAuth: récupérer un jeton de requête, autoriser ce jeton et le mettre à niveau en jeton d'accès.
  2. Affiche la chaîne de base de signature appropriée pour chaque requête.
  3. Affiche l'en-tête Authorization approprié pour chaque requête.
  4. Montre comment utiliser une oauth_token pour interagir avec un flux de données Google authentifié. Vous pouvez GET/POST/PUT/DELETE données.
  5. Affichez un flux authentifié directement dans votre navigateur.
  6. Permet de tester vos propres 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.

Démonstration de course à pied

Étape 1: Choisissez vos champs d'application

Choisissez les API que vous souhaitez utiliser en choisissant une ou plusieurs portées. Dans cette démonstration, je demande un jeton qui fonctionnera avec Blogger et Google Contacts.

Similarité à AuthSub
AuthSub nécessite également le paramètre scope pour contrôler la plage de données à laquelle 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 et les paramètres OAuth

Pour l'instant, ne modifiez aucun paramètre dans la zone "Modifier les paramètres OAuth". Par la suite, vous pourrez tester 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 "Use your own private key" (Utiliser votre propre clé privée). Veuillez n'utiliser qu'une clé privée TEST.

Remarque : oauth_signature_method et oauth_consumer_key sont les seuls champs modifiables ici. oauth_timestamp, oauth_nonce et oauth_token seront automatiquement générés pour vous.

En plus de RSA-SHA1, vous pouvez choisir d'utiliser HMAC-SHA1 pour oauth_signature_method. Dans ce cas, Playground affichera des zones supplémentaires dans lesquelles vous devrez saisir votre propre oauth_consumer_key et votre code secret client. Ces valeurs se trouvent sur la page https://www.google.com/accounts/ManageDomains de votre domaine enregistré.

Différence avec 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é.

Étape 3-5: Procurez-vous le jeton d'accès

L'obtention d'un jeton d'accès OAuth s'effectue en trois étapes. La première étape consiste à récupérer un jeton de requête. Cela permet à Google de savoir que votre application lance la danse OAuth.

Tout d'abord, cliquez sur le bouton "Demander un jeton" dans la zone "Obtenir le jeton".

Certains champs seront remplis avec des données.

  • La chaîne de base de 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" contenant 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. Playground affiche également le type de oauth_token dont nous disposons actuellement. Pour le moment, il s'agit 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 "Accorder l'accès" pour autoriser le jeton de requête et être redirigé vers OAuth Playground.

Similarité à AuthSub :
Cette page d'autorisation est identique à AuthSub.

Différence avec AuthSub :
Le paramètre d'URL next d'AuthSub est analogue au paramètre oauth_callback. La différence est qu'en OAuth, oauth_callback est facultatif. Lorsque l'utilisateur clique sur le bouton "Accorder l'accès", le jeton de requête devient autorisé et la mise à niveau du jeton vers https://www.google.com/accounts/OAuthGetAccessToken peut être effectuée de manière asynchrone.

Conseil: Spécifier une URL oauth_callback est préférable si vous écrivez une application Web, car elle offre une meilleure expérience utilisateur.

Enfin, cliquez sur le bouton "Jeton d'accès" dans la zone "Obtenir le jeton".

Cette action met à niveau le jeton de requête autorisé (indiqué par le libellé rouge "jeton d'accès").

Si vous souhaitez récupérer un nouveau jeton, cliquez sur "Recommencer" pour relancer la danse OAuth.

Maintenant, on peut faire quelque chose d'intéressant !

Utiliser le jeton d'accès

Vous êtes maintenant prêt à interroger des flux, insérer, mettre à jour ou supprimer des données. Faites attention lorsque vous utilisez ces trois dernières méthodes HTTP, car vous exploitez vos données réelles !

Conseil : 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 ne renvoie pas plus de trois articles par blog. Vous pouvez également afficher le flux ou l'entrée directement dans votre navigateur en cliquant sur le lien "Afficher dans le navigateur" sous la syntaxe en surbrillance.

Exemple: Mettre à jour un post

  1. Recherchez l'élément <link> avec un rel="edit" dans le post que vous souhaitez mettre à jour. 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 "View Plain" (Afficher le texte brut) en haut du panneau de la syntaxe en surbrillance. Ne copiez que le corps de la réponse, et non les en-têtes.
  3. Dans la liste déroulante de la méthode HTTP, sélectionnez PUT.
  4. Cliquez sur "Saisir les données de publication" sous ce menu déroulant, puis collez le code XML <entry> dans le pop-up.
  5. Cliquez sur le bouton "exécuter".

Le serveur enverra une réponse 200 OK.

Conseil : Au lieu de copier manuellement le lien edit, décochez la case "Syntaxe syntaxique ?". Après une requête, vous pouvez cliquer sur les liens dans les corps de réponse XML.

Conclusion

Des technologies comme le protocole de publication AtomPub/Atom (protocole sous-jacent des API Google Data) et OAuth contribuent à faire avancer le Web. Alors que de plus en plus de sites commencent à adopter ces normes, les développeurs sont les gagnants. La création d'une application géniale devient soudainement plus intimidante.

Si vous avez des questions ou des commentaires concernant OAuth Playground, ou si vous utilisez OAuth avec les API Google, veuillez consulter le forum d'assistance consacré aux API G Suite et Marketplace.

Ressources