sedex: Manuel de l utilisateur du proxy service web Installation, configuration et utilisation Proxy service web 5.0.0

Transcription

1 Eidgenössisches Finanzdepartement EFD Bundesamt für Informatik und Telekommunikation BIT Lösungszentrum E-Government sedex: Manuel de l utilisateur du proxy Installation, configuration et utilisation Proxy Nom du projet: sedex Numéro du projet: LZPSB Version: V4.0 Statut: en travail en examen autorisé pour l utilisation Groupe de personnes concernées Auteur: Approbation: Utilisateurs: Pour information: Lorenz Ammon, Thomas Wenger Stefan Leisi Fournisseurs de logiciel, OFS Suivi des modifications, examen et approbation Quand Version Qui Description V0.1 Lorenz Ammon Version initiale V0.7 Stephan Tschäppät Proof-Reading / Layout V0.8 Lorenz Ammon Messages d'erreur détachés (nouveau chapitre). Ajout du message d erreur DTD V0.9 Lorenz Ammon Ajout du chapitre problèmes connus. Point final UPI Query: Erreur dans le nom d une propriété corrigée V1.0 Lorenz Ammon Chapitre 2.2.5: Adaptation de la configuration du proxy. Chapitre problèmes connus adapté. Chapitre Migration des fichiers de configuration ajouté. Indication quant au statut béta retirée du chapitre introduction. Chapitre remanié. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx

2 Suivi des modifications, examen et approbation Quand Version Qui Description V1.1 Lorenz Ammon Correction de la requête de test UPI-Query: getahvvn : L'ancienne requête est valable uniquement pour un NAVS13 et non pas pour un NAVS V1.2 Lorenz Ammon Le nouveau UPI-Compare a été intégré à ce document V1.3 Lorenz Ammon Les URL de test des points finaux proposés par les prestataires de service ont été ajoutées V1.4 Lorenz Ammon Adaptations en vue de la release V1.5 Stephan Tschäppät Proof-Reading / Layout V1.6 Jörg Böhlen Approbation V1.7 Lorenz Ammon Adaptations selon commentaires/feedback de Michel Gentile. Documentation de la variante de démarrage Unix utilisant le Service-Wrapper de Tanuki V1.8 Jörg Böhlen Approbation V1.9 Lorenz Ammon Adaptations nécessaires suite au remplacement de SOAP-over-OSCI (release 2.2.0) V2.0 Lorenz Ammon Adaptations en prévision de la nouvelle release Informations quant au schéma V1.2 de UPI- Query. Options de configuration Connection- Timeout et Connections per Host V2.1 Lorenz Ammon Adaptations en prévision de la nouvelle release 3.0 (chapitre Migration des fichiers de configuration, Problèmes connus ) V2.1 Stefan Leisi Approbation V3.0 Thomas Wenger Adaptations au nouveau client sedex contrôlé par le controller sedex. Le logging comprend un nouveau log technique et un log d accès V3.0 Stefan Leisi Approbation pour la release V3.0.1 Michel Gentile Changement du numéro de version V3.0.3 Markus Antener Changement du numéro de version V3.0.4 Michel Gentile Adaptation des points finaux «test» pour le service web UPI V4.0 Markus Antener Adaptations au nouveau renouvellement du certificat, eumzugch Documents référencés [Client] sedex-client 5.0.0: Installation and User manual [UPI] UPI (Unique Personal Identifier) Interface [sedex] Manuel sedex Termes et abréviations CdC Centrale de Compensation DNS Domain Name System DTD Document Type Declaration sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 2 / 31

