Bienvenue sur le HelpDesk de Keepeek

Articles dans cette section

OAuth 2 / Token JWT

Présentation

Cette fonctionnalité est disponible depuis la version 4.28.0 du backoffice et elle permet d'utiliser
l'API Keepeek avec le protocole OAuth2.
Pour cela, à chaque appel API, on utilise un token JWT (JSON Web Token / ID Token) contenant l'identité de l'utilisateur (le login Keepeek).


Cinématique

Contexte : une application souhaite utiliser l'API Keepeek en OAuth 2

  1. L'application génère un token JWT contenant un login Keepeek et signe ce token en utilisant
    une clef privée (qui est également connue de Keepeek)
  2. Sur chaque appel API Keepeek, l'application positionne dans le header "Authorization" le
    token JWT de cette façon : Bearer <token>
  3. Keepeek détecte qu'un token JWT est utilisé et vérifie sa validité : on utilise la même clef
    privée pour valider le token.
  4. Le token est valide : l'utilisateur est authentifié et peut utiliser l'API

Génération / signature du token

Pour générer un token JWT, il existe de nombreux clients disponibles pour plusieurs langages de programmation (voir la page ici : https://jwt.io/#libraries-io)

Pour signer un token, il existe plusieurs algorithmes :

  • HMAC : une clef privée est partagée entre l'application et Keepeek
  • RSA : clef privée avec clef publique

Actuellement, seul le HMAC est supporté par Keepeek et doit au minimum utiliser du SHA256.
Le HMAC se base sur une clef privée pour signer/valider un token. Il est donc nécessaire de
partager la même clef entre Keepeek et l'application qui a signé le token.

 

⚠️ ATTENTION : il est nécessaire que la clef privée soit uniquement composée de
caractères alphanumériques.

 

Un token JWT est découpé en plusieurs parties :

  • Un header
  • Un payload (les claims)
  • La signature

Pour tester / valider un token, vous pouvez utiliser le site suivant : http://jwt.io/

Voici un exemple de token Keepeek valide :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJrZWVwZWVrLXRlc3QiLCJs
b2dpbiI6ImR1cG9uZCIsImlhdCI6MTYxNjIzOTAyMiwiZXhwIjoxNjE5NTk5MDIyfQ.Dq9kHJpoEi
4s_GpOqI2-9ytglUVmKz5wS02LXaRMK0I

 

Voici un exemple de code en JAVA basé sur la librairie "https://github.com/auth0/java-jwt" permettant la génération d'un token JWT :

Builder builder = JWT.create();
builder.withClaim("client_id", "mon-instance-keepeek");
builder.withClaim("login", "dupond");
builder.withIssuedAt(new Date());
builder.withExpiresAt(new Date(System.currentTimeMillis() + 1000 * 60));
String token = builder.sign(Algorithm.HMAC512(secretKey));

Articles associés