Chaque appel d'API doit être authentifié. Nous décrivons dans cette section les différentes manières de s'authentifier. Ces authentifications sont utilisées conjointement avec HTTPS. Dans la section "Construire le jeton" vous avez des exemples PHP liés au Payload et aux constructions des JWT.

 Restez sur la bonne voie avec notre changelog

Si vous souhaitez être averti lorsque notre équipe planifie/publie de nouvelles fonctionnalités techniques ou si vous utilisez notre API et que vous voulez vous assurer que notre nouvelle fonctionnalité ne cassera pas votre code, nous vous conseillons de vous abonner au canal changelog.

 

Sommaire

Authentification de base

Dans le contexte d'une transaction HTTPS, l'authentification "BasicAuth" est une méthode permettant à un utilisateur de fournir un nom d'utilisateur et un mot de passe lors d'une requête.

L'utilisateur dispose des mêmes accès que s'il était connecté via l'application web.

Ceci est le mieux adapté à des fins de test. Nous vous déconseillons d'utiliser des informations d'identification codées en dur dans un script ou une application.

 Attention

La possibilité d'utiliser BasicAuth pour les appels d'API doit être activée :

  • Menu utilisateur > Configuration > Sécurité > Autoriser l'appel aux API Rest via l'authentification BasicAuth

activation_BasicAuth.png

Le champ Authorization est construit comme suit :

  • Le login et le mot de passe d'un compte BoondManager séparés par deux-points ':'
  • Si le login est "test@domain.tld" et le mode de passe "test" La chaîne résultante encodée en Base64 suivant RFC3548 sera "dGVzdEBkb21haW4udGxkOnRlc3Q="
  • La méthode d'autorisation, "Basic" suivit d'un espace est alors mis avant la chaîne encodée

Exemple :

En utilisant test@domain.tld comme login et test comme mot de passe, l'en-tête serait :

Authorization : Basic dGVzdEBkb21haW4udGxkOnRlc3Q=

 

Jeton Client (JWT Client)

Le jeton Client est un jeton JWT (JSON Web Tokens) qui est utilisé pour prouver les droits d'accès pour utiliser notre API.

Les requêtes adressées à nos serveurs doivent envoyer en en-tête X-Jwt-Client-Boondmanager construit  comme suit :

  • Un header, encodé en Base64, composé de 2 parties :
    • Le type de jeton, qui est JWT
    • L'algorithme de hachage utilisé. Actuellement, BoondManager ne prend en charge que HS256:
{"alg": "HS256","type": "JWT"}
  • Un payload, encodé en Base64 également, composé de 4 parties :
    • Le jeton de l'utilisateur (userToken), qui est récupérable :
      • en décodant une signedRequest reçue de BoondManager
      • depuis un compte d'utilisateur en allant dans Configuration > Sécurité >Token utilisateur
    • Le jeton client (clientToken), disponible dans l'Espace développeur
    • L'heure de la demande sous forme de "timestamp UNIX"
    • Un mode indiquant si l'on applique les droits d'accès de l'utilisateur. Les valeurs possibles sont :
      • "normal": nous appliquerons les droits actuels de l'utilisateur
      • "god": nous n'appliquerons pas les droits de l'utilisateur et considèrerons qu'il a un accès total aux données. Veuillez l'utiliser uniquement pour les utilisateurs disposant d'un accès Admin ou très étendu dans la société (direction, RH). Certains terminaux ne sont accessibles que dans ce mode: /contrats,  /advantages, /absences, /times et /expenses.
{
"userToken": "token1",
"clientToken": "token2",
"time": 1528535249,
"mode": "normal"
}
  • Enfin, une signature utilisant l'en-tête et le payload que nous avons décrits :
    • L'en-tête encodée en Base64
    • payload encodée en Base64
    • Un hachage utilisant l'algorithme spécifié déclaré dans l'en-tête (here HS256) en utilisant la clé client comme secret. A noter que cette clé est récupérable depuis l'espace développeurs qui n'est accessible que depuis un compte administrateur.
HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload),appKey)

Si nous appliquons cet algorithme aux valeurs que nous avons utilisées comme exemples, nous obtenons un token JWT ressemblant à ceci :

X-Jwt-Client-Boondmanager: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyVG9rZW4iOiJ0b2tlbjEiLCJjbGllbnRUb2tlbiI6InRva2VuMiIsInRpbWUiOjE1Mjg1MzUyNDksIm1vZGUiOiJub3JtYWwifQ.T8hF1MqFO5sMpTdqnMhWcb1gXWpWuLWFlc6XxZN6_h8

 

 Attention

La possibilité d'utiliser X-Jwt-Client-Boondmanager pour les appels d'API doit être activée :

  • Administration > Espace Développeur > API / Sandbox > “Autoriser l’appel aux API Rest via l’authentification X-Jwt-Client“. 
Jeton d'application (JWT App)

