Apprendre à mettre en œuvre l'authentification 3-Legged ou OAuth

Vous l'avez compris, OAuth est le nom générique que l'on donne à la « 3-Legged Authentification » ; il s'agit simplement d'une seconde appellation, plus générique. Actuellement, nous en sommes à la version 2 de ce « protocole », il s'appelle donc en réalité OAuth2.

L'usage des réseaux est rempli de protocoles, par exemple :

• HTTP (Hyper Text Transfert Protocol) sert à pouvoir consulter des sites Web ;
• FTP (File Transfert Protocol) sert à transférer des fichiers ;
• IMAP/SMTP/POP3 servent quant à eux pour les utilisations de mails ;
• etc. Il existe des centaines voire des milliers de protocoles.
  Le HTTPS et le SFTP sont des homologues à leur version sans « S » ; ils utilisent juste une couche SSL ou TLS supplémentaire pour chiffrer les transferts.

OAuth2 est un protocole de délégation d'autorisation et non d'authentification (mais nous reparlerons de cette partie un peu plus tard).

OAuth2 est maintenant un protocole standardisé par les normes RFC 6749 et [RFC 6750] depuis octobre 2012. Il est soutenu, plébiscité et implémenté par les poids lourds du Web comme Facebook ou Google.

Pour expliquer à quoi sert ce type de délégation d'autorisation, rien de mieux qu'un cas d'usage, un cas concret. Prenons donc par hasard l'API Cloud d'Orange !

Dans ce tutoriel, on a créé une application qui s'appelle « Ma Super Application ». Cette dernière a besoin d'utiliser le Cloud Orange pour gérer les fichiers de ses utilisateurs. Pour cela, Orange a créé une API (Application Programming Interface) qui permet aux applications qui l'ont demandé de proposer la plupart des fonctionnalités du Cloud Orange, un peu à la manière d'une utilisation d'un produit en marque blanche.

« Ma Super Application » a donc fait une demande et obtenu des « codes d'authentification » à l'API Cloud d'Orange.

Dans la pratique, ces codes d'authentification sont un APP_SECRET et un APP_TOKEN (appelé CLIENT_ID et CLIENT_SECRET dans la documentation de l'API d'Orange). Cette combinaison unique de chiffres et de lettres permet à « Ma Super Application » de s'authentifier auprès de l'API Cloud d'Orange. Par analogie, cette combinaison agit à la manière d'un couple Login/Mot de passe qui permette à « Ma Super Application » d'être reconnue par l'API Cloud d'Orange.

Voici un cas pratique. Disons que Jacques utilise « Ma Super Application » pour stocker ses photos personnelles dans le Cloud d'Orange. Jacques en a besoin, il se connecte donc à « Ma Super Application » pour accéder à l'arborescence de son espace Cloud.

