# Code exemple JAVA MSSanté - version du 30/04/2015.

## I. Introduction

### A. Contexte MSSanté

Le client de messagerie mettant en oeuvre les Web Services MSSanté permet à l'utilisateur :

- De relever ses messages et de gérer les dossiers de sa BAL MSSanté hébergée par l'opérateur Asip Santé.
- D'émettre des messages vers des destinataires titulaires de BAL sur des domaines hébergés par un opérateur MSSanté.

Ces fonctionnalités sont basées sur plusieurs transactions de Web Services qui composent un catalogue de services. Ce catalogue de services permet de mettre à disposition des fonctionnalités comparables à celles proposées par les protocoles classiques de messagerie IMAP et SMTP. L'accès à ces Web Services repose sur la mise en œuvre d'une authentification forte de l'utilisateur, qui est matérialisée par l'usage d'un jeton fourni par un service d'authentification dédié.

### B. Le code exemple JAVA des Web Services MSSanté de l'opérateur ASIP Santé

#### 1. Principes d’utilisation du code exemple

L'ASIP Santé met à disposition des éditeurs de clients de messagerie du code exemple client MSSanté pour aider les éditeurs dans l’implémentation des Web Services MSSanté de l’opérateur ASIP Santé. L’ASIP Santé garantit la pertinence intrinsèque de code exemple, mais pas l’utilisation in situ chez les éditeurs, qui doivent réaliser les adaptations nécessaires à leur solution logicielle et qui sont les seuls responsables des bonnes conditions de son utilisation. L’ASIP Santé décline toute responsabilité en cas de mauvaise utilisation du code exemple.

#### 2. Composition du code exemple

Le code exemple est fourni sous la forme d’une application composée d'un projet parent "code-exemple" et de deux modules Maven "cxf" et "connect-kit".

- Le module Maven "cxf" comporte un code client MSSanté basé sur CXF. Il permet la mise en œuvre du module "connect-kit".
- Les deux tests "ClientTestOTPMssFolder" et "ClientTestPKCS11MssFolder" se trouvent dans le module Maven "cxf" (cxf/src/test/java/fr/asipsante/mss/clientcxfmss).

Ce code exemple implémente le processus d'authentification SAML2 selon la norme PAOS. L’authentification peut être effectuée soit par l'utilisation d'un PKCS11, soit par l'utilisation d'une connexion OTP.

#### 3. Pré-requis

La lecture du Dossier des Spécifications Techniques (DST) des interfaces d’accès des Clients de messagerie au système MSSanté est indispensable à la compréhension du code exemple fourni. Les WSDL des services de messagerie sont disponibles à l’adresse suivante : http://www.esante.gouv.fr/services/mssante/editeurs-operateurs/editeurs. Le mode d’authentification par carte CPS implique que le poste de travail dispose d’un lecteur de cartes, ainsi que des librairies cryptographiques et modules associés correctement configurés (plus de détails sur http://integrateurs-cps.asipsante.fr/ ).

## II. Compilation du projet

### A. Pré-requis nécessaires

#### 1. Environnement de développement

La compilation avec un IDE du code test nécessite l'installation de :

- Eclipse Luna 4.4.1 32 bits (intègre Maven v3)
- Une jdk1.7.0_71 32 bits

La compilation du code test sans IDE nécessite l'installation de Maven v3.

#### 2. Proxy HTTP pour Maven dans Eclipse

Il peut être nécessaire de configurer le fichier settings.xml dans maven, ci-dessous un exemple :

Le fichier se positionne en général à cet emplacement : C:\Users\\.m2\settings.xml. Si le fichier n'existe pas, il faudra le créer. Le contenu est le suivant :

<settings | xmlns="http://maven.apache.org/SETTINGS/1.0.0"
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
| xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
| http://maven.apache.org/xsd/settings-1.0.0.xsd">
| <localRepository/>
| <interactiveMode/>
| <usePluginRegistry/>
| <offline/>
| <pluginGroups/>
| <servers/>
| <mirrors/>
| <proxies>
|  | <proxy>
|  |  | <id>pxy</id>
|  |  | <active>true</active>
|  |  | <protocol>http</protocol>
|  |  | <host>[HOST]</host>
|  |  | <port>[PORT]</port>
|  |  | <username></username>
|  |  | <password></password>
|  |  | <nonProxyHosts>localhost,127.0.0.1</nonProxyHosts>
|  | </proxy>
| </proxies>
| <profiles/>
| <activeProfiles/>
</settings>

### B. Import du projet source dans un IDE

#### 1. Avec Eclipse

- Utiliser la fonctionnalité "Importer/Maven/Existing Maven Projects"
- Sélectionner le répertoire de votre choix
- Sélectionner "Finish"

#### 2. Avec NetBeans

- Utiliser la fonctionnalité "Open Project"
- Sélectionner le répertoire proposé
- NetBeans réalise automatiquement le build.

### C. Compilation du code source avec l'IDE Eclipse

Lors d'une première compilation :

- Clic-droit "code-exemple"
- Sélectionner "Run As/Maven build…"
- Dans le champ "Name", saisir la commande suivante :
code-exemple mvn clean install
- Dans le champ "Goal", saisir la commande suivante :
clean install
- Run

Pour les prochaines compilations :

- Clic-droit "code-exemple"
- Sélectionner "Run As/Maven build"
- Dans la fenêtre "Select configuration", sélectionner "code-exemple mvn clean install"
- OK

### D. Compilation du code source sans l'aide d'un IDE

- Depuis une console, lancer le build Maven à l'aide de la commande suivante :
mvn clean install