Le jeton d'application est un jeton JWT (JSON Web Tokens) qui est utilisé pour prouver les droits d'accès pour utiliser notre API.

Les requêtes adressées à nos serveurs doivent envoyer en en-tête X-Jwt-App-Boondmanager construit  comme suit :

  • Un header, encodé en Base64, composé de 2 parties :
    • Le type de jeton, qui est JWT
    • L'algorithme de hachage utilisé. Actuellement, BoondManager ne prend en charge que HS256:
{"alg": "HS256","type": "JWT"}
  • Un payload, encodé en Base64 également, composé de 4 parties :
    • Le jeton de l'utilisateur (userToken), qui est récupérable :
      • en décodant une signedRequest reçue de BoondManager
      • depuis un compte d'utilisateur en allant dans Configuration > Sécurité >Token utilisateur
    • Le jeton d'app (App Token), reçu lors de l'installation de l'app (voir l'article Comprendre les différentes catégories d'applications, plus spécifiquement la section Premiers pas avec le développement d'applications BoondManager / Installez votre application)
    • L'heure de la demande sous forme d'horodatage UNIX
    • Un mode indiquant si l'on applique les droits d'accès de l'utilisateur. Les valeurs possibles sont :
      • "normal": nous appliquerons les droits actuels de l'utilisateur
      • "god": nous n'appliquerons pas les droits de l'utilisateur et considèrerons qu'il a un accès total aux données. Veuillez l'utiliser uniquement pour les utilisateurs disposant d'un accès Admin ou très étendu dans la société (direction, RH). Certains terminaux ne sont accessibles que dans ce mode: /contrats,  /advantages, /absences, /times et /expenses.
{
"userToken": "token1",
"appToken": "token2",
"time": 1528535249,
"mode": "normal"
}
  • Enfin, une signature utilisant l'en-tête et le payload que nous avons décrits :
    • L'en-tête encodée en Base64
    • Payload encodée en Base64
    • Un hachage utilisant l'algorithme spécifié déclaré dans l'en-tête (here HS256) en utilisant la clé client comme secret. A noter que cette clé est récupérable depuis l'espace développeurs qui n'est accessible que depuis un compte administrateur.
HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload),appKey)

Si nous appliquons cet algorithme aux valeurs que nous avons utilisées comme exemples, nous obtenons un token JWT ressemblant à ceci :

X-Jwt-App-Boondmanager: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyVG9rZW4iOiJ0b2tlbjEiLCJhcHBUb2tlbiI6InRva2VuMiIsInRpbWUiOjE1Mjg1MzUyNDksIm1vZGUiOiJub3JtYWwifQ.T8hF1MqFO5sMpTdqnMhWcb1gXWpWuLWFlc6XxZN6_h8

 

Construire le jeton

Voici un extrait PHP qui permettra de construire soit  X-Jwt-Client-Boondmanager soit X-Jwt-App-Boondmanager.

Comme nous l'avons vu, la valeur de l'en-tête est la concaténation de 3 valeurs séparées par un point '.':

function buildJWTClient() {
$payload = [
"userToken" => USER_TOKEN,
"clientToken" => CLIENT_TOKEN,
"time" => time(),
"mode" => "normal" //or "god"
];
return jwtEncode($payload, CLIENT_KEY);
}

function buildJWTApp() {
$payload = [
"userToken" => USER_TOKEN,
"appToken" => APP_TOKEN,
"time" => time(),
"mode" => "normal" //or "god"
];
return jwtEncode($payload, APP_KEY);
}

function jwtEncode($payload, $key){
$header = ['typ' => 'JWT', 'alg' => 'HS256'];
$segments = [];
$segments[] = base64UrlEncode(json_encode($header));
$segments[] = base64UrlEncode(json_encode($payload));
$signing_input = implode('.', $segments);
$signature = hash_hmac('SHA256', $signing_input, $key, true);
$segments[] = base64UrlEncode($signature);
return implode('.', $segments);
}

function base64UrlEncode($input) {
return str_replace('=', '', strtr(base64_encode($input), '+/', '-_'));
}

Vous pouvez trouver une implémentation de ces mêmes fonctions dans notre exemple d'application ici

 

Exemple de code : Générateur de jeton JWT (PHP)

Vous trouverez ci-dessous deux exemples de code commentés, pour vous aider à générer et tester votre token JWT

Il ne vous reste plus qu'à compléter le code avec vos propres tokens (token client, clé client, token utilisateur) en suivant les instructions dans les commentaires et ouvrir la page sur votre navigateur !

 

Nous espérons que cet article vous a été utile et nous vous invitons grandement à nous l'indiquer en votant juste en dessous.

S'il vous reste des questions sans réponse alors n'hésitez surtout pas à contacter notre service Support qui reste à votre écoute :

Contacter le support

Tel : (+33) 03 62 27 61 05

Boondmanager-Mascot-Desk-lg.png

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 3 sur 5

Commentaires

0 commentaire

Cet article n'accepte pas de commentaires.