Guide de l`application cliente des Web Services de l`Annuaire Santé

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