C'est à ce moment qu'intervient OAuth2. Quand Jacques se connecte à « Ma Super Application », il lui demande d'accéder à son Cloud via l'API d'Orange. Mais ça, Jacques, il n'en a pas conscience (sauf lors de sa première connexion, il devra se connecter à son compte Orange Cloud et sera donc invité à s'identifier en saisissant son login/mot de passe de compte Cloud).

Ensuite, « Ma Super Application » va lancer une requête (demande d'accès à l'espace de Jacques) à l'API Cloud d'Orange qui utilise le protocole OAuth2. L' API va lui répondre « Oui, mais qu'est-ce qui me prouve que Jacques veut bien que toi, « Ma Super Application », tu accèdes à ses données personnelles ? ». Voilà le rôle de OAuth2 : c'est un protocole de délégation d'autorisation.

OAuth2 vient distinguer quatre rôles parfaitement distincts, c'est ce qui fait de lui le système de délégation d'autorisation le plus sécurisé à ce jour.

• Le Resource Owner (détenteur des données) : dans notre exemple, c'est Jacques. En effet, Jacques est propriétaire de ses fichiers sur le Cloud, mais aussi de son adresse email, ses informations personnelles, etc. C'est le premier des « three legs ».
• Le Resource Server (serveur de ressources) : dans notre exemple, c'est l'endroit où sont stockés les fichiers personnels et les informations de Jacques. C'est donc le serveur de stockage du Cloud Orange. Il s'agit du second des « three legs ».

Les deux dernières ressources représentent le troisième des « three legs ». Ce sont :

• Le Client Application (client) : dans notre exemple, il s'agit de « Ma Super Application ». C'est « Ma Super Application » qui demande à avoir l'accès aux informations et fichiers de Jacques.
• Le Authorization Server (serveur d'autorisation) : c'est le serveur d'autorisation de l'API Cloud d'Orange. C'est lui qui délivre les accès à « Ma Super Application ». Attention, il ne le fait que sur autorisation de Jacques ! Et si Jacques veut y mettre fin, c'est ce serveur qui révoquera les accès.

L'utilisateur (Jacques) dispose d'un tableau de contrôle, en se connectant sur le site Cloud Orange, de l'ensemble des autorisations qu'il a laissées et à quelles applications ces dernières ont été attribuées. Il peut, en se connectant à ce tableau de bord, révoquer n'importe quelle autorisation à tout moment.

Dans la pratique, l'Authorization Server et le Resource Server sont souvent le même serveur (la même machine). Il peut s'agir de séparation physique ou logique, cela n'a aucune importance.

Quand le Resource Owner (Jacques) sollicite « Ma Super Application » pour utiliser son Cloud Orange, il se rend d'abord dans l'interface de « Ma Super Application ». De là, s'en suivent les étapes suivantes :

1. « Ma Super Application », au moyen de l'API d'autorisation, demande au serveur d'autorisation de bien vouloir authentifier Jacques, puis lui demande s'il accepte que « Ma Super Application » accède à ses données. L'API retourne alors à « Ma Super Application » un lien de connexion pointant vers une page de demande de consentement (générée par le serveur d'autorisation). Jacques s'authentifie et y donne son consentement pour un « scope » prédéfini par le Cloud d'Orange. Un « scope » est l'étendue des droits demandés (par exemple : lire, lire et écrire dans un répertoire particulier, dans tous les répertoires…).
   Il s'agit là de la seule intervention de Jacques sur tout le processus de consentement de partage de données ;
2. Jacques s'est authentifié et a accepté que « Ma Super Application » accède à ses informations. L'Authorization Server délivre alors à « Ma Super Application » un jeton identifiant unique, valable pour une durée déterminée. Ce jeton permet alors à « Ma Super Application » de passer à l'étape 3 et 4 ;
3. « Ma Super Application » fournit alors à l'API d'Orange Cloud le jeton qui lui a été attribué et lui demande de bien vouloir lui transmettre les informations de la personne qui s'est connectée et correspondant à ce jeton (et là, nous parlons bien de Jacques) ;
4. L'API Orange Cloud renvoie les informations demandées (listes des répertoires, contenus des répertoires, etc.).

L'avantage principal de cette solution de consentement de partage de données est que Jacques n'a jamais transmis ses identifiants de Cloud d'Orange à « Ma Super Application ». Il lui a autorisé l'accès pendant un temps déterminé par l'intermédiaire du serveur d'autorisation. À chaque connexion de Jacques, ce temps d'autorisation sera renouvelé.

Le temps d'autorisation dépend des serveurs, des API… Il est en général de quelques heures, permettant ainsi de conserver l'utilisation suffisamment longtemps, sans toutefois laisser la porte ouverte trop longtemps non plus.

Cette première étape consiste à vérifier que votre utilisateur est authentifié sur les services d'Orange. Pour cela, il vous suffit de constituer une URL et de rediriger votre utilisateur dessus. Cette URL doit être de la forme suivante :

https://api.orange.com/oauth/v2/authorize?scope=openid%20Cloud&response_type=code&client_id=VOTRE_CLIENT_ID&state=state&redirect_uri=http%3A%2F%2Fwww.masuperapplication.com

Dans ce cas précis, vous obtiendrez l'ensemble des droits requis pour gérer le Cloud de Jacques (ou de votre client bien sûr).

Votre utilisateur arrivera donc sur la page de connexion Orange Cloud.Une fois authentifié, il sera redirigé sur la page spécifiée dans votre redirect_uri :

http://www.masuperapplication.com/?code=OFR-251f7...716a727f&state=state

Il ne vous reste plus qu'à récupérer ce code, puis à demander un token à l'API Cloud d'Orange.

curl -X POST \
     -H "Authorization: Basic NktSSHl...UdnlrT2lOaA==" \
     -d "grant_type=authorization_code \ &code=OFR-251f7...716a727f \
     &redirect_uri=http://www.masuperapplication.com" \
     https://api.orange.com/oauth/v2/token

La valeur de “Authorization : Basic” est en fait base64encode(”CLIENT_ID”:”APP_SECRET”)

Vous obtenez alors un retour de ce type :

{
 "token_type":"Bearer",
 "access_token": "OFR-948ef...d5de1f4",
 "expires_in":3600,
 "scope":"openid Cloud",
 "refresh_token": "OFR-fa78dfb0dcf01…ff5c", 
 "id_token": "eyJ0eX9….xCN7KiBNYiSAPd0XEs" 
}

C'est fait : vous avez votre access_token, il ne vous reste plus qu'à lancer la requête sur l'API avec votre access_token pour obtenir les données tant convoitées.

Par exemple, pour obtenir le contenu de la racine, la requête est la suivante :

curl -X GET \
     -H "Authorization: Bearer MON_ACCESS_TOKEN..." \
     https://api.orange.com/Cloud/v1/folders/restrictedmode

et la réponse est de cette forme :

{
 "id": "VHlwZSAob3IgcGFzdGUpIGhlcmUuLi4=",
 "parentId": "Lw==",
 "name": "MyBeautifulApp",
 "files":
 [{
  "id": "dmlkZW9EZWZhdWx0Lm1wNA==",
  "name": "videoDefault.mp4",
  "type": "VIDEO"
  },
  { "id": "cGRmRGVmYXV0LnBkZg==",
    "name": "pdfDefaut.pdf",
    "type": "FILE"
  },
  {
    "id": "aW1hZ2VEZWZhdXQyLmpwZw==",
    "name": "imageDefaut2.jpg",
    "type": "PICTURE"
  }],
 "subfolders":
  [{
  "id": "X191cGxvYWQv",
  "name": "__upload"
 }] 
}

Maintenant, vous pouvez utiliser l'ensemble des API qui utilisent les données personnelles avec le consentement du client final, par exemple les API Cloud, Check Id, Form Filling ou encore Direct Carrier Billing d'Orange.