3 Termes et abréviations HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol Secure OFS Office fédéral de la Statistique, Neuchâtel SOAP Simple Object Access Protocol soapui Un outil permettant de tester les services web ( UPI Unique Personal Identifier VM Virtual Machine sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 3 / 31

4 Table des matières 1 INTRODUCTION Objectif du document Le proxy 7 2 INSTALLATION ET CONFIGURATION Installation à l aide du programme d installation Installation sans programme d installation Définition des autorisations d exécution sous Unix Activer le proxy dans le controller Configuration du proxy Configuration des ports du proxy Configuration du proxy web Configuration du certificat sedex Configuration du certificat du prestataire de services Configuration du mécanisme de déploiement Configuration de l historisation Options de configuration propre aux services Configuration du point final du prestataire de service Connection-Timeout Connections per Host Autorisations d accès spéciales Keystore-Properties Truststore et truststore-properties Répertoire des logs Répertoire de déploiement Configuration de l utilisation de la mémoire principale Configuration de la mémoire de la machine virtuelle Désinstallation 15 3 EXPLOITATION Exigences Exigences fondamentalement identiques à celles de l adaptateur Ports Mémoire principale Exécution du proxy Historisation Le log technique Le log d accès Changement de la configuration après l installation 18 4 RENOUVELLEMENT DU CERTIFICAT Renouvellement automatique du certificat Renouvellement manuel du certificat Renouvellement des certificats de serveur de confiance Renouvellement du certificat du participant sedex 19 sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 4 / 31

5 5 AJOUT OU MISE À JOUR DES SERVICES WEB Ajout de nouveaux services web Mise à jour d un existant 20 6 UTILISATION Services web disponibles UPI Query UPI Compare CheckSedex PlausEx Sasis / VeKa Partnerws / UID Echo 23 7 TESTS ET REQUÊTES DE TEST Tests Proxy atteignable? UPI-Query atteignable? UPI-Compare atteignable? CheckSedex atteignable? Requêtes de test UPI Query: getahvvn UPI Compare: comparedata CheckSedex 26 8 MESSAGES D ERREUR Erreur SOAP Must not contain a DTD Problèmes de déploiement Fichier d arrêt dans le répertoire de déploiement Proxy inatteignable Proxy inatteignable sans signaler d erreur 28 9 PROBLÈMES CONNUS Problèmes existant actuellement Problèmes résolus Un SOAP-Header manquant provoque une exception dans le mode debug Timeout locaux suite à des erreurs HTTP auprès du prestataire de service No route to host The namespace prefix nsany was not declared 29 sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 5 / 31

6 10 MIGRATION DES FICHIERS DE CONFIGURATION De la release 3.0 à la De la release à la De la release à la Illustrations ILLUSTRATION 1: CONCEPT DU PROXY SERVICE WEB... 8 sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 6 / 31

7 1 Introduction 1.1 Objectif du document Ce document contient les informations nécessaires à l instauration du proxy de sedex au niveau des fournisseurs de logiciels. 1.2 Le proxy Le client sedex se compose du controller, de l adaptateur et du proxy. Pour pouvoir être utilisé, ce dernier doit être installé en même temps que le reste des composants. Il n est pas possible de n installer que le proxy car il est dépendant de l adaptateur et du controller. Le controller permet quant à lui de contrôler et de surveiller l adaptateur et le proxy sedex (start, stop, etc.). Le proxy sert d intermédiaire entre un prestataire de un utilisateur. Les caractéristiques suivantes du proxy allège le travail des utilisateurs: Réplication locale des services web des prestataires de services Récupération de la requête HTTP de l appelant Chiffrement de la requête de l appelant via le certificat du participant Connexion au du prestataire de service désiré Transmission de la requête via HTTPS au du prestataire de service Réception du résultat (reçu en HTTPS du Internet) Déchiffrement du résultat Transmission via HTTP du résultat à l utilisateur Grâce aux traitements du proxy, l appelant ne s occupe donc que de requêtes en HTTP. Toute la partie sécurisation (chiffrements et transmissions) est prise en charge par le proxy. Du coup, puisque c est le certificat du client sedex qui est utilisé, la transmission d un nom d utilisateur et d un mot de passe est inutile. L Illustration 1 présente, sous forme d une vue d ensemble, le fonctionnement du proxy service web. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 7 / 31

8 Système participant Fournisseur de prestations Applications Client sedex Certificat... Logiciel de la commune Appel Réponse Point final Point final Proxy service web Requête authentifiée Réponse authentifiée Point final Point final UPIQuery (CdC) CheckSedex (sedex)... Configuration des points finaux Illustration 1: Concept du proxy Les appels de services web utilisant les points finaux locaux du proxy s effectuent sans indiquer de caractéristique de sécurité comme p.ex. les certificats. Etant donné que seuls les participants sedex physiques possèdent un certificat et un adaptateur, le proxy ne peut être utilisé qu auprès de participants sedex physiques. Le proxy est prévu pour des participants sedex habituels, comme par exemple les registres des habitants communaux. Il n a pas été conçu pour des volumes d appels tels qu ils peuvent survenir lors d une agrégation de participants. Un tel scénario d agrégation peut par exemple survenir lorsque le canton de Berne désire rassembler individuellement chaque appel de et retransmettre ceux-ci individuellement au prestataire de service. La réalisation d un tel scénario nécessiterait la construction d une infrastructure informatique propre à une agrégation de participants, qui prendrait en charge les appels de services web de ces participants en fonction d un critère permettant d identifier le participant. Il faut partir du principe que lors d un tel scénario, cette infrastructure servirait également à transférer des appels de services web récoltés vers le prestataire de service, en les authentifiant au passage à l aide du certificat sedex. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 8 / 31

9 2 Installation et configuration L installation du proxy se fait en même temps que le reste du client sedex. Celui-ci peut être installé automatiquement à l aide du programme d installation pour Windows ou manuellement (voir [Client]). Le programme d installation propose par défaut d installer uniquement l adaptateur et le controller. Pour installer également le proxy service web, il faut cocher la case correspondante lors de l installation. Les informations nécessaires pour configurer manuellement un proxy après une installation automatique peuvent être trouvées au chapitre Installation à l aide du programme d installation Lorsque l adaptateur sedex est installé à l aide du programme d installation Windows, l utilisateur est invité à indiquer le port TCP par lequel le proxy web service propose ses services. Le port du proxy doit absolument être modifié si le port 8080 (proposé par défaut) est déjà utilisé par une autre application. De plus, il faut s assurer que le proxy soit en mesure de recevoir des appels entrants. En outre, il doit pouvoir communiquer avec Internet à travers HTTP et HTTPS. Ceci nécessite en général une configuration correspondante dans les pare-feu. Le pare-feu de Windows peut par exemple demander s il faut autoriser ou bloquer la communication avec la machine virtuelle Java lors du premier démarrage du proxy. Si une telle question est posée, il faut répondre par l affirmative. 2.2 Installation sans programme d installation Si l installation de l adaptateur est faite de manière manuelle, le proxy devra également être configuré manuellement. Indication: Le proxy nécessite une installation entièrement fonctionnelle de l adaptateur, conformément à la description contenue dans le document [Client]. /!\ Attention: La possibilité de garder les mêmes configurations manuelles entre deux versions n est pas garantie. Il est de plus particulièrement déconseillé de partir du principe que le proxy se basera, également à l avenir, directement sur une distribution Axis2. Ci-après, le dossier d installation du client sedex est désigné sous le nom ClientDir Définition des autorisations d exécution sous Unix Lorsque le proxy est installé sur une machine Unix, il faut, suite à l installation, autoriser l exécution des scripts. A cet effet, les commandes suivantes doivent être exécutées dans un script shell: 1. Se placer dans le répertoire ClientDir/adapter/bin 2. Exécuter l instruction: chmod +x *.sh 3. Se placer dans le répertoire ClientDir/adapter/axis2/bin 4. Exécuter l instruction: chmod +x *.sh Activer le proxy dans le controller Pour que le proxy puisse être automatiquement démarré par le controller sedex, il doit être activé dans la configuration du controller sedex : sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 9 / 31

10 Fichier de configuration : ClientDir/controller/conf/sedexController.properties wsproxy.enabled=true Configuration du proxy Le chemin sous lequel le client sedex est installé doit être indiqué dans la configuration du proxy : Fichier de configuration : ClientDir/adapter/conf/wsproxy.properties sedex.home=c:/program Files/SedexClient Cela équivaut au répertoire de base dans le fichier ZIP. Attention : il est important d utiliser le séparateur " / " également sous Windows Configuration des ports du proxy Le port par lequel le proxy réplique localement les services des prestataires de services est défini dans le fichier de configuration suivant: Fichier de configuration: ClientDir/adapter/axis2/conf/axis2.xml Dans ce fichier de configuration, à l intérieur de l élément XML transportreceiver, se trouve le paramètre suivant: Paramètre: <parameter name="port">8080</parameter> La valeur par défaut du port du proxy est Il est important de vérifier si le port spécifié n est pas déjà utilisé par une autre application. En outre, il faut contrôler si le proxy peut recevoir des appels entrants Configuration du proxy web Si dans l environnement du proxy, l accès à l Internet s effectue via un proxy HTTP (proxy web), il faut, pour permettre l accès HTTP, ajouter les paramètres correspondants dans le fichier de configuration suivant: Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Les propriétés suivantes doivent y être configurées en remplaçant "proxy.domain.ch, "8080, "name et "pwd par les valeurs correspondantes. Paramètres: sedex.wsproxy.webproxy.host=proxy.domain.ch sedex.wsproxy.webproxy.port=8080 sedex.wsproxy.webproxy.user=name sedex.wsproxy.webproxy.password=pwd Si le proxy n exige aucune authentification à l aide d un nom d utilisateur et d un mot de passe, les deux dernières lignes peuvent être supprimées ou mises en commentaire en insérant un "# en début de ligne. Si aucun proxy web ne doit être utilisé, il faut supprimer ou mettre en commentaire chacune des lignes ci-dessus Configuration du certificat sedex Le proxy doit pouvoir accéder au certificat sedex. A cette fin, l emplacement, le type et le mot de passe du certificat sont à indiquer dans un fichier de configuration keystore sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 10 / 31

11 séparé. Ce fichier de configuration keystore est référencé dans le fichier de configuration principal du proxy. En partant du principe que le fichier de configuration keystore se trouve sous le chemin suivant: Fichier de configuration keystore:clientdir/adapter/conf/wsproxykey.properties Il faut y définir les propriétés et les valeurs correspondantes suivantes: Paramètres: sedex.wsproxy.keystore.path=clientdir/adapter/zertifikate/prod-bit/cert.p12 sedex.wsproxy.keystore.password=certpwd sedex.wsproxy.keystore.type=pkcs12 Le fichier de configuration keystore doit être référencé comme suit dans le fichier de configuration principal du proxy : Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Paramètre: sedex.wsproxy.keystore.properties.path=clientdir/adapter/conf/wsproxykey.properties Configuration du certificat du prestataire de services Les certificats des prestataires de services auquel le proxy fait confiance sont intégrés dans un fichier truststore. Le proxy doit donc connaître le chemin, le type, le mot de passe et le numéro de version du fichier truststore. L emplacement du truststore doit être spécifié comme suit: Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Paramètre (tout sur une seule ligne): sedex.wsproxy.serviceclient.ssl.truststore.path= ClientDir/adapter/zertifikate/prod-bit/wsyproxytrust.jks Le type, le mot de passe ainsi que le numéro de version du truststore sont spécifiés de la manière suivante: Fichier de configuration: ClientDir/adapter/zertifikate/prod-bit/wsproxytrust.jks.properties Paramètres: sedex.wsproxy.truststore.password=trustme sedex.wsproxy.truststore.version=versionnr sedex.wsproxy.truststore.type=jks En plus du fichier truststore wsproxytrust.jks, il existe donc dans le même répertoire un fichier de propriétés nommé wsproxytrust.jks.properties qui décrit le fichier truststore correspondant. S il manque le fichier de description correspondant à un truststore donné, le proxy ne pourra pas se servir du fichier truststore. Les truststores sont distribués par l exploitant de sedex sous forme de deux fichiers assortis. La propriété de la version est définie par l exploitant de sedex et ne doit en aucune façon être modifiée à la main Configuration du mécanisme de déploiement Le proxy implémente un mécanisme de déploiement permettant à l adaptateur sedex de fournir des mises à jour au proxy durant son fonctionnement. De telles mises à jour sont en réalité des fichiers que le proxy prend en charge dans un dossier spécial de déploiement et qu il installe selon certaines consignes. L installation d une mise à jour peut déclencher le redémarrage du proxy. C est pourquoi il est pos- sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 11 / 31

12 sible de définir la période durant laquelle le proxy installe les mises à jour. Pour l heure, le proxy supporte (à travers le mécanisme de déploiement) l installation automatisée de nouveaux truststores et de nouveaux certificats sedex. La configuration du mécanisme de déploiement est brièvement expliquée ci-dessous. Le dossier de déploiement, dans lequel le proxy recherche des mises à jour, est configuré comme suit: Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Paramètre: sedex.wsproxy.server.deploydir.path=clientdir/adapter/deploy /!\ Attention: Le proxy ne recevra des mises à jour de son adaptateur sedex que si le répertoire indiqué dans la configuration de l adaptateur, utilisé par l adaptateur pour déposer les mises à jour, est identique au répertoire de déploiement configuré dans le proxy. Il est possible d indiquer au proxy de n installer les mises à jour du dossier de déploiement qu à certaines périodes de la journée. Les instructions correspondantes sont définies de la manière suivante: Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Paramètres: sedex.wsproxy.server.deployhours.start=startinghour sedex.wsproxy.server.deployhours.start=endinghour Le proxy installera les mises à jour chaque jour, entre les heures «startinghour» et «endinghour». En utilisant les valeurs startinghour=0 et endinghour=23, il n y a aucune limitation et les mises à jour seront donc installées à toute heure de la journée. Les valeurs startinghour=1 et endinghour=3 permettent uniquement les mises à jour nocturnes entre 01:00 et 03:59. Durant le laps de temps défini, le proxy vérifie périodiquement (toutes les 5 minutes) le répertoire de déploiement à la recherche de mises à jour Configuration de l historisation Le proxy génère deux fichiers log: un log technique, contenant les erreurs rencontrées, les avertissements et les informations concernant la configuration du proxy, durant son fonctionnement un log d accès, contenant tous les appels de services web que le proxy a effectués. La configuration des deux fichiers log se fait dans le fichier de configuration Logback: Fichier de configuration: ClientDir/adapter/conf/wsproxy-logback.xml On indique, dans ce fichier de configuration, dans quels fichiers du proxy les enregistrements doivent être écrits. Etant donné que le proxy gère une historisation roulante sur plusieurs fichiers, il doit être autorisé à créer et modifier des fichiers dans le dossier où se trouvent les fichiers indiqués. Configuration du fichier log technique: <appender name="wsproxy-technical" class="ch.qos.logback.core.rolling.rollingfileappender"> <File>ClientDir/logs/wsproxy/wsproxy-technical.log</File> [ ] sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 12 / 31

13 </appender> Configuration du fichier log d accès: <appender name="wsproxy-access" class="ch.qos.logback.core.rolling.rollingfileappender"> <File>ClientDir/logs/wsproxy/wsproxy-access.log</File> [ ] </appender> Il est possible de définir le seuil du log des classes du proxy à ERROR, INFO, WARN ou DEBUG. Le plus grand nombre d informations est obtenu en fixant le seuil à DEBUG, alors que le seuil ERROR ne permet d afficher que peu d informations. Le seuil INFO devrait être choisi lors d une utilisation productive. Configuration du seuil du log technique: <logger name="ch.admin.bit.sedex.wsproxy" level="info" /> Configuration du seuil du log d accès: Dans le log d accès, tous les enregistrements sont réglés sur le seuil INFO. Le log d accès peut cependant être facilement désactivé, par exemple en montant le seuil pour ce log à ERROR. <logger name="wsproxyaccesslogfile" level="info" additivity="false"> </logger> <appender-ref ref="wsproxy-access" /> 2.3 Options de configuration propre aux services Certaines options de configuration peuvent être configurées spécifiquement pour certains services proposés. Ces options sont sommairement décrites dans les chapitres suivants Configuration du point final du prestataire de service Les points finaux proposés par le proxy ne sont qu'une réplication des points finaux des prestataires de service. Ceux-ci peuvent être définis dans le fichier de configuration suivant: Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Pour chaque répliqué, les paramètres correspondants peuvent être définis dans ce fichier. Si pour l un des services web aucun paramètre n est défini, l adresse productive standard du prestataire de service est utilisée par défaut. Durant la phase de développement et de test, il est recommandé d utiliser les instances de test mises à disposition par le prestataire de service. A cet effet, il faut changer la configuration comme suit. Pour l exploitation productive, il est au contraire déconseillé de configurer les points finaux des prestataires de services. Configuration UpiQueryWebservice: sedex.wsproxy.upiqueryservice.target.endpoint.url= Configuration UpiCompareWebservice: sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 13 / 31

14 sedex.wsproxy.upicompareservice.target.endpoint.url= Connection-Timeout L'option Connection-Timeout permet de définir, en millisecondes, l'intervalle durant lequel le proxy attend une réponse du prestataire de service. Une configuration explicite du timeout de connexion est recommandée uniquement lorsque des problèmes apparaissent dans le cadre de l'utilisation productive. Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Paramètre: sedex.wsproxy.servicename.timeout=60000 Le terme servicename peut être remplacé par UPICompareService (60000), UPIQueryService (360000) ou CheckSedexWebService (60000). Si aucune configuration correspondante n'est effectuée, les valeurs par défaut indiquées entre parenthèses sont appliquées Connections per Host L'option "Connections per Host" permet de définir, par service, le nombre maximal de connexions simultanées que le proxy peut ouvrir simultanément vers un prestataire de service. Une configuration explicite de l'option "Connections per Host" est recommandée uniquement lorsque des problèmes apparaissent dans le cadre de l'utilisation productive. Fichier de configuration: ClientDir/adapter/conf/wsproxy.properties Paramètre: sedex.wsproxy.servicename.connections.perhost.default=5 Le terme servicename peut être remplacé par UPICompareService (5), UPIQueryService (10) ou CheckSedexWebService (5). Si aucune configuration correspondante n'est effectuée, les valeurs par défaut indiquées entre parenthèses sont appliquées. 2.4 Autorisations d accès spéciales Le proxy nécessite fondamentalement un accès en lecture à tous les fichiers et dossiers au sein de son dossier d installation. De plus, le proxy nécessite des autorisations additionnelles spéciales pour certains fichiers et certains répertoires. Ces derniers sont listés ci-dessous: Keystore-Properties Le proxy doit pouvoir remplacer le fichier keystore-properties décrit dans le chapitre Truststore et truststore-properties Le proxy doit pouvoir remplacer les fichiers truststore et truststore-properties décrits dans le chapitre De plus, à des fins de sauvegardes, le proxy doit être en mesure de générer et modifier des fichiers dans le répertoire des truststores Répertoire des logs Le proxy doit pouvoir générer et modifier des fichiers de logs (décrits dans le chapitre 2.2.9) dans le dossier, respectivement les dossiers de logs. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 14 / 31

15 2.4.4 Répertoire de déploiement Le proxy doit pouvoir générer et supprimer les fichiers de mises à jour (décrits dans le chapitre 2.2.8) dans le répertoire de déploiement, mais aussi lister le contenu de celui-ci. 2.5 Configuration de l utilisation de la mémoire principale Si nécessaire, il est possible d adapter, avec toute la prudence qui s impose, la limite inférieure et supérieure de la mémoire allouée par la machine virtuelle Java au proxy service web Configuration de la mémoire de la machine virtuelle La Java-VM du proxy est démarrée par le controller sedex via les scripts de démarrage du proxy : Fichier de configuration Windows: ClientDir/adapter/bin/wsproxy-start.bat Fichier de configuration Unix: ClientDir/adapter/bin/wsproxy-start.sh Il est possible de définir la mémoire ou d entreprendre des réglages supplémentaires de la VM dans ces fichiers en tant qu options Java: Configuration: JAVA_OPTS=-Xms128M -Xmx256M [autres options] Indication: Lors de ces modifications, les options existantes de Java ne doivent pas être effacées! 2.6 Désinstallation Le proxy fait partie du client sedex et sera installé avec ce dernier. Pour cette raison, le proxy sera également désinstallé lorsque l'on désinstalle le client (voir [Client]). sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 15 / 31

16 3 Exploitation Ci-après, le dossier d installation du client sedex est désigné sous le nom ClientDir/adapter. 3.1 Exigences Exigences fondamentalement identiques à celles de l adaptateur Le proxy fait partie intégrante de l adaptateur sedex et pose des exigences fondamentalement identiques à ce dernier (voir [Client]). Les exigences supplémentaires du proxy sont brièvement énumérées ci-après Ports Entrant Le port par lequel le proxy réplique localement les services des prestataires de services doit être ouvert pour les connexions entrantes. Le port par défaut du proxy service web est Sortant Le proxy transmet les appels aux prestataires de services par HTTPS (port 443). Par conséquent, les connexions sortant du proxy doivent être autorisées pour ce protocole (port). Il faut en outre pouvoir atteindre les serveurs des prestataires de services (voir chapitre 6) Mémoire principale Le proxy sedex fonctionne à l aide d une machine virtuelle Java spécifique. La mémoire que le proxy utilise doit donc être additionnée à celle utilisée par le controller sedex et par l adaptateur sedex. Le proxy configure la mémoire virtuelle Java (heap) comme suit: Heap minimal alloué: 128 Mo Heap maximal allouable: 256 Mo Au besoin, ces valeurs par défaut peuvent être changées (voir chapitre 2.5). 3.2 Exécution du proxy Le proxy n est pas démarré directement, mais est démarré, arrêté et surveillé par le controller sedex. Une notice concernant l exécution du controller sedex peut être trouvée dans [Client]. Indication: Il n est pas prévu que le proxy puisse être démarré ou arrêté directement, c est-à-dire sans l aide du controller sedex. Au cas où le proxy démarre sans erreur mais qu il n est malgré tout pas atteignable, vérifier la configuration du port du proxy (voir chapitre 2.2.2). Il faut faire en sorte qu un port valide et libre ait été entré. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 16 / 31

17 3.3 Historisation Le proxy génère deux fichiers log différents: le log technique le log d accès Les chapitres suivants décrivent ces deux fichiers Le log technique Durant son fonctionnement, le proxy génère un fichier log contenant les erreurs rencontrées, les avertissements et les informations concernant la configuration du proxy service web. L historisation roulante (c.-à-d. sur plusieurs fichiers) s effectue par défaut dans le fichier suivant: Fichier log: ClientDir/logs/wsproxy/wsproxy-technical.log La configuration de l historisation est décrite dans le chapitre Le log d accès Le proxy génère un log d accès, dans lequel sont protocolés les appels traités par le proxy sedex. L historisation roulante (c.-à-d. sur plusieurs fichiers) s effectue par défaut dans le fichier suivant: Fichier log: ClientDir/logs/wsproxy/wsproxy-access.log La configuration de l historisation est décrite dans le chapitre Formatage du log d accès Les enregistrements du log d accès sont composés d'au moins dix champs séparés par des espaces: Champ Description date Date de l enregistrement au format ISO 8601: YYYY-MM-DD Ex: time Heure de l enregistrement au format ISO 8601: hh:mm:ss.f Ex: 16:43: duration Durée de l appel (Round Trip Time) en millisecondes. Ex: 129 client Adresse IP du client qui appelle. Ex: result-code Code de résultat (chaine de caractères). Exemple: OK Fault_HTTP_Get_Not_Allowed req-bytes Nombre de bytes de la requête SOAP. rsp-bytes Nombre de bytes de la réponse SOAP. req-endpoint Point final (URL) du prestataire de service. Réponse standard pour appels réussis. Faute SOAP avec indication sur le type de faute. Indication: Tous les espaces sont remplacés par des underscores ( _ ). req-method Nom de la méthode du qui est appelé dans la requête. orig-req Point final (URL) sur le proxy. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 17 / 31

18 optional fields Indication: Tous les espaces sont remplacés par des underscores ( _ ). A l avenir, différents champs s ajouteront ici. 3.4 Changement de la configuration après l installation Les changements de configuration intervenant après l installation peuvent être effectués conformément à la description du chapitre 2.2. Tout changement impliquant un des fichiers de configuration présentés nécessite le redémarrage du proxy via le controller sedex. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 18 / 31

19 4 Renouvellement du certificat 4.1 Renouvellement automatique du certificat Le proxy ne peut pas renouveler son certificat de lui-même. Toutefois, le proxy propose, à travers son mécanisme de déploiement, un procédé permettant de remplacer le truststore ainsi que le certificat du participant qui est utilisé pour le transport sécurisé des données. Ce mécanisme de déploiement est utilisé autant par l adaptateur sedex que par le controller sedex. Lorsque le controller sedex renouvelle son certificat d organisation, celui-ci le fournit également au proxy. En outre, l adaptateur sedex peut aussi recevoir un nouveau fichier truststore qu il dépose dans le répertoire de déploiement de son proxy dans le but d être installé. Au final, le proxy est donc mis à jour au travers de son adaptateur et de son controller. 4.2 Renouvellement manuel du certificat Renouvellement des certificats de serveur de confiance Lors de l ajout de services web supplémentaires (ou pour d autres raisons), il peut devenir nécessaire de renouveler la liste des certificats de serveur de confiance. A cet effet, l exploitant sedex met à disposition un nouveau truststore qui se compose de deux fichiers, p.ex. truststore.jks et truststore.jks.properties. Ces deux fichiers doivent être déposés conjointement dans un dossier accessible par le proxy et l emplacement des fichiers doit être spécifié dans la configuration du proxy, conformément au chapitre Si les fichiers de l ancien truststore sont écrasés par les fichiers du nouveau truststore, aucune modification n est nécessaire dans le fichier de configuration du proxy. Afin de remplacer les fichiers truststore et adapter la configuration, le proxy doit être redémarré Renouvellement du certificat du participant sedex Le certificat du participant sedex est installé en même temps que l adaptateur sedex et est uniquement référencé par le proxy. Pour plus de renseignements au sujet du renouvellement de ce certificat, voir [Client]. Suite au renouvellement du certificat du participant, il est indispensable d adapter la configuration du proxy à l utilisation du nouveau certificat, conformément au chapitre L adaptation de la configuration nécessite un arrêt et un redémarrage du proxy. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 19 / 31

20 5 Ajout ou mise à jour des services web Ci-après, le dossier d installation du client sedex est désigné sous le nom ClientDir. 5.1 Ajout de nouveaux services web Les services web supplémentaires, que le proxy doit dorénavant pouvoir proposer, sont distribués en tant qu archives sous la forme de fichiers *.aar. Concrètement, l installation d une telle archive se limite à la copie de l archive correspondante dans le dossier suivant: Dossier d installation: ClientDir/adapter/axis2/repository/services Lors de l ajout de nouveaux services web, il pourrait être nécessaire d adapter la liste des certificats de serveur de confiance (voir chapitre 2.2.7). Le redémarrage du proxy n est nécessaire que si l ajout d un nouveau service web est accompagné d un changement dans les fichiers de configuration ou d un changement dans la liste des certificats de serveur de confiance. 5.2 Mise à jour d un existant La mise à jour d un existant consiste à distribuer une nouvelle version de l archive existante. Concrètement, l installation d une telle archive se limite à l écrasement de l archive correspondante dans le dossier suivant: Dossier d installation: ClientDir/adapter/axis2/repository/services Le redémarrage du proxy n est nécessaire que si l ajout d un nouveau service web est accompagné d un changement dans les fichiers de configuration ou d un changement dans la liste des certificats de serveur de confiance (voir chapitre 2.2.7). sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 20 / 31

21 6 Utilisation 6.1 Services web disponibles Ci-après, wsproxyhost désigne l adresse IP ou le nom d hôte DNS de la machine sur laquelle se trouve le proxy, tandis que wsproxyport désigne le port par lequel le proxy propose ses services UPI Query L interface UPI Query est à disposition pour interroger en ligne la CdC. La documentation pour cette interface se trouve dans le document [UPI]. Ce peut également être atteint directement via la CdC (voir ci-dessous). Afin de pouvoir proposer correctement l interface UPI Query, le proxy doit être en mesure d accéder au serveur correspondant de la CdC via HTTPS. La version 1.2 du schéma UPI Query apporte entre autre la nouvelle opération "getcancelledandinactiveahvvn". L'appel de cette opération peut prendre un certain temps (quelques minutes), pour un laps de temps de quelques jours déjà. C'est pourquoi les options de configuration "Connection-Timeout" et "Connections per Host" ont été spécifiées différemment pour UPI Query (voir chapitre et 2.3.3). URL du point final URL du WSDL L accès direct au UPI Query à l aide du certificat sedex est possible en utilisant les points finaux suivants: Production: Test: UPI Compare ( ( La CdC met à disposition l interface UPI Compare qui permet d effectuer des comparaisons en ligne. La documentation pour cette interface se trouve dans le document [UPI]. Ce service web peut également être atteint directement via la CdC (voir ci-dessous). Afin de pouvoir proposer correctement l interface UPI Compare, le proxy doit être en mesure d accéder au serveur correspondant de la CdC via HTTPS. URL du point final URL du WSDL L accès direct au UPI Compare à l aide du certificat sedex est possible en utilisant les points finaux suivants: Production: sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 21 / 31

22 Test: ( ( CheckSedex CheckSedex permet d effectuer des interrogations quant à la disponibilité et les possibilités d utilisation de sedex. La description de cette interface se trouve dans le document [sedex]. Ce peut également être atteint directement via la passerelle de sedex (voir ci-dessous). Afin de pouvoir proposer correctement l interface CheckSedex, le proxy doit être en mesure d accéder à la passerelle de sedex via HTTPS. URL du point final URL du WSDL L accès direct au CheckSedex (de sedex) à l aide du certificat sedex est possible en utilisant les points finaux suivants: Production: PlausEx ( Pour les requêtes en rapport avec eumzugch, le PlausEx peut être utilisé. URL du point final URL du WSDL Webservice Webservice?wsdl L accès direct au plausex à l aide du certificat sedex est possible en utilisant les points finaux suivants: Production: ( Sasis / VeKa Pour les requêtes en rapport avec eumzugch, le Sasis peut être utilisé. URL du point final URL du WSDL ery ery?wsdl L accès direct au sasis à l aide du certificat sedex est possible en utilisant les points finaux suivants: sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 22 / 31

23 Production: ( Partnerws / UID Pour les requêtes en rapport avec eumzugch, le UID peut être utilisé. URL du point final URL du WSDL Services Services?wsdl L accès direct au uid à l aide du certificat sedex est possible en utilisant les points finaux suivants: Production: Echo ( Le Echo représente une possibilité simple de tester si le proxy est disponible ou non. Comme son nom l indique, le Echo se contente fondamentalement de répondre par ce qu on lui a écrit, à l exception toutefois qu il ajoute à la réponse un timbre temporel (timestamp). Ce est uniquement disponible à travers le proxy et a été imaginé à des fins de développement et de test. Les logiciels en environnement productif ne doivent en aucun cas être dépendants de l existence ou des fonctionnalités du Echo. Il n existe aucune garantie assurant l existence sous la forme actuelle ou même l existence en elle-même du Echo dans les futures versions du proxy. URL du point final SOAP 1.1 URL du point final SOAP 1.2 URL du WSDL /wsproxy/services/echows.echowshttpsoap11endpoint /wsproxy/services/echows.echowshttpsoap12endpoint sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 23 / 31

24 7 Tests et requêtes de test 7.1 Tests Ci-après, wsproxyhost désigne l adresse IP ou le nom d hôte DNS de la machine sur laquelle se trouve le proxy, tandis que wsproxyport désigne le port par lequel le proxy propose ses services Proxy atteignable? Afin de tester si le proxy est atteignable sous le port configuré, on peut appeler l URL suivante depuis le navigateur Internet de la machine à analyser: Si le proxy est atteignable, le navigateur affiche une page web contenant le document WSDL du echo. Ce document décrit les opérations mises à disposition par le UPI-Query atteignable? Afin de découvrir si le proxy a la possibilité d appeler le UPI-Query, on peut appeler l URL suivante à l aide du navigateur Internet installé sur la machine où se trouve le proxy : Afin de rendre l accès à cette URL possible, il faut auparavant avoir importé le certificat sedex dans le navigateur Internet utilisé. Lors de l appel de l URL ci-dessus, le certificat sedex sera interrogé, puis une page incluant entre autre la phrase Hello! This is an Axis2 Web Service! sera affichée UPI-Compare atteignable? Afin de découvrir si le proxy a la possibilité d appeler le UPI- Compare, on peut appeler l URL suivante à l aide du navigateur Internet installé sur la machine où se trouve le proxy : Afin de rendre l accès à cette URL possible, il faut auparavant avoir importé le certificat sedex dans le navigateur Internet utilisé. Lors de l appel de l URL ci-dessus, le certificat sedex sera interrogé, puis une page incluant entre autre la phrase Hello! This is an Axis2 Web Service! sera affichée CheckSedex atteignable? Afin de découvrir si le proxy a la possibilité d appeler le CheckSedex, on peut appeler l URL suivante à l aide du navigateur Internet installé sur la machine où se trouve le proxy : Afin de rendre l accès à cette URL possible, il faut auparavant avoir importé le certificat sedex dans le navigateur Internet utilisé. Lors de l appel de l URL ci-dessus, le certificat sedex sera interrogé, puis une page incluant entre autre la phrase Welcome to the home page sera affichée. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 24 / 31

25 7.2 Requêtes de test Les requêtes SOAP ci-dessous vous permettent de tester la disponibilité du proxy service web et du prestataire de service en arrière-plan. Ces requêtes peuvent, à titre d exemple, être envoyées à l aide du programme gratuit soapui ( au point final correspondant du proxy UPI Query: getahvvn Dans la requête ci-dessous, le terme "Numéro AVS" est utilisé pour désigner un numéro AVS-11 valable. <soapenv:envelope xmlns:soapenv=" xmlns:ns=" xmlns:ns1=" <soapenv:header/> <soapenv:body> <ns:getahvvnrequest> <ns:personidentification> <ns:localpersonid> <ns1:personidcategory>ch.ahv</ns1:personidcategory> <ns1:personid>numéro AVS</ns1:personId> </ns:localpersonid> </ns:personidentification> </ns:getahvvnrequest> </soapenv:body> </soapenv:envelope> UPI Compare: comparedata La requête suivante compare les données "nom", "prénom", date de naissance "yyyy-mmdd", nationalité "0" (Suisse) et sexe "1" (masculin) au moment "dateexport" avec les données stockées à la CdC sous "numéroassuré". <soapenv:envelope xmlns:soapenv=" xmlns:ns=" xmlns:ns1=" xmlns:ns2=" <soapenv:header/> <soapenv:body> <ns:comparedatarequest> <ns:exportdate>dateexport</ns:exportdate> <ns:datatocompare> <ns:ahvvn>numéroassuré</ns:ahvvn> <ns:firstnames>prénom</ns:firstnames> sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 25 / 31

26 <ns:officialname>nom</ns:officialname> <ns:sex>1</ns:sex> <ns:dateofbirth> <ns1:yearmonthday>yyyy-mm-dd</ns1:yearmonthday> </ns:dateofbirth> <ns:nationality> <ns:nationalitystatus>0</ns:nationalitystatus> </ns:nationality> </ns:datatocompare> </ns:comparedatarequest> </soapenv:body> </soapenv:envelope> CheckSedex Dans la requête ci-dessous, le terme "sedexid" est utilisé pour désigner un identifiant sedex valable. <soapenv:envelope xmlns:soapenv=" xmlns:v1=" <soapenv:header/> <soapenv:body> <v1:checksedexreq> <sendersedexid> sedexid</sendersedexid> <physicalsendersedexid>sedexid</physicalsendersedexid> <messagetype>99</messagetype> <messageclass>0</messageclass> <recipientsedexid>sedexid</recipientsedexid> </v1:checksedexreq> </soapenv:body> </soapenv:envelope> sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 26 / 31

27 8 Messages d erreur 8.1 Erreur SOAP Si lors du traitement d un appel de dans le proxy ou chez le prestataire de service lui-même une erreur apparaît, le proxy tente toujours de retourner une erreur SOAP. Si le prestataire de service à répondu lui-même par une erreur SOAP, le proxy va retourner cette réponse en l état. Le proxy génère des erreurs SOAP propres uniquement lorsqu un problème survient chez le prestataire de service. De telles erreurs sont aussi inscrites dans le log (voir chapitre 3.3.1). Les sections suivantes traitent des possibles raisons de certaines erreurs SOAP prédéfinies Must not contain a DTD Message d erreur: SOAP message MUST NOT contain a Document Type Declaration (DTD) Raison: Ce message d erreur est généré lorsque le du prestataire de service ne répond pas comme prévu par un message SOAP, mais par une page HTML (contenant une DTD). Une telle page HTML contient typiquement un message d erreur d un serveur web ou d un serveur d applications. La page pourrait par exemple signaler que le appelé n est pas à disposition actuellement ou que l appelant n est pas autorisé à utiliser ce service web. Pour voir la page HTML et son message d erreur, il est possible d appeler directement le point final du concerné chez le prestataire de service, par exemple avec soapui ou un navigateur Internet, à condition d utiliser le certificat sedex. 8.2 Problèmes de déploiement Fichier d arrêt dans le répertoire de déploiement Lors de certaines circonstances, le proxy génère un fichier deploy.stop dans le répertoire de déploiement. Tant que ce fichier se trouve dans le répertoire de déploiement, le mécanisme de déploiement du proxy reste bloqué. Afin de débloquer le mécanisme, il faut supprimer le fichier deploy.stop. Cependant, il faudrait au préalable résoudre le problème qui a mené à la génération du fichier d arrêt. Le proxy génère un fichier d arrêt lorsque, suite au traitement d un fichier de mise à jour, celui-ci ne peut être supprimé. La présence du fichier d arrêt assure dans un tel cas que le fichier de mise à jour ne sera pas retraité lors de la prochaine vérification périodique du répertoire de déploiement. La présence d un fichier d arrêt est en règle générale due à un problème d autorisation. Le proxy doit avoir l autorisation de supprimer un fichier de mise à jour du répertoire de déploiement que l adaptateur a déposé auparavant. Avant de supprimer le fichier d arrêt, il faudrait donc toujours vérifier (et le cas échéant adapter) les autorisations sur le répertoire de déploiement. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 27 / 31

28 8.3 Proxy inatteignable Proxy inatteignable sans signaler d erreur Si le proxy démarre sans erreur, mais n est tout de même pas atteignable, il est conseillé de vérifier en premier lieu la configuration du port du proxy (voir chapitre 2.2.2). Le port spécifié doit impérativement être valable et libre. Le port par défaut est sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 28 / 31

29 9 Problèmes connus Les problèmes connus présentés ci-dessous concernent exclusivement le proxy service et non le controller sedex lui-même, resp. l'adaptateur sedex. 9.1 Problèmes existant actuellement A l heure actuelle, aucune erreur n est connue pour la release 4.0 du proxy. 9.2 Problèmes résolus Un SOAP-Header manquant provoque une exception dans le mode debug Concerne: Toutes les releases du proxy version Si le proxy est utilisé en mode debug, qui n'est pas le mode par défaut, un SOAP-Header manquant lors de l'appel SOAP déclenche une exception dans le proxy service web et le appelé n'est pas exécuté. D'autres appels à l'aide du SOAP- Header sont toutefois exécutés Timeout locaux suite à des erreurs HTTP auprès du prestataire de service Concerne: Release du proxy Lorsque plusieurs requêtes générées par le proxy font l'objet d'erreurs HTTP auprès du serveur du prestataire de service, le service correspondant ne sera en règle générale plus disponible, et ce pour une durée indéterminée. Dans ce cas, toute requête ultérieure pour ce service sera refusée par le proxy et recevra systématiquement une erreur Timeout-SOAP. Un redémarrage du proxy résout le problème. La raison du problème est un bug dans la version de Axis qui provoque le blocage des connexions lorsque des erreurs HTTP sont rencontrées, empêchant ainsi subitement l'établissement de connexions au prestataire de service No route to host Concerne: Release 1.0 et du proxy Il a été constaté que le UPI Query du proxy n est pas capable, dans certains environnements Linux, d établir une connexion avec la CdC lorsqu il faut passer par un proxy web. Dans un tel cas, il retourne donc l erreur SOAP "No route to host". Sous Windows, malgré l utilisation d un proxy web, cette erreur n est pas apparue The namespace prefix nsany was not declared Concerne: Release 1.0 et du proxy Certaines requêtes SOAP à l attention du UPI Query, pourtant formées correctement, ne sont pas retransmises correctement par le proxy. Le problème apparaît dans le cadre des espaces de noms lorsque ceux-ci ne correspondent pas à l espace de nom de la requête. Le problème survient spécifiquement lorsque les éléments de cet espace de nom se suivent séquentiellement. Dans ce cas, seul l espace de nom du premier élément est déclaré correctement dans la requête SOAP transférée, ce qui engendre l erreur The namespace prefix nsany was not declared. sedex_webservice_proxy_benutzerhandbuch_v5_0_0_fr.docx 29 / 31