### E. Vérification de la présence des assemblies

- Aller dans : C:\Users\\.m2\repository\fr\asipsante\mss\sample
- Vérifier la présence des assemblies et des ".jar"

## III. Documentation

### A. Production de la documentation

#### 1. Depuis l'IDE Eclipse

Lors d'une première compilation :

- Clic-droit "code-exemple"
- Sélectionner "Run As/Maven build…"
- Dans le champ "Name", saisir la commande suivante :
code-exemple mvn site assembly
- Dans le champ "Goal", saisir la commande suivante :
site:site assembly:assembly
- Run

Pour les prochaines compilations :

- Clic-droit "code-exemple"
- Sélectionner "Run As/Maven build"
- Dans la fenêtre "Select configuration", sélectionner "code-exemple mvn site assembly"
- OK

#### 2. En ligne de commande

Exécuter le build Maven à l'aide de la commande suivante :

- mvn site:site assembly:assembly

### B. Où trouver la documentation ?

La documentation est produite au format Maven dans le sous répertoire "target/code-demo-client-site/code-exemple".

## IV. Configuration et exécution des tests

### A. Fichiers de configuration

#### 1. cxf.xml

Fichier de configuration Spring :
- Configuration HTTP, avec définition du header Accept à envoyer lors de tous les échanges avec le serveur.
- Mise en place de la SSLSocketFactory (ici l'objet sslFactoryFactory qui crée les SSLSocketFactory est défini ailleurs pour pouvoir utiliser plusieurs stratégies SSL en fonction des tests)
- On force l'encodage ISO-8859-1 qui correspond à la réponse du WS.

#### 2. site.xml

Ce fichier permet de générer la documentation sous forme d’un site maven.

### B. Configuration des tests

#### 1. Configuration du test par connexion OTP

#### a) Fichiers de configuration

les deux fichiers suivants doivent être présents avant l'exécution du test :
- mss.properties
- otpConfig-formation.xml

#### b) Fichier otpConfig-formation.xml

Le contenu du fichier otpConfig-formation.xml doit être vérifié avant l'exécution du test :
- <constructor-arg index="2" value="mss-idp.formation.mssante.fr">
- <constructor-arg index="3" value="444">

Les valeurs doivent correspondre à l'URL et au port en vigueur.

#### c) Fichier mss.properties

Le contenu du fichier mss.properties doit être paramétré avant l'exécution du test :
#Configuration pour le test OTP
mss.base.url =indiquer l'url et le port du site à consulter
#IdNatPs utilisé pour s'identifier auprès de l'IDP en mode OTP
ps.id.nat=indiquer l'id_nat du PS utilisé
#compte e-mail du PS
ps.email=indiquer l'adresse mail attachée à la carte du PS
#identifiant du canal OTP, attribué par le système MSS au moment de l'enrôlement
otp.canal.id=indiquer l'id du canal OTP utilisé
#mot de passe du canal OTP, fourni au moment de l'enrôlement
otp.canal.password=indiquer le mot de passe MSSanté utilisé par le PS

#### 2. Configuration du test par connexion avec PKCS11

#### a) Fourniture cps3_pkcs11_w32.dll : cryptolib CPS v5

La fourniture cps3_pkcs11_w32.dll doit être téléchargée et installée sur le système où seront effectués les tests :
- Il est possible de trouver la fourniture à l'adresse suivante en téléchargeant l'installeur de cryptolib CPS :
http://esante.gouv.fr/services/espace-cps/telechargements-libres/cryptolib-cps-windows

#### b) Fichiers de configuration

les deux fichiers suivants doivent être présents avant l'exécution du test :
- mss.properties
- pkcs11Config-formation.xml

#### c) Fichier pkcs11Config-formation.xml

Le contenu du fichier pkcs11Config-formation.xml doit être vérifié avant l'exécution du test :
- <constructor-arg index="2" value="mss-idp.formation.mssante.fr">
- <constructor-arg index="3" value="444">

Les valeurs doivent correspondre à l'URL et au port en vigueur.

#### d) Fichier mss.properties

Le contenu du fichier mss.properties doit être paramétré avant l'exécution du test :
#Configuration pour le test PKCS11
mss.base.url =indiquer l'url et le port du site à consulter
#IdNatPs utilisé pour s'identifier auprès de l'IDP en mode OTP
ps.id.nat=indiquer l'id_nat du PS utilisé
#compte e-mail du PS
ps.email=indiquer l'adresse mail attachée à la carte du PS

### C. Où trouver les informations id.nat, email, otp.canal.id et password ?

Les informations se trouvent dans le compte de test attribué au détenteur de la carte CPS. Se connecter sur l'IHM de MSSanté. Depuis la page d'Accueil, cliquer sur "Modifier mon compte". La page mon compte contient les informations nécessaires pour le paramètrage du fichier "mss.properties".

### D. Exécution des tests

#### 1. Sous Eclipse

- Pour exécuter les deux tests, effectuer un clic droit sur le projet "cxf" et sélectionner l'option "Run AS/Junit Test".
- Pour exécuter l'un des deux tests, effectuer un clic droit sur le test voulu puis sélectionner l'option "Run AS/Junit Test".
- Pour le test par vérification de certificat pkcs11 ClientTestPKCS11MssFolder, lorsque le test est lancé une fenêtre de saisie du code porteur s'affiche. Il convient d'être vigilant car cette fenêtre n'apparaît pas systématiquement en premier plan.

#### 2. Sous NetBeans

- Sélectionner le ou les tests à exécuter et presser la touche F6 ou faire un clic-droit et sélectionner l'option Test file(s).