Guide de l`application cliente des Web Services de
publicité
Spécifications Fonctionnelles Détaillées Guide de l’application cliente des Web Services de l’Annuaire Santé Identification du document Référence Annuaire_sante_fr_Guide_App_Cliente_WebServices_V1.1.5.docx Date de création 15/05/2013 Date de dernière mise à jour 04/12/2013 Etat Validé Version V1.1.5 Classification Confidentiel - Non public Nombre de pages 21 Historique du document Version Date Auteur Commentaires V0.0.1 15/05/13 ASIP Santé Initialisation du document V1.0.0 28/06/13 ASIP Santé Version pour diffusion Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 Documents de référence Référence Descriptif [ref 1] Annuaire_sante_fr_DSFT_WebServices_Consultation Dossier des spécifications Fonctionnelles et techniques des Webservices du repertoire annuaire.santé.fr [ref 2] NAS-Ressources terminologiques utilisées par le RASS NAS - Ressources terminologiques associées aux données publiées par le répertoire annuaire.sante.fr [ref.3 ] CI-SIS : EVOLUTION DU VIHF : PROFIL POUR ANNUAIRE DE PROFESSIONNEL DE SANTÉ CI-SIS : Evolution du VIHF : profil pour annuaire de professionnel de santé Classification : public 2 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 Sommaire 1. 2. Introduction ..................................................................................................................... 4 1.1 Objet du document ..................................................................................................................... 4 1.2 Documents relatifs ...................................................................................................................... 4 1.3 Fonctions implémentées ............................................................................................................. 4 1.4 Avertissement ............................................................................................................................. 4 Application cliente............................................................................................................ 5 2.1 Contenu....................................................................................................................................... 5 2.2 Description des sources .............................................................................................................. 5 2.3 2.4 3. 2.2.1 Dossier src/main/java .................................................................................................... 5 2.2.2 Dossier src/main/resources ........................................................................................... 7 2.2.3 Dossier src/test/java ...................................................................................................... 7 2.2.4 Dossier src/test/resources ............................................................................................. 8 Description détaillée des classes ................................................................................................ 8 2.3.1 Dossier src/main/java .................................................................................................... 8 2.3.2 Dossier src/test/java .................................................................................................... 11 Configuration de l’application cliente ....................................................................................... 12 2.4.1 Fichier de configuration ............................................................................................... 12 2.4.2 Authentification ........................................................................................................... 13 2.4.3 Utilisation derrière un proxy ........................................................................................ 14 Principes de fonctionnement .......................................................................................... 14 3.1 Connexion sécurisée TLS mutuelle ........................................................................................... 14 3.2 Authentification directe (carte CPS) ......................................................................................... 15 3.3 3.2.1 Extraction des informations de la carte CPS ................................................................ 15 3.2.2 Signature des données avec la carte CPS ..................................................................... 15 Authentification indirecte (certificats établissement) .............................................................. 16 3.3.1 3.4 4. 5. Obtenir l’accès aux méthodes du certificat PKCS12 .................................................... 16 Jeton VIHF ................................................................................................................................. 16 3.4.1 Structure du jeton VIHF................................................................................................ 16 3.4.2 Construction du jeton VIHF .......................................................................................... 16 Installation de l’application cliente ................................................................................. 18 4.1 Prérequis ................................................................................................................................... 18 4.2 Installation ................................................................................................................................ 18 4.3 Remarques ................................................................................................................................ 19 4.4 Configuration de l’application cliente ....................................................................................... 19 4.5 Exécution des tests ................................................................................................................... 19 Tests avec SoapUI ........................................................................................................... 21 Classification : public 3 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 1. Introduction 1.1 Objet du document La lecture des spécifications des contrats d’interfaces des Web Services permettant la consultation des données rattachées aux personnes morales et physiques de l’Annuaire Santé, est un prérequis à la compréhension de l’application cliente. 1.2 Documents relatifs Dossier de spécifications fonctionnelles et techniques détaillées des Web Services de consultation. Cadre d’interopérabilité des SIS (Volet Synchrone pour Client Lourd). 1.3 Fonctions implémentées Les principales fonctions implémentées par l’application cliente sont : Authentification par carte ou par certificat serveur ; Génération d’un jeton VIHF ; Etablissement d’une connexion sécurisée TLS ; Génération des requêtes Soap des clients des quatre web services de consultation des données des personnes physiques et des personnes morales : 1. Client du Web Service de recherche de personnes physiques ; 2. Client du Web Service de consultation des données d’une ou de plusieurs personnes physiques ; 3. Client du Web service de recherche de personnes morales ; 4. Client du Web Service de consultation des données d’une ou de plusieurs personnes morales. 1.4 Avertissement Les codes sources sont fournis « tels quels », sans support. L’attention du partenaire est appelée sur les modalités d’utilisation du code exemple. Ce dernier est fourni à titre d’information permettant au partenaire de réaliser librement l’adaptation personnalisée nécessaire à la création de l’interfaçage de son logiciel. L’ASIP Santé en garantit la pertinence intrinsèque mais pas l’utilisation in situ chez le partenaire. Le partenaire est seul responsable des bonnes conditions de son utilisation et libre de s’inspirer des éléments fournis et de les adapter par ses propres moyens à la situation particulière de la solution logicielle qu’il développe. Ainsi notamment, il est déconseillé de procéder par voie de copier-coller du code à partir des exemples fournis. L’ASIP Santé décline toute responsabilité en cas de mauvaise mise en œuvre du code exemple. Classification : public 4 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 2. Application cliente 2.1 Contenu L’application cliente est livrée sous forme d’archive au format zip : annuaire-sante-webservices-client<version>-src.zip, contenant un projet Java configuré sous l’IDE Eclipse. L’archive décompressée donne lieu au dossier annuaire-sante-webservices-client-<version>, dont le contenu est le suivant : Dossier Description .settings Dossier de configuration du projet Eclipse Certificates Dossier contenant d’authentification repo Dossier contenant une structure de repository Maven propre au projet pour embarquer le jar client des Web Services de consultation annuaire-sante-wsclient-<version>.jar, ce dernier contient les fichiers WSDL et XSD des Web Services src/main/java Dossier contenant les sources des classes java src/main/resources Dossier contenant les ressources utiles à l’exécution des classes de l’application cliente (fichiers de configurations, keystores,...) src/test/java Dossier contenant les sources des classes java des tests JUnit des services (permet l’exécution des web-services) src/test/resources Dossier contenant les ressources utiles à l’exécution des classes de test (fichiers de test, ...) .classpath Fichier de configuration du classpath du projet Eclipse .project Fichier de configuration principal du projet Eclipse pom.xml Fichier de configuration Maven pour le projet assembly.xml Fichier de configuration de l’assemblage des sources pour Maven les certificats P12 et les keystore 2.2 Description des sources L’application cliente contient les packages suivants : 2.2.1 Dossier src/main/java Ce dossier est le dossier source principal de l’application cliente. Il contient les packages suivants : 2.2.1.1 Package fr.sante.annuaire.webservices.client.authentification Ce package contient la classe de service d'appel au gestionnaire du jeton VIHF et de la connexion TLS. Classification : public 5 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 2.2.1.2 Package fr.sante.annuaire.webservices.client.certificate Ce package contient les classes représentant les données contenues dans le certificat ainsi que la classe GetX509CertificateInfo permettant de les extraire d’un certificat X509. 2.2.1.3 Package fr.sante.annuaire.webservices.client.common.vihf Ce package contient les classes représentant le jeton VIHF. 2.2.1.4 Package fr.sante.annuaire.webservices.client.consultation Ce package contient les classe d’implémentation des clients des Web Services de consultation de(s) personne(s) morale(s) et physique(s). 2.2.1.5 Package fr.sante.annuaire.webservices.client.examples.donnees Ce package contient la classe récupérant les données d'exemple d’un professionnel de santé depuis sa carte CPS ou depuis le fichier de configuration. 2.2.1.6 Package fr.sante.annuaire.webservices.client.exception Ce package contient une classe d’exception générique utilisée par les clients des web services 2.2.1.7 Package fr.sante.annuaire.webservices.client.pkcs11 Ce package contient toutes les classes nécessaires pour accéder à la carte CPS via le wrapper PKCS11. 2.2.1.8 Package fr.sante.annuaire.webservices.client.pkcs12 Le package pkcs12 contient la classe Pkcs12Impl implémentant l’interface Pkcs12 offrant l’accès au certificat PKCS12. Ce certificat se trouve dans les ressources du projet. 2.2.1.9 Package fr.sante.annuaire.webservices.client.recherche Ce package contient les classe d’implémentation des clients des Web Services de recherche de(s) personne(s) morale(s) et physique(s). 2.2.1.10 Package fr.sante.annuaire.webservices.client.security.vihf Ce package contient les classe d’implémentation du jeton VIHF à l’aide de la librairie OpenSAML. Remarque : les données du VIHF sont à valoriser dynamiquement en fonction des données de l’utilisateur connecté (lues sur la carte CPS en authentification directe ou récupérées du fichier de configuration en authentification indirecte). 2.2.1.11 Package fr.sante.annuaire.webservices.client.soapservice Ce package contient la classe qui gère la mise en place du VIHF dans les messages et la connexion. 2.2.1.12 Package fr.sante.annuaire.webservices.client.util Ce package est un utilitaire où l’on retrouve différentes classes nécessaires au projet. Classification : public 6 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 2.2.1.13 Package fr.sante.annuaire.webservices.client.vihf Ce package contient les différents handlers de VIHF. 2.2.1.14 Package fr.sante.annuaire.webservices.client.xades Ce package contient des classes nécessaires à la signature XAdES. 2.2.2 Dossier src/main/resources Ce dossier est le dossier de ressources principal de l’application cliente. Il contient les éléments suivants : 2.2.2.1 Package fr.sante.annuaire.webservices.client.xades Ce package contient notamment des fichiers magasins de certificat Java (mot de passe = « changeit ») permettant de fournir la « chaine de certification » des certificats de signature CPS2bis 2020 (racine des certificats de personnes morales) ou CPS2ter 2020 (racine des cartes CPx, prorogée en 2012), dans la signature XAdES (éléments fils de SigningCertificate) : Fichier truststoreCps.jks truststoreCpsTest.jks keystoreCps.jks keystoreCpsTest.jks Contenu AC racines des certificats réels AC racines des certificats de test ; inutile en production AC intermédiaires des certificats réels AC intermédiaires des certificats de test ; inutile en production 2.2.2.2 Fichier config.properties Le fichier config.properties contient les propriétés utilisées par l’application cliente (URL des services, chemins des certificats, etc…). 2.2.2.3 Fichier cxf-client.xml Le fichier cxf-client.xml contient la configuration CXF (framework des Web Services) 2.2.2.4 Fichier log4j.xml Le fichier log4j.xml contient la configuration pour les logs. 2.2.3 Dossier src/test/java Ce dossier est le dossier source de test de l’application cliente. Il contient les packages suivants : 2.2.3.1 Package fr.sante.annuaire.webservices.client.test Ce package contient les classe d’implémentation des tests des Web Services de consultation et de recherche des personnes morales et physiques. 2.2.3.2 Package fr.sante.annuaire.webservices.client.test.util Package utilitaire où l’on retrouve une classe de constantes pour les classes de test. Classification : public 7 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 2.2.4 17/12/13 Dossier src/test/resources Ce dossier est le dossier de ressources de test de l’application cliente. Il contient les éléments suivants : 2.2.4.1 Package fr.sante.annuaire.webservices.client.consultation Ce package contient les fichiers de test des Web Services de consultation des personnes morales et physiques. Il s’agit de fichiers properties contenant les critères de consultation des personnes morales ou physiques. 2.2.4.2 Package fr.sante.annuaire.webservices.client.recherche Ce package contient les fichiers de test des Web Services de recherche des personnes morales et physiques. Il s’agit de fichiers properties contenant les critères de recherche des personnes morales ou physiques. 2.3 Description détaillée des classes 2.3.1 Dossier src/main/java Nom du package / Nom de la classe Java Fonction fr.sante.annuaire.webservices.client.authentification Package des services d’authentification LoginService.java Classe de service d'appel au gestionnaire du jeton VIHF et de la connexion TLS. fr.sante.annuaire.webservices.client.certificate Package utilitaire pour extraction de données d’un certificat GetX509CertificateInfo.java Classe extractrice de données du certificat Issuer.java Classe représentant l’objet Issuer du certificat Subject.java Classe représentant l’objet Subject du certificat fr.sante.annuaire.webservices.client.common.vihf Package contenant les classes utilitaires pour la génération du VIHF (classes et énumérations) CommonCode.java Classe implémentant un élément générique pour le VIHF IdStructureType.java Enumération pour les types d'identifiants structures IdUserType.java Enumération pour les types d'identifiants des acteurs ModeAcces.java Enumération pour les modes d'accès Classification : public 8 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr Nom du package / Nom de la classe Java 17/12/13 Fonction ProfilUtilisateur.java Classe implémentant l’élément ProfilUtilisateur PurposeOfUse.java Classe implémentant l’élément PurposeOfUse Role.java Classe implémentant l’élément Role pour les professions et spécialités RoleItf.java Interface de l’élément Role VIHF.java Interface de l’objet VIHF VIHFProfil.java Classe implémentant l’élément VIHFProfil fr.sante.annuaire.webservices.client.consultation Package contenant les classes d’implémentation des clients des Web Services de consultation PP et PM ConsultationPMClient.java Classe représentant un client du web service de consultation PM ConsultationPPClient.java Classe représentant un client du web service de consultation PP fr.sante.annuaire.webservices.client.examples.donnees Package contenant les données en exemple PSSampleData.java Classe regroupant des données d’exemple du PS (carte CPS) suivant le type d’authentification fr.sante.annuaire.webservices.client.ex Package contenant une classe d’exception générique utilisée par les clients ception des web services AnnuaireSanteWebServiceClientExcepti on.java Classe d’exception générique utilisée par les clients des web services fr.sante.annuaire.webservices.client.pkcs11 Package regroupant tout ce qui concerne le pkcs11 (lecteur de carte CPS) Pkcs11.java Interface pour utiliser la carte pkcs11 PKCS11Tools.java Classe utilitaire pour le pkcs11 fr.sante.annuaire.webservices.client.pkcs11.cps Package contenant les classes spécifiques à la carte CPS CPSCard.java Classe permettant de charger la Cryptolib dans le provider PkCS11 sun fr.sante.annuaire.webservices.client.pkcs11.impl Package regroupant les implémentations de l’interface pkcs11 Pkcs11Impl.java Classification : public Implémentation du pkcs11 permettant de ne charger qu’une seule fois la 9 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr Nom du package / Nom de la classe Java 17/12/13 Fonction Cryptolib fr.sante.annuaire.webservices.client.pkcs12 Package regroupant tout ce qui concerne le pkcs12 (certificat serveur) Pkcs12.java Interface pour utiliser un certificat pkcs12 fr.sante.annuaire.webservices.client.pkcs12.impl Package regroupant les implémentations de l’interface pkcs12 Pkcs12Impl.java Implémentation du pkcs12 permettant de charger un certificat fr.sante.annuaire.webservices.client.recherche Package contenant les classes d’implémentation des clients des Web Services de recherche PP et PM RecherchePMClient.java Classe représentant un client du web service de recherche PM RecherchePPClient.java Classe représentant un client du web service de recherche PP fr.sante.annuaire.webservices.client.security.vihf Package contenant la représentation du jeton VIHF Helper.java Permet de créer des exceptions compréhensibles pour le VIHF VIHFFields.java Enumération des champs du VIHF VIHFImpl.java Implémentation du jeton VIHF fr.sante.annuaire.webservices.client.security.vihf.handlers Package contenant les handlers du jeton VIHF VIHFClientHandler.java Classe représentant un VIHF client (hérite de VIHFHandler) VIHFHandler.java Superclasse du Handler VIHF fr.sante.annuaire.webservices.client.soapservice Package contenant la classe qui gère la mise en place du VIHF dans les messages et la connexion SetTLSAndVIHF.java Classe qui gère la mise en place du VIHF dans les messages et la connexion TLS (tunnel TLS persistant avec cxf). fr.sante.annuaire.webservices.client.util Package regroupant les classes utilitaires de l’application cliente BaseClient.java Classification : public Classe de base pour les clients des Web Services 10 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr Nom du package / Nom de la classe Java 17/12/13 Fonction Constants.java Classe de constantes pour clients des Web Services Properties.java Classes permettant de charger une propriété se trouvant dans src/main/resources/config.properties SSLKeyManagers.java Manager de clés pour la connexion TLS avec un certificat serveur fr.sante.annuaire.webservices.client.vihf Package contenant les différents handlers VIHF (exemples de jetons VIHF) KSClientHandler.java Handler pour VIHF signé par carte CPS (usage futur) NotSignedClientHandler.java Handler VIHF non signé (authentification directe) P11ClientHandler.java Handler pour VIHF signé par carte CPS (usage futur) SoftwareCertificateClientHandler.java Handler VIHF non signé avec certificat pkcs12 (authentification indirecte) fr.sante.annuaire.webservices.client.xades Package contenant les classes de construction de signature Xades CpsPathBuilder.java 2.3.2 Classe permettant de gérer la chaine de certification des cartes CPS à ajouter aux signatures XAdES Dossier src/test/java Nom du package / Nom de la classe Java Fonction fr.sante.annuaire.webservices.client.test Package contenant les classe d’implémentation des tests des Web Services AllTests.java Classe qui fait appel à tous les tests implémentés ConsultationPMTest.java Classe d’implémentation de test de la consultation des PM ConsultationPPTest.java Classe d’implémentation de test de la consultation des PP RecherchePMTest.java Classe d’implémentation de test de la recherche des PM RecherchePPTest.java Classe d’implémentation de test de la recherche des PP fr.sante.annuaire.webservices.client.test.util Package contenant les classes utilitaires Classification : public 11 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr Nom du package / Nom de la classe Java 17/12/13 Fonction Constants.java Classe de constantes pour les classes de test 2.4 Configuration de l’application cliente 2.4.1 Fichier de configuration Les paramètres de configuration de l’application cliente se trouvent dans le fichier config.properties, il convient de, les bien renseigner, avant d’exécuter l’application cliente. Paramètre Description Requis ? SERVER_URL Il s’agit de l’URL racine des Web Services Oui cibles CERTIFICATE_TYPE Il s’agit du type du certificat, les valeurs Oui possibles sont : CPS (certificat de la carte) et P12 (certificat serveur) CPS_MODULE Il s’agit du chemin absolu sur le poste Oui client du module PKCS11, celui-ci doit si CERTIFICATE_TYPE =CPS être installé sur le poste client (Cryptolib). Ce chemin peut différer d’un système à un autre, valeurs possibles : C:/WINDOWS/system32/cps_pkcs11_w32 .dll C:/WINNT/cps_pkcs11_w32.dll C:/WINNT/system32/cps_pkcs11_w32.dll C:/Windows/SysWOW64/cps3_pkcs11_w 32.dll CPS_PWD Il s’agit du code PIN de la carte CPS Oui si CERTIFICATE_TYPE = CPS CPS_SIGN_VIHF Indique si le jeton VIHF doit être signé ou Oui pas, la valeur doit être positionnée à si CERTIFICATE_TYPE = CPS « false » AUTHENTIFICATION_CERTIFICATE_PATH Il s’agit du chemin du certificat P12 Oui servant à l’authentification si CERTIFICATE_TYPE = P12 AUTHENTIFICATION_PASSWORD Il s’agit du mot de passe du certificat P12 Oui servant à l’authentification si CERTIFICATE_TYPE = P12 SERVER_TRUSTSTORE_PATH Il s’agit du chemin du fichier keystore Oui (magasin de clefs) qui stocke les clefs Classification : public 12 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr Paramètre Description 17/12/13 Requis ? privés des certificats SERVER_TRUSTSTORE_PASSWORD Il s’agit du mot de passe du fichier Oui keystore (magasin de clefs) qui stocke les clefs privés des certificats PROXY_HOST Configuration du proxy (hôte) si le poste Oui client est derrière un proxy si utilisation de l’application derrière un proxy PROXY_PORT Configuration du proxy (port) si le poste Oui client est derrière un proxy si utilisation de l’application derrière un proxy IDENTIFIANT_STRUCTURE Identifiant de l’établissement de santé ou Non du cabinet depuis lequel, la requête a été émise SECTEUR_ACTIVITE Secteur d’activité dans lequel exerce Non l’utilisateur PROFIL_UTILISATEUR Profil de l’utilisateur PROFIL_UTILISATEUR_PERIMETRE Contexte métier l’utilisateur Oui ou périmètre de Oui si le profil de l’utilisateur nécessite la détermination d’un périmètre. IDENTITE_UTILISATEUR Identité de l’utilisateur dans le cas d’une Oui authentification indirecte (ex : nom, si CERTIFICATE_TYPE = P12 prénom) PATH_TO_SAVE Chemin des fichiers générées en sortie 2.4.2 des réponses Oui Authentification L’application cliente fonctionne avec deux modes d’authentification : 1. Authentification directe avec une carte CPS de test 2. Authentification indirecte avec des certificats de structure (certificats serveur). L’application cliente est livrée en mode authentification directe CPS par défaut. Dans ce mode, un lecteur de carte fonctionnel avec une carte CPS de test insérée est un prérequis à l’exécution de l’application cliente (code PIN = 1234 configuré par défaut). Pour utiliser des certificats de structure, le fichier config.properties doit être modifié comme suit : Le paramètre « CERTIFICATE_TYPE » doit être positionné à la valeur « P12 » Copier les certificats p12 en votre possession dans le répertoire Certificates de l’application cliente Classification : public 13 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 2.4.3 17/12/13 Préciser le nom et le mot de passe du fichier p12 à utiliser dans les variables : AUTHENTIFICATION_CERTIFICATE_PATH et AUTHENTIFICATION_PASSWORD. Utilisation derrière un proxy Si l’application cliente est exécutée derrière un proxy, il est nécessaire de renseigner les champs PROXY_HOST et PROXY_PORT du fichier de configuration (décommenter les paramètres en supprimant le caractère « # »). 3. Principes de fonctionnement 3.1 Connexion sécurisée TLS mutuelle La connexion sécurisée entre l’application cliente et l’Annuaire Santé s’effectue via une authentification TLS mutuelle. Les certificats utilisés pour cette opération sont le certificat de la carte CPS ou le certificat établissement côté client et le certificat de l’Annuaire Santé côté serveur. Dans la version initiale de l’Annuaire Santé, la connexion TLS est réalisée à partir des certificats des personnes morales. Les certificats autorisés sont déclarés manuellement dans la configuration de l’Annuaire Santé. Le processus de mise œuvre est détaillée dans le guide d’utilisation de la plate-forme de tests des web services : « ANST_BUILD_TEC_Procedure-Utilisation PF de tests des WebServices_20130515_V0.0.1.docx » Le fichier de configuration cxf-client.xml situé dans le dossier src/main/resources configure les paramètres CXF. L’implémentation des actions nécessaires à la connexion sécurisée se trouve dans la classe SetTLSAndVIHF du package fr.sante.annuaire.webservices.client.soapservice. Paramètres CXF : afin que le canal reste ouvert côté client (pour éviter les sollicitations de la carte CPS) le paramètre Connection="Keep-Alive" est positionné : <http:conduit name="*.http-conduit"> <http:client ... Connection="Keep-Alive" ... /> </http:conduit> afin de permettre à l’application cliente de voir les flux échangés (capture des trames entrantes / sortantes en debug uniquement, ne pas utiliser en environnement de production), les paramètres suivants sont positionnés (les trames sont envoyées dans la sortie standard) : <cxf:bus> … <cxf:inInterceptors> <ref bean="loggingInInterceptor" /> </cxf:inInterceptors> <cxf:outInterceptors> <ref bean="loggingOutInterceptor" /> </cxf:outInterceptors> <cxf:inFaultInterceptors> <ref bean="loggingInInterceptor" /> </cxf:inFaultInterceptors> <cxf:outFaultInterceptors> <ref bean="loggingOutInterceptor" /> </cxf:outFaultInterceptors> </cxf:bus> La fonction setTLS : Classification : public 14 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 récupère le certificat d’authentification ; crée un X509TrustManager ; crée un contexte TLS contenant le X509TrustManager et le certificat d’authentification ; récupère le client TLS de la transaction ; construit un contexte TLS adapté à l’Annuaire Santé; définit ce contexte TLS comme étant celui du conduit HTTPS du client récupéré. 3.2 Authentification directe (carte CPS) Pour tester ce mode d’authentification par carte CPS, le fichier config.properties doit être configuré en mode CPS (voir paramètre CERTIFICATE_TYPE). Pour accéder à la carte CPS, la librairie cryptographique CPS (Cryptolib) est requise sur le poste, ainsi qu’un lecteur de carte correctement configuré. Il est nécessaire d’utiliser la version 5.x.x du package de la Cryptolib. Le paramétrage de la Cryptolib dépend de la plateforme cible (voir paramètre CPS_MODULE). L’accès PKCS11 offert par la librairie CPS étant sous la forme d’une librairie externe (cps_pkcs11_w32.dll sous Windows, voir la documentation de la librairie CPS pour plus de précisions sur les autres systèmes), il est nécessaire d’utiliser un wrapper ou un provider pour y accéder en java. Dans l’application cliente, nous avons utilisé le provider PKCS11 fourni par Sun (sun.security.pkcs11.SunPKCS11). Le certificat de la carte est extrait au premier accès, puis l’accès à la carte ne se fait ensuite que pour effectuer des signatures. 3.2.1 Extraction des informations de la carte CPS Tous les accès à la carte CPS se font dans la classe CPSCard qui est elle-même appelée par la classe PKCS11Impl du package fr.sante.annuaire.webservices.client.pkcs11.impl. L’extraction des données se fait dans la fonction init de CPSCard et se déroule de la façon suivante : 1. 2. 3. 4. Ajout du provider de la carte CPS aux providers accessibles Chargement du Keystore de la carte avec le code PIN Récupération de la liste des alias du Keystore Mise en place en mémoire des informations en fonction du nom de leur alias Il ne reste plus qu’à appeler les getters de CPSCard pour récupérer les informations nécessaires. 3.2.2 Signature des données avec la carte CPS La signature des données se base sur l’objet PrivateKey signaturePrivateKey que l’on a obtenu cidessus. Afin de signer, nous utilisons la classe Signature fournie de base avec java et permettant de signer à partir d’une clé privée. En réalité, avec un lecteur de carte PKCS11, nous n’obtenons pas réellement la clé privée mais un token établissant le lien avec la carte. La signature s’effectue dans la fonction sign de la classe CPSCard. La procédure de signature est la suivante : 1. Création d’un objet Signature en précisant le mécanisme de signature 2. Initialisation de l’objet en lui passant la clé de signature 3. Mise en place des données à signer Classification : public 15 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 4. Signature des données et récupération de la signature. 3.3 Authentification indirecte (certificats établissement) Pour tester ce mode d’authentification par certificat établissement, le fichier config.properties doit être configuré en mode P12 (voir paramètre CERTIFICATE_TYPE). Pour les certificats d’établissement (certificats « serveur ») PKCS12 dans l’application cliente, nous avons utilisé les fonctionnalités offertes par java. 3.3.1 Obtenir l’accès aux méthodes du certificat PKCS12 La procédure pour obtenir l’accès à un certificat PKCS12 est la suivante : 1. Récupération de l'instance du dépôt de clés gérant les certificats PKCS12 2. Initialisation du dépôt avec le certificat fourni (sous forme de fichier) et le code PIN du certificat. Dans l’application cliente, nous récupérons ensuite directement la clé et le certificat afin de pouvoir les réutiliser rapidement (voir la fonction login de la classe Pkcs12Impl du package fr.sante.annuaire.webservices.client.pkcs12.impl). 3.4 Jeton VIHF 3.4.1 Structure du jeton VIHF Le jeton VIHF se trouve dans le package fr.sante.annuaire.webservices.client.security.vihf. La classe VIHFFields liste les champs du jeton VIHF sous la forme d’une énumération. La classe VIHFImpl représente le jeton VIHF et offre un constructeur ainsi que des fonctions pour le créer en se basant sur la bibliothèque openSaml. Le package fr.sante.annuaire.webservices.client.security.vihf.handlers contient les différentes classes handlers utilisés par l’application cliente. 3.4.2 Construction du jeton VIHF La construction du jeton VIHF se fait dans la classe SetTLSAndVIHF du package fr.sante.annuaire.webservices.client.soapservice. La fonction AddVIHF se charge de se logger si possible sur le certificat P12 (le jeton VIHF n’est pas signé) puis appelle la fonction de création de handler correspondante (NotSignedClientHandler dans le cas de la carte CPS et SoftwareCertificateClientHandler pour le certificat serveur). Ces deux classes héritent des classes du package : fr.sante.annuaire.webservices.client.security.vihf. handlers et fixent des valeurs exemples dans le VIHF. Le VIHF doit être valorisé correctement à partir des données issues de la carte CPS (cas de l’authentification directe) ou du certificat établissement (cas de l’authentification indirecte). Ces handlers sont ensuite rattachés au service SOAP à l’aide d’un objet SOAPBinding (voir fonction AddVIHF). Le rattachement du VIHF est effectué juste avant l’envoi de la requête SOAP. Les informations présentes dans le jeton VIHF sont utilisées pour l’identification du détenteur de carte (Inscription préalable dans l’Annuaire Santé). Le contenu du jeton VIHF est stocké comme élément de preuve. Classification : public 16 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr Classification : public 17/12/13 17 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 4. Installation de l’application cliente 4.1 Prérequis Les composants cryptographiques CPS doivent être installés (version 5.x.x du package au minimum). La mise à jour des composants cryptographiques peut se faire en utilisant l'outil de DMP compatibilité. Disposer de l'IDE Eclipse version Juno (4.2) ou ultérieure Configurer l'encodage du workspace d’Eclipse pour utiliser l’UTF-8 : o Aller sur Window -> Preferences -> General -> Workspace o Dans Text File encoding, définir « UTF-8 » comme encoding par défaut du workspace pour les fichiers textes o Aller sur General -> Content Types sur le menu à gauche o Sélectionner Text -> Java Properties Files dans la zone Content types o Saisir « UTF-8 » dans le champ Default encoding (en bas de la fenêtre) o Cliquer sur le bouton Update à droite du champ Default encoding o Cliquer sur le bouton OK Installer un JDK 1.6 U4 ou supérieur en mode 32 bits (le mode 64 bits n'est pas compatible), ce JDK doit être aussi installé dans l’IDE Eclipse Un plugin de Maven (M2E - Maven Integration for Eclipse) doit être installé sur Eclipse Configurer le plugin pour utiliser l’installation de Maven embarquée v3.0.4 ou supérieure Configurer de préférence le plugin pour ne pas utiliser un fichier de configuration settings.xml, afin de ne prendre en compte que les repositories de Maven définis dans le pom.xml du projet (cela accélère la construction du projet). 4.2 Installation 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. Décompresser l'archive annuaire-sante-webservices-client-x.x.x-src.zip dans un workspace Ouvrir Eclipse en se positionnant sur ce workspace Importer le projet : menu File -> Import... -> General -> Existing Projects into Workspace Cliquer sur le bouton Next Sélectionner la racine du workspace Sélectionner le projet annuaire-sante-webservices-client-x.x.x Cliquer sur le bouton Finish Créer une configuration Maven : Aller sur le menu Run -> Run Configurations… Se positionner sur Maven Build Faire un clic droit -> New Saisir annuaire-sante-webservices-client dans le champ Name Sélectionner le projet annuaire-sante-webservices-client-x.x.x à l'aide du bouton Browse Workspace... dans le champ Base directory Saisir -X clean install eclipse:clean eclipse:eclipse dans le champ Goals Cocher la case Skip Tests Aller sur l’onglet JRE Sélectionner le JDK du workspace par défaut s’il correspond bien à un jdk (1.6 U4 ou supérieur) complet (pas seulement un JRE) en mode 32 bits, sinon sélectionner le bon jdk en cochant Alternate JRE et sélectionner le à partir de la liste déroulante Aller sur l'onglet Refresh Cocher la case Refresh resources upon completion Cliquer sur le bouton Run Attendre la fin du build Classification : public 18 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 21. Le message BUILD SUCCESS doit apparaître à la fin du build 4.3 Remarques La javadoc est disponible sous le dossier doc/apidocs Si besoin de regénérer la javadoc, créer une configuration Maven comme ci-dessus avec comme cible javadoc:javadoc et l'exécuter Si besoin de repackager les sources du projet, créer une configuration Maven comme cidessus avec comme cible assembly:single et l'exécuter 4.4 Configuration de l’application cliente Editer le fichier src/main/resources/config.properties Suivre la procédure de Configuration de l’application cliente (§2.4) 4.5 Exécution des tests L’application cliente est fournie avec un jeu de tests sous forme de fichiers de propriétés, ces fichiers correspondent aux critères en entrée, de la consultation ou de la recherche des personnes morales et physiques. Les modèles de ces fichiers se trouvent sous le dossier src/test/resources/fr/sante/annuaire/webservices/client/templates : 1. consultationPMTemplate.properties pour le Web service de consultation des personnes morales 2. consultationPPTemplate.properties pour le Web service de consultation des personnes physiques 3. recherchePMTemplate.properties pour le Web service de recherche des personnes morales 4. recherchePPTemplate.properties pour le Web service de consultation des personnes physiques Les fichiers de test fournis avec l’application cliente se trouvent dans les dossiers suivants : 1. src/test/resources/fr/sante/annuaire/webservices/client/consultation pour la consultation des personnes morales et physiques. 2. src/test/resources/fr/sante/annuaire/webservices/client/recherche pour la recherche des personnes morales et physiques. Ces fichiers correspondent à différents cas de test de consultation et de recherche de personnes morales et physiques. A l’exécution des tests, les classes ci-dessous, se trouvant sous le package src/main/java/fr/sante/annuaire/webservices/client/test/ permettent de lire le contenu des dossiers ci-dessus : 1. 2. 3. 4. ConsultationPMTest.java pour les fichiers de test de consultation de personnes morales ConsultationPPTest.java les fichiers de test de consultation de personnes physiques RecherchePMTest.java les fichiers de test de recherche de personnes morales RecherchePPTest.java les fichiers de test de recherche de personnes physiques Ces classes correspondent à des classes de test JUnit qui peuvent être exécutées séparément ou toutes à la fois. Pour exécuter le test d’une classe avec Eclipse, faire un clic droit sur la classe puis Run As > JUnit Test (Junit 4 doit être configuré par défaut) Classification : public 19 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 Pour exécuter tous les tests avec Eclipse, faire un clic droit sur la classe AllTests se situant dans le même package puis Run As > JUnit Test Pour exécuter tous les tests avec Maven, créer une configuration Maven semblable à celle décrite dans l’installation du projet et mettre comme cibles (goals) : test Les résultats de tests sont produits sous forme de fichiers XML situés à l’emplacement défini par le paramètre PATH_TO_SAVE dans le fichier config.properties. Ces fichiers correspondent aux réponses des requêtes Soap envoyés aux Web Services. Classification : public 20 / 21 Guide application cliente – Webservices de consultation du repertoire annuaire.sante.fr 17/12/13 5. Tests avec SoapUI Les web services peuvent être testés à partir de l’application SoapUI. Pour se faire l’option suivante doit être positionnée dans le fichier soapUI-X.X.X.vmoptions : -Dsun.security.ssl.allowUnsafeRenegotiation=true Le keystore fournit dans les sources doit également être positionné dans les préférences SoapUI (« SSL Settings ») Classification : public 21 / 21
