| Prochaine révision | Révision précédente |
| adel:utilisateurs:api-rest:implementation [2021/02/16 12:53] – créée julien.lanfrey | adel:utilisateurs:api-rest:implementation [2021/09/09 09:57] (Version actuelle) – [3 - Actualisation du ''access_token''] julien.lanfrey |
|---|
| ====== Implémentation ====== | ====== Implémentation ====== |
| |
| Il est possible d'utiliser à peu près n'importe quel langage de programmation pour utiliser l'API. Nous donnerons quelques exemples en langage Javascript avec la librairie JQuery. | Il est possible d'utiliser à peu près n'importe quel langage de programmation pour utiliser l'API. Nous donnons ci-après quelques exemples en langage Javascript, avec la librairie JQuery. |
| |
| Les communications avec l'API passent par des requêtes HTTPS GET. Le format d'échange utilisé est le format JSON. | Les communications avec l'API passent par des requêtes HTTPS GET. Le format d'échange utilisé est le format JSON. |
| |
| ===== Authentification ===== | ===== Authentification ===== |
| | |
| | **Preambule** |
| |
| Deux standards sont employés dans le but de sécuriser l'API : | Deux standards sont employés dans le but de sécuriser l'API : |
| * OAuth 2.0 JWT, avec échange de Token | * OAuth 2.0 JWT, avec échange de Token |
| |
| Le principe général est le suivant : | **Principe général** |
| - On commence par transmettre des informations d'authentification initiale à l'API (login et mot de passe). L'API vérifie les droits de la personne à utiliser l'API et, le cas échéant lui retourne un ''access_token'' et un ''refresh_token''. | - On commence par transmettre des informations d'authentification initiale à l'API (login et mot de passe). L'API vérifie les droits de la personne à utiliser l'API et, le cas échéant lui retourne un ''access_token'' et un ''refresh_token''. |
| - Le ''access_token'' est un identifiant unique qui sert de laisser-passer pour tout appel successif à l'API. Il a une durée de vie relativement courte (de l'ordre de l'heure). Au delà, un nouvel appel à l'API provoquera une erreur. | - Le ''access_token'' est un identifiant unique qui sert de laisser-passer pour tout appel ultérieur à l'API. Il a une durée de vie relativement courte (de l'ordre de l'heure). Au delà, un nouvel appel à l'API provoquera une erreur. |
| - Le ''refresh_token'' sert à demander à l'API un nouvel ''access_token'', typiquement quand ce dernier a expiré. Il a donc une durée de vie beaucoup plus longue. | - Le ''refresh_token'' sert à demander à l'API un nouvel ''access_token'', typiquement quand ce dernier a expiré. Il a donc une durée de vie beaucoup plus longue. |
| | ** |
| Pour en savoir plus sur JWT : | Pour en savoir plus sur JWT** |
| * [[https://tools.ietf.org/html/rfc7519|RFC 7519]] | * Référence [[https://tools.ietf.org/html/rfc7519|RFC 7519]] |
| * Présentation sur [[https://jwt.io/introduction|jwt.io]] | * Présentation sur [[https://jwt.io/introduction|jwt.io]] |
| * Schémas illustrant l'échange de token sur [[https://blog.ippon.fr/2017/10/12/preuve-dauthentification-avec-jwt|ce billet de blog]]. | * Schémas illustrant l'échange de token sur [[https://blog.ippon.fr/2017/10/12/preuve-dauthentification-avec-jwt|ce billet de blog]]. |
| |
| |
| ===== Exemples avec la librairie JQuery ===== | ===== Exemples avec la librairie JQuery (v3.5.1) ===== |
| | |
| Version de JQuery utilisée : 3.5.1 | |
| |
| ==== 1 - Authentification initiale ==== | ==== 1 - Authentification initiale ==== |
| $.ajax({ | $.ajax({ |
| method: 'POST', | method: 'POST', |
| url: 'https://votre/instance/adel/oauth/token', | url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/oauth/token', |
| contentType: 'application/x-www-form-urlencoded; charset=utf-8', | contentType: 'application/x-www-form-urlencoded; charset=utf-8', |
| crossDomain:true, | crossDomain:true, |
| </code> | </code> |
| |
| Si l'authentification réussie, vous obtiendrez un retour de la forme : | Si l'authentification réussit, vous obtiendrez un retour de la forme : |
| |
| <code json | Réponse> | <code json | Réponse> |
| $.ajax({ | $.ajax({ |
| method: 'GET', | method: 'GET', |
| url: 'https://votre/instance/adel/api/v1/personnes/123', | url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/api/v1/personnes/123', |
| dataType: 'json', | dataType: 'json', |
| crossDomain:true, | crossDomain:true, |
| $.ajax({ | $.ajax({ |
| method: 'POST', | method: 'POST', |
| url: 'https://votre/instance/adel/oauth/token', | url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/oauth/token', |
| contentType:'application/x-www-form-urlencoded; charset=utf-8', | contentType:'application/x-www-form-urlencoded; charset=utf-8', |
| data: { | data: { |