Introduction
Cette application permet de gérer le cycle de vie des cartes NFC de votre établissement, de la demande à sa désactivation en passant par son impression, encodage et activation dans votre système d'information.
Cette application fonctionne via une authentification/identification Shibboleth et en lien avec une instance esup-nfc-tag-server
Plan du document
Concepts
Afin de mettre en œuvre le système de gestion de carte ESUP-SGC, vous devez installer ESUP-SGC mais également ESUP-NFC-TAG.
ESUP-SGC
Gère le cycle de vie de vos cartes (workflow allant de la demande à désactivatino de la carte)
- Authentifie les utilisateurs via une authentification Shibboleth
Récupère les informations (nom, prénom, email, date de naissance, etc.) des utilisateurs depuis l'identifiaction shibboleth ou/et un annuaire LDAP ou/et une base de données relationnelle
Synchronise les informations utilisateurs et de cartes avec l'API du CNOUS (CROUS, IZLY) en temps réel.
- Synchronise les informations utilisateurs étudiants et de cartes avec l'API ESC - European Student Card : http://europeanstudentcard.eu
Synchronisation avec différentes solutions de contrôles d’accès (P2S, TIL, Synchronic)
- Reversement des informations de cartes (csn, 'identifiant desfire', photo) dans un annuaie LDAP
- Permet l’impression des cartes (en mode PS/PCL)
esup-sgc ne sait pas encoder les cartes, la partie technique propre au NFC est propre à ESUP-NFC-TAG
ESUP-NFC-TAG
ESUP-NFC-TAG ( https://www.esup-portail.org/wiki/display/ESUPNFC ) se décompose d'une partie serveur (implémentatnt toute la logique métier, la gestion des périphériques et applications clientes ainsi que les algorithmes de chiffrement Mifare Desfire) nommé ESUP-NFC-TAG-SERVER qui :
Permet la lecture et l’écriture des cartes en NFC - technologie Mifare Desfire
Gère des applications clientes (de lecture notamment mais aussi écriture ou/et mise à jour pour ESUP-SGC)
Gère les périphériques sans contact (lecteur PC/SC, smartphone, …)
C'est esup-nfc-tag-server qui connait la structure de la carte Mifare Desfire. Il communique avec esup-sgc pour récupérer le contenu à écrire dans les fichiers (ex : code d’identification pour le contrôle d’accès)
Pour lire ou encoder une carte, un "client lourd" est nécessaire ; aussi les applications clientes suivantes sont disponibles :
esup-nfc-tag-desktop : application java qui permet d’utiliser un encodeur PC/SC USB depuis une machine linux/windows/mac disposant de Java
esup-nfc-tag-droid : application Android qui utilise le lecteur NFC du smartphone
ESUP-SGC-CLIENT
ESUP-SGC inclut également son propre client pour l’encodage des cartes (esup-sgc-client) qui est en fait également client d'esup-nfc-tag-server.
L’encodage via esup-sgc-client se passe de cette manière :
lecture du QR code présent sur la carte (identifiant l’individu à encoder)
association de la carte avec l’individu dans le SGC
encodage des différentes applications DESFIRE telles que décrites dans le fichier de configuration d'ESUP-NFC-TAG-SERVER
... et optionnellement (on recommande plutôt d'acheter des cartes préencodés IZLY) encodage de l’application IZLY (CROUS) via ESUP-NFC-TAG-SERVER en utilisant la clé SAM du CNOUS et des DLL Windows
Schéma d’architecture de la solution
Liens
https://github.com/EsupPortail/esup-sgc
https://github.com/EsupPortail/esup-nfc-tag-server
https://github.com/EsupPortail/esup-nfc-tag-desktop
https://github.com/EsupPortail/esup-nfc-tag-droid
Pre-requis
Logiciels
Java (JDK - JAVA SE 8): vous pouvez utiliser la librairie openjdk pour la partie serveur, pour la partie cliente, il est plus simple de prendre les versions officielles de chez Oracle (notamment pour le support facilité de JAVA WebStart et Java FX) : http://www.oracle.com/technetwork/java/javase/downloads/index.html
Maven (dernière version 3.0.x) : http://maven.apache.org/download.cgi
Postgresql : le mieux est de l'installer via le système de paquets de votre linux.
Tomcat 8 : https://tomcat.apache.org/download-80.cgi
Apache + libapache2-mod-shib2
Git
Les deux applications serveurs doivent être « shibbolethisées » - voir la documentation renater : https://services.renater.fr/federation/docs/installation/sp
Matériel
Voici le matériel minimal requis pour pouvoir mettre en place un Système de Gestion de cartes via l'environnement ESUP-SGC.
Serveur : 2 CPU, RAM > 2 Go, Disque > 20 Go
Lecteurs RFID USB Compatible PC/SC pour encodage
Cartes Mifare Desfire EV1 ou EV2
- Une imprimante à carte.
A cela, un Smartphone Android > 5 avec lecteur NFC peut également s'avérer utile par exemple.
Installation
Éléments requis
Pour avoir un système de gestion de cartes fonctionnel, l'installation minimale consiste à installer :
- un serveur tomcat avec l'application web esup-nfc-tag-server - documentation d'installation ici :
https://github.com/EsupPortail/esup-nfc-tag-server/blob/master/README.md - un serveur tomcat avec l'application web esup-sgc - documentation d'installation ici :
https://github.com/EsupPortail/esup-sgc/blob/master/README.md
A noter que esup-sgc embarque de fait le client esup-sgc-client sous la forme d'un jar servie via Java Web Start (JavaWS) / Java Network Launch Protocol (JNLP).
Ce client est signé par l'Université de Rouen Normandie - vous pouvez aussi le reconstruire et le resigner vous même depuis les sources : https://github.com/EsupPortail/esup-sgc-client
Éléments optionnels
Vous pouvez également mettre en place les applications Esup-nfc-tag-desktop et Esup-nfc-tag-droid :
- Esup-nfc-tag-desktop :https://github.com/EsupPortail/esup-nfc-tag-desktop/blob/master/README.md
- Esup-nfc-tag-droid : https://github.com/EsupPortail/esup-nfc-tag-droid/blob/master/README.md
Alliées à ESUP-SGC, ces applications pourront vous permettre
- de rechercher une carte en la badgeant
- de marquer une carte comme "livrée" en la badgeant
Configurations
Esup-nfc-tag-server
La configuration se fait par les fichiers suivants :
src/main/resources/META-INF/spring/applicationContext-custom.xml
src/main/resources/META-INF/spring/applicationContext-desfire.xml (voir configuration avancée)
src/main/resources/META-INF/spring/applicationContext-security.xml
applicationContext-custom.xml
Le fichier applicationContext-custom.xml permet de configurer les différentes applications avec lesquelles esup-nfc-tag va communiquer.
Dans le cadre du SGC il faudra à minima configurer la connexion avec esup-sgc à l’aide de la configuration suivante :
<bean id="csnAuthConfig" class="org.esupportail.nfctag.service.api.impl.CsnAuthConfig"> <property name="description" value="Authentification CSN"/> </bean> <bean id="esupSgcUpdateExtApi" class="org.esupportail.nfctag.service.api.impl.AppliExtRestWs"> <property name="isTagableUrl" value="https://esup-sgc-test.univ-ville.fr/wsrest/nfc/isTagable"/> <property name="validateTagUrl" value="https://esup-sgc-test.univ-ville.fr/wsrest/nfc/validateTag"/> <property name="getLocationsUrl" value="https://esup-sgc-test.univ-ville.fr/wsrest/nfc/locationsUpdater"/> <property name="description" value="Web Service Update Esup SGC"/> </bean> <bean id="tagIdCheckApiEsupSgc" class="org.esupportail.nfctag.service.api.impl.TagIdCheckRestWs"> <property name="tagIdCheckUrl" value="https://esup-sgc-test.univ-ville.fr/wsrest/nfc/tagIdCheck"/> <property name="idFromEppnInitUrl" value="https://esup-sgc-test.univ-ville.fr/wsrest/nfc/idFromEppnInit"/> <property name="description" value="via Esup SGC"/> </bean>
en remplacant les liens par ceux pointant vers votre instance d’esup-sgc
applicationContext-desfire.xml
Dans le ficher applicationContext-desfire.xml on trouve la structure et les données qui seront écrites sur la carte lors de l’encodage. Par défaut la configuration de Desfire est vide, aucune application ne sera écrite sur la carte.
<bean id="tagName" class="org.esupportail.nfctag.beans.DesfireTag" p:formatBeforeWrite="false" p:key="0000000000000000" p:keyType="DES" p:keyVersion="00"> </bean>
Voir la documentation avancée pour l'ajout d'application Desfire sur la carte.
applicationContext-security.xml
Dans le fichier applicationContext-security.xml il faut modifier le mapping des groupes pour l’attribution des rôles Admin et Supervisor en precisant le cn des groupes concernés :
<beans:bean id="authUserDetailsService" class="org.esupportail.nfctag.security.ShibAuthenticatedUserDetailsService"> <beans:property name="mappingGroupesRoles"> <beans:map> <beans:entry key="cn=for.esup-nfc-tag.admin,ou=groups,dc=univ-ville,dc=fr" value="ROLE_ADMIN" /> <beans:entry key="cn=for.esup-nfc-tag.supervisor,ou=groups,dc=univ-ville,dc=fr" value="ROLE_SUPERVISOR" /> </beans:map> </beans:property> </beans:bean>
Esup-sgc
La configuration se fait via les fichiers suivants :
src/main/resources/META-INF/spring/applicationContext-services.xml
src/main/resources/META-INF/spring/applicationContext-crous.xml
src/main/resources/META-INF/spring/applicationContext-paybox.xml
src/main/resources/META-INF/spring/applicationContext-access-control.xml
src/main/resources/META-INF/spring/applicationContext-security.xml
applicationContext-services.xml
UserInfo :
La première partie du fichier comporte les « UserInfoService » ainsi que les « SpelUserInfoService » . Ces deux entités ont pour but de peupler les informations des demandeurs de carte à l’aide des différentes sources de données présentent dans le SI. Trois methodes sont implémentées dans le SGC :
ShibUserInfoService (recupération des données via le context Shibboleth)
LdapUserInfoService
SqlUserInfoService
Les spelUserInfoService sont des règles qui s’appliquent ensuite pour calculer certains attributs de l’utilisateur.
La recherche dans les différentes sources ainsi que le calcule des règles se fait de manière séquentielle dans l’ordre défini par la propriété « p:order ». A chaque étape, quand une donnée est trouvée, elle remplace celle trouvée par l’étape précédente.
ComueNuCardIdService :
Permet de configurer le début de la plage d’identifiants, dans le cas present l’identifiant COMUE (ouverture de portes) et l’identifiant CROUS.
<bean id="cardIdService" class="org.esupportail.sgc.services.cardid.ComueNuCardIdService"> <property name="cardNfcIdCounterBegin" value="107000000100000"/> <property name="cardCrousIdCounterBegin" value="66900000"/> <property name="crousEncodeEnabled" value="true"/> </bean>
crousEncodeEnabled permet de spécifier si l’application CROUS doit être écrite lors de l’encodage des cartes.
EsupNfcTagService :
Pour spécifier l’adresse du serveur esup-nfc-tag. Le SGC déclare et contrôle ses périphériques d’encodage (esup-scg-client) avec esup-nfc-tag.
<bean id="esupNfcTagService" class="org.esupportail.sgc.services.EsupNfcTagService"> <property name="restTemplate" ref="restTemplate"/> <property name="webUrl" value="http://esup-nfc-tag.univ-ville.fr"/> <property name="applicationName" value="Ecriture SGC"/> <property name="location" value="Encodage ESUP SGC"/> </bean>
LdapValidateService
Le SGC peut transmettre des données au LDAP lorsque la carte est activée. Dans le bean ldapValidateService il est possible de paramétrer deux types de clés : Simple ou multivaluée (ldapCardIdsMappingValue, ldapCardIdsMappingMultiValues)
Les valeurs transmissibles sont : %csn%, %reverse_csn% (le csn retourné par paires), %desfireId% (ex : identifiant contrôle d'accès), %photo%.
<bean id="ldapValidateService" class="org.esupportail.sgc.services.ldap.LdapValidateService"> <property name="ldapTemplate" ref="ldapTestTemplate"/> <property name="peopleSearchFilter" value="(eduPersonPrincipalName={0})"/> <property name="ldapCardIdsMappingMultiValues"> <map> <!-- Exemple clé multi-valuée --> <entry key="supannRefId"> <list> <value>{ISO15693}%csn%</value> <value>{LEOCARTE:ACCESS-CONTROL}%desfireId%</value> </list> </entry> <!-- Exemple clé multi-valuée --> <entry key="autreExemple"> <list> <value>%reverse_csn%@ISO15693</value> </list> </entry> </map> </property> <property name="ldapCardIdsMappingValue"> <map> <!-- Exemple clé simple --> <entry key="jpegPhoto" value="%photo%"/> </map> </property> </bean>
applicationContext-crous.xml
ApiCrousService :
Permet d’activer l’envoi de données au CROUS via l’api
<bean id="apiCrousService" class="org.esupportail.sgc.services.crous.ApiCrousService"> <property name="enable" value="false"/> <property name="webUrl" value="https://api-pp.nuonet.fr/v1" /> <property name="login" value="truc@univ-ville.fr" /> <property name="password" value="xxxxxxxxxxxxxxx" /> <property name="restTemplate" ref="restTemplate" /> </bean>
EsistCrousService :
Fait référence au fichier XML de calcul des tarifs CROUS
ApiEscrService :
Permet de configurer l’envoi des données à l’api ESC (Eropean Student Card) voir : http://europeanstudentcard.eu/
<bean id="europeanStudentCardService" class="org.esupportail.sgc.services.esc.ApiEscrService"> <property name="enable" value="false"/> <property name="webUrl" value="http://api-sandbox.europeanstudentcard.eu/v1" /> <property name="key" value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" /> <property name="restTemplate" ref="restTemplate" /> <property name="countryCode" value="FR"/> <property name="picInstitutionCode" value="000000000"/> <!-- 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="3"/> </bean>
applicationContext-paybox.xml
Permet le paramétrage du module paybox dans le cas d’un renouvellement de carte payant.
applicationContext-access-control.xml
Permet de paramétrer le chemin d'export des informations pour le controle d'accès. Formats disponibles:
- P2S
- TIL
- SYNCHRONIC
applicationContext-security.xml
Comme pour la configuration esup-nfc-tag, il s’agit de mapper les groups sur les rôles proposés par le SGC :
ADMIN
MANAGER
LIVREUR
UPDATER
CONSULT
USER (Liste des utilisateurs pouvant faire une demande de carte)
USER_NO_EDITABLE (Liste des utilisateurs dont les critères ne permettent pas l’edition de la carte, ex: dossier administratif incomplet)
USER_RENEWAL_PAYED (Liste des utilisateurs pouvant renouveler leur carte gratuitement)