Skip to content

Utilisation des jetons

La plateforme Hellocare utilise des JSON Web Token (JWT) pour l'échange sécurisé des jetons avec votre système. Il est principalement utilisé pour gérer l'authentification des utilisateurs.

Structure

Un jeton se compose de trois parties:

  • Une en-tête, utilisée pour décrire le jeton. Il s'agit d'un objet JSON.
  • Un corps qui représente les informations embarquées dans le jeton. Il s'agit également d'un objet JSON.
  • Une signature numérique.

Définition des propriétés

Propriété Description Notes
iss (Issuer) Claim Clé d'API fournie par Hellocare
sub (Subject) Claim Identifiant de l'utilisateur sur votre système
aud (Audience) Claim Valeur fixe: https://id.hellocareplatform.com
exp (Expiration Time) Claim Date d'expiration du token
nbf (Not Before) Claim Date de début de validité du token
iat (Issued At) Claim Date d'émission du token
jti (JWT ID) Claim ID unique du token
https://id.hellocareplatform.com/prop/type Type d'utilisateur Hellocare PATIENT ou DOCTOR

Génération du jeton

Nous vous conseillons très fortement d'utiliser des librairies de génération du JWT pour votre language de programmation côté serveur : https://jwt.io.

Ces dernières disposent des méthodes et validateurs pour peupler le jeton et le signer.

Nous vous présentons tout de même la décomposition JSON de la structure des jetons qui devront être générés. En cas de doute sur la validité d'un jeton, n'hésitez pas à utiliser le validateur en ligne : https://jwt.io

Composition de l'en-tête (header)

L'algorithme utilisé pour la génération du jeton (alg) est RS256, c'est cette valeur qui doit figurer dans l'entête du jeton.

La proriété jti est un identifiant unique de jeton généré par votre système (un uid dans l'exemple ci-dessous).

Exemple de header 

{
  "typ": "JWT",
  "alg": "RS256",
  "jti": "867c825d-38c5-4549-88a8-ea9177d8b4f4"
}

Composition du corps (payload)

Toutes les propriétés sauf le nbf sont obligatoires lors de la génération du token. Hormis les validateurs inhérents à la gestion du token (expiration, vérification de l'audience et signature), les deux valeurs clés sont :

  • L'émetteur (iss) qui nous permet de valider que le jeton a été généré sur un système autorisé
  • Le sujet (sub) qui votre l'identifiant de l'utilisateur sur votre système. Il correspond à l'externalId qui vous sera demandé lors des appels API de création de ressources.

Exemple de payload 

{
  "iss": "7f48109c104721981da7917581eb9f88e67-test",
  "aud": "https://id.hellocareplatform.com",
  "jti": "867c825d-38c5-4549-88a8-ea9177d8b4f4",
  "iat": 1523523421,
  "nbf": 1523523481,
  "exp": 1555059421,
  "https://id.hellocareplatform.com/prop/type": "PATIENT",
  "sub": "12345678abcde"
}

Signature du token

Il vous suffit maintenant de signer le JWT en RS256 avec votre clé privée via la librairie choisie.
La signature du jeton est indispensable car elle permet de vérifier que le message n'a pas été altéré entre le moment de son émission sur votre serveur et la réception celui d'Hellocare.

Références