Intégration carte étudiante
- Former user (Deleted)
- Former user (Deleted)
- Former user (Deleted)
Procédure de validation du QR code affiché sur la carte étudiante AppScho
La carte étudiante d'AppScho peut, en plus du visuel de la carte, afficher un QR code permettant de scanner et valider la carte présentée par un utilisateur et les informations qu'elle contient.
Ce QR code est :
signé cryptographiquement
limité dans le temps
La partie affichage doit regénérer le QR code régulièrement afin que celui-ci continue à être vérifié. Si un QR code invalide ou expiré est scanné, celui-ci sera rejeté automatiquement.
La procédure ci-dessous décrit l'algorithme à suivre afin de valider un QR code scanné.
Nous partons du prédicat que le QR code a déjà été scanné et que vous êtes en possession de son contenu sous forme de chaîne de caractère. Egalement, aucun exemple de code ne sera fourni, il est de la responsabilité de l'établissement de rechercher les méthodes d'implémentation pour chaque concept évoqué ici pour ses langages et plateformes respectifs.
Il est recommandé de choisir une librairie établie, reconnue et maintenue pour tout ce qui touche à la cryptographie.
QR code et JWT
Chaque QR code généré pour la carte étudiante d'AppScho contient un jeton JWT qui contient toutes les informations nécessaires pour la vérification des informations affichées.
Ce JWT est signé à l'aide de l'algorithme ES256 (ECDSA avec P-256 et SHA-256). Cet algorithme de chiffrement asymétrique basé sur les courbes elliptiques permet ici de signer la valeur avec une clé privée gérée par AppScho tout en permettant à quiconque de vérifier sa validité avec une clé publique mise à disposition.
Les données contenues dans le JWT ressemblent à ceci (la partie supérieure correspond à l'en-tête, la partie inférieure à la payload) :
En-tête
{
"alg": "ES256",
"kid": "Wpn+0mxthk+5ZLsyBGRhnw==",
"typ": "JWT"
}Contenu
{
"bc": "0197456712",
"c": "demo",
"exp": 1602080318,
"jti": "33f04486-4190-4dfb-86ab-2d47bdf40584",
"n": "Amandine CLÉMENT",
"t": 0,
"u": "01974567A-12"
}Récupération de l'ID de clé
Les JWT peuvent théoriquement être signés à l'aide de différentes clés au fil du temps. Afin de déterminer quelle clé publique utiliser pour la validation, il s'agit de décoder l'en-tête du JWT et de récupérer la valeur de l'attribut "kid" (key ID). Dans l'exemple ci-dessus, notre ID de clé est Wpn+0mxthk+5ZLsyBGRhnw==.
Il est possible de récupérer toutes les clés publiques valides à un instant donné en requêtant l'API à cette URL, en fonction de votre environnement :
Beta/Production : https://api.appscho.com/<id>/idcard/pubkeys
L'ID à renseigner ici vous sera fourni par AppScho. Si cette API vous renvoie une erreur, le scanner de carte étudiante n'est probablement pas activé pour votre établissement. Veuillez vous rapprocher d'AppScho pour résoudre cela.
Cette API renvoie des données sous ce format :
{
"response": [
{
"kid": "Wpn+0mxthk+5ZLsyBGRhnw==",
"x5c": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAER2MMLwxo0baYhy8E/gvA+Hz0gz/js54BQRa9e6TacFl
}
],
"state": "ok",
"timestamp": "2020-10-07 14:22:25 +0000"
}Vous retrouverez, dans l'attribut response, la liste des clés publiques actives pour votre établissement. En comparant leurs "kid" avec celui du JWT scanné, vous pouvez obtenir la clé publique indiqué dans l'attribut "x5c".
La clé publique est fourni au format PEM sans en-tête. Il s'agit ici de reconstruire la clé publique ECDSA à l'aide de sa représentation au format PEM.
En fonction des langages et librairies utilisés, il est possible que vous deviez ajouter les en-tête et en-pieds PEM adéquats ( -----BEGIN PUBLIC KEY----- et -----END PUBLIC KEY----- ).
Validation du JWT
La librairie utilisée pour valider le JWT devrait se charger elle-même de vérifier les propriétés cryptographiques du jeton ainsi que la date d'expiration (indiquée dans l'attribut "exp").
A votre tour, deux valeurs doivent absolument être vérifiée afin de garantir la fiabilité du processus :
La valeur d'en-tête "alg" est égal à la chaîne de caractères "ES256".
La valeur de l'attribut "c" est égale à l'ID utilisé dans l'URL d'appel à l'API utilisé pour récupérer la clé publique.
Si tous ces éléments sont au vert, vous avez validé que le QR code scanne a bien été généré par AppScho, pour votre établissement, et que celui-ci est toujours valide.
Lecture des attributs
Le jeton étant signé, vous pouvez être certain que les données qui y sont n'ont pas été modifiée par l'utilisateur. Ainsi, vous pouvez, à l'heure actuelle, récupérer les attributs suivants (veuillez noter que certains attributs peuvent être manquants si non-applicables ou non-existants) :
u : identifiant de l’utilisateur
bc : numéro du code bar de l'utilisateur
n : nom complet de l'utilisateur
t : type d'utilisateur (0 pour un étudiant, 1 pour un professeur, 2 pour un personnel administratif)
num : numéro / identifier étudiant
bir : date de naissance de l'étudiant
yea : année scolaire
exp : date d’expiration de la carte étudiante
mor : liste de champs personnalisés