Ces pages de documentation doivent vous permettre d'intégrer votre ESUP-SGC dans le projet ESC (European Student Card).
Ces pages sont avant tout techniques ; pour une bonne compréhension du projet, merci de vous référer au site officiel : https://europeanstudentcard.eu
Le projet de carte étudiante européenne comporte plusieurs volets techniques que nous allons aborder un par un :
Impression et utilisation du QR-Code
Présentation
Pour fonctionner, ESUP-SGC imprime puis encode la carte en 2 étapes successives et distinctes.
Pour réaliser l’enrôlement de la carte au moment de l'encodage après impression, un qr-code est utilisé.
Ce qr-code correspond au qr-code standardisé/normalisé par le projet ESC.
C'est là le premier usage que fait ESUP-SGC du QR-Code de la carte européenne.
Le QR-Code européen consiste en une url dans laquelle on retrouve l'url d'accès au serveur ESC http://esc.gg/ suivi d'un numéro de carte 'ESCN' qui est un identifiant codé en hexadécimal, formaté pour une meilleur lecture avec des - supplémentaires.
Exemple : 50228de1-8944-1038-a3d5-001999465982
Cet ESCN est construit pour être unique, ESUP-SGC utilise directement la librairie escn-generator disponible depuis les repositories centraux de maven (le code source y est également donné) : https://search.maven.org/artifact/eu.europeanstudentcard/escn-generator
Cet identifiant de carte est construit via l'heure système suffixé d'un code qui correspond au pic de l'établissement lui-même préfixé par un numéro supplémentaire.
Dans l'exemple de 50228de1-8944-1038-a3d5-001999465982 on retrouve ainsi le code pic 999465982 de l'Université de Rouen Normandie.
On note que la "version" hexadecimal correspond à 50228de189441038a3d5001999465982, soit une chaîne hexadecimale de 16 octets.
ESUP-SGC ne propose pas cependant d'utiliser le QR-Code pour identifier la carte dans un usage courant après édition.
ESUP-SGC préfère en effet l'usage du sans-contact au scan de QR-Code.
Mise en oeuvre
La configuration de la génération de ce QR-Code se fait dans src/main/resources/META-INF/spring/applicationContext-crous.xml
<bean id="escUidFactoryService" class="org.esupportail.sgc.services.esc.EscUidFactoryService"> <property name="pic" value="le-code-pic-de-letablissement"/> <property name="prefixe" value="1 " /> <!-- si plusieurs sgc, l'établissement doit les distinguer par un préfixe différent --> <property name="qrCodeUrlPrefixe" value="http://esc.gg/" /> <!-- pour l'instance ESC de pre-production on mettra http://pp.esc.gg/ --> </bean>
On active l'utilisation du QR6Code européen (en lieu de l'usage de l'EPPN en tant que QR6Code) en allant dans l'interface web, "Admin" > "Configurations" > "QRCODE_ESC_ENABLED" que l'on doit mettre à true.
Enregistrement d'une carte dans ESC-R
Présentation
Pour que la carte puisse être reconnue par un service d'un établissement européen partenaire, il faut que celui-ci puisse la récupérer techniquement depuis ESCR qui est la plateforme d'échange (le hub ou Router) des identifiants de cartes/étudiants du projet ESC.
Enregistrer une carte c'est donc enregistrer à la fois l'étudiant et la carte dans ESCR.
ESUP-SGC permet à ce que ce soit sur demande de l'étudiant que l'enregistrement ait lieu (RGPD). Ensuite, ESCR elle-même propose à l'étudiant de diffuser au cas par cas ses identifiants aux services des établissements partenaires.
L'identifiant de carte est l'ESCN.
L'identifiant de l'utilisateur est construit ainsi : code pays - code pic - code ine.
La connaissance de l'INE est donc obligatoire ici.
Mise en oeuvre
La configuration d'esup-sgc en tant que client ESCR pour enregistrer les cartes se fait dans src/main/resources/META-INF/spring/applicationContext-crous.xml
<bean id="europeanStudentCardService" class="org.esupportail.sgc.services.esc.ApiEscrService"> <property name="enable" value="true"/> <property name="webUrl" value="http://api.europeanstudentcard.eu/v1" /> <property name="key" value="clef-a-recuperer-auprès-d-escr" /> <property name="restTemplate" ref="restTemplate" /> <property name="countryCode" value="FR"/> <property name="picInstitutionCode" value="le-code-pic-de-letablissement"/> <!-- Type of cards. Possibles values are : 1 - passive card, with no electronic 2 - Smartcard without European common data zone 3 - Smartcard with European common data zone 4 - Smartcard on which application may be installed by service providers --> <property name="cardType" value="2"/> </bean>
Pour proposer à certains "userType" (populations) d'utilisateurs d'activer leur carte dans ESCR, il faut renseigner le paramètre DISPLAY_FORM_EUROPEAN_CARD dans l'interface web, "Admin" > "Configurations".
Le paramètre ENABLE_EUROPEAN_CARD permet quant à lui de sélectionner les userType pour lesquels on active par défaut la carte dans ESCR.
Récupération d'une carte depuis ESC-R
Présentation
Pour qu'une carte extérieure puisse être reconnue par ESUP-SGC, il faut déclarer ESUP-SGC dans ESCR.
Ainsi ESUP-SGC sera présenté aux étudiants adhérents au dispositif ESC, et ils pourront accepter que leur carte et informations personnelles soient transmises à votre ESUP-SGC.
Mise en oeuvre
Depuis votre interface ESCR https://router.europeanstudentcard.eu/remote-service en tant que gestionnaire, vous pouvez déclarer une application compatible ESCR.
Au niveau d'esup-sgc, vous pouvez mettre dans security.properties
accessRestrictionWSescr=hasHeader('escr-key','123456789ABCDEF')
Notez qu'à la fois le nom de l'entête http (escr-key ici) et sa valeur (123456789ABCDEF) sont libres. Il faudra simplement reporter les mêmes dans l'interface ESCR.
En supposant que votre ESUP-SGC est accessible en https://esup-sgc.univ-ville.fr, vous devrez ainsi remplir les champs demandés lors de l'enregistrement de votre service ainsi :
- API root url : https://esup-sgc.univ-ville.fr/wsescr
- Api Key Header name : escr-key
- Api Key : 123456789ABCDEF
- Activation Endpoint : /activate
- Deactivation Endpoint : /deactivate
- Card added Endpoint : /addcard
- Card deleted Endpoint : /deletecard
- Student updated Endpoint : /updatestudent
- Student deleted Endpoint : /deletestudent