Implémentation

Ceci est une ancienne révision du document !

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.

Preambule

Deux standards sont employés dans le but de sécuriser l'API :

HTTP Basic Authentication
OAuth 2.0 JWT, avec échange de Token

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.
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.

Pour en savoir plus sur JWT

Référence RFC 7519
Présentation sur jwt.io
Schémas illustrant l'échange de token sur ce billet de blog.

Authentification : /oauth/token

$.ajax({
    method: 'POST',
    url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/oauth/token',
    contentType: 'application/x-www-form-urlencoded; charset=utf-8',
    crossDomain:true,
    dataType: 'json',
    data: {
        grant_type: 'password',
        username: 'xxxxx',      // Login Adel
        password: 'xxxxx',      // Mot de passe Adel
        client_id: 'xxxxx',     // Basic-auth : id
        client_secret: 'xxxxx'  // Basic-auth : mot de passe
    },
    success: function (data) {
        console.log('success', data);
    },
    error: function (e) {
        console.log('error', e.responseText);
    }
});

Si l'authentification réussit, vous obtiendrez un retour de la forme :

Réponse

{
 "access_token": "azertyiJIhyhyNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImV4cCI6MTYxMjU0NDA1MSwiYXV0aG9yaXRpZXMiOlsic3lzX2dsb2JhbF9hZG1pbmlzdHJlciIsIlJPTEVfc3lzX2FkbWluIl0sImp0aSI6IjJiV1lwdEazertyXJ4Nm1hSSIsImNsaWVudF9pZCI6Imp3dGNsaWVudGlkIn0.x6gJRCbsOVVkpnsYduVL9QldGK0qPgW-Hql8mjcqBiQ",
 "token_type": "bearer",
 "refresh_token": "azertyzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImF0aSI6IjJiV1lwdEQ0QkdaSXJqaFplYTlpTXJ4Nm1hSSIsImF1dGhvcml0aWVzIjpbInN5c19nbG9iYWxfYWRtaW5pc3RyZXIiLCJST0xFX3N5c19hZG1pbiJdLCJqdGkiOiJvd1RkamQwZ3dUTU51MTg3ckNPRlRxT0ZwWHMiLCJjbGllbnRfaWQiOiJqd3RjbGllbnRpZCJ9.hT4WZ5yjloX5zH0Ko6c7WaTWD-ImGQYlmFxsInHVQqU",
 "expires_in": 3559,
 "scope": "read write trust",
 "jti": "azertyD4BGZIrjhZea9iMrx6maI"
}

Vous êtes désormais en mesure d'appeler les différentes routes de l'API en transmettant le access_token à chaque appel.

Appel de /api/v1/personnes/123

$.ajax({
    method: 'GET',
    url: 'https://secure.bayard-service.com/annuaire_VOTRENOM/api/v1/personnes/123',
    dataType: 'json',
    crossDomain:true,
    data: {},
    beforeSend: function (xhr) {
        xhr.setRequestHeader('Authorization','Bearer ' + store.access_token);        
    },
    success: function (data) {
        console.log('success', data);
    },
    error: function (e) {
        console.log('error', e.responseText);
    }
});

Si vous utilisez votre access_token alors que ce dernier a expiré, qu'il n'est plus valide, vous obtiendrez un retour d'erreur de ce type :

Utilisation d'un access_token invalide

{"error":"invalid_token","error_description":"Access token expired: azertyiJIhyhyNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImV4cCI6MTYxMjU0NDA1MSwiYXV0aG9yaXRpZXMiOlsic3lzX2dsb2JhbF9hZG1pbmlzdHJlciIsIlJPTEVfc3lzX2FkbWluIl0sImp0aSI6IjJiV1lwdEazertyXJ4Nm1hSSIsImNsaWVudF9pZCI6Imp3dGNsaWVudGlkIn0.x6gJRCbsOVVkpnsYduVL9QldGK0qPgW-Hql8mjcqBiQ"}

Si votre access_token est invalide, vous devez en demander un nouveau en utilisant le refresh_token.

Actualisation du token : /oauth/token

$.ajax({
    method: 'POST',
    url: 'https://secure.bayard-service.com/annuaire_VOTRENOM/oauth/token',
    contentType:'application/x-www-form-urlencoded; charset=utf-8',
    data: {
        grant_type: 'refresh_token',
        refresh_token: store.refresh_token, // Le refresh_token
        client_id: 'xxxxx',                 // Basic-auth : id
        client_secret: 'xxxxx'              // Basic-auth : mot de passe
    },
    success: function (data) {
        console.log('success', data);
    },
    error: function (e) {
        console.log('error', e.responseText);
    }
});

Le retour est similaire à celui obtenu lors de l'authentification initiale.

Implémentation

Authentification

Exemples avec la librairie JQuery (v3.5.1)

1 - Authentification initiale

2 - Utilisation de l'API

3 - Actualisation du ''access_token''

ADEL