Vous consultez une page technique concernant le logiciel de gestion Mercator. Celle-ci contient des informations spécifiques destinées aux professionnels de Mercator. Souhaitez-vous être redirigés vers des informations plus générales ?


   Ne plus poser cette question

Installation de MercatorPenguinServer

0000002758     -      18/12/2023

MercatorPenguinServer est un web service RESTful API qui permet les échanges entre l'application mobile MercatorPenguin et la base de données de Mercator. Il doit être hébergé sur un serveur Windows sur lequel le rôle IIS (Internet Information Server) est installé. L'installation de ce serveur se fait comme la mise en route d'un site web.

MercatorPenguinServer existe en deux versions, une pour le framework .net classique (4.8) et l'autre pour le framework .net Core (7.0). Chaque version ne peut servir des Mercators que de cette version. Les deux versions peuvent cohabiter sur un même serveur IIS en tant que sites web distincts.

Installation sur base du framework .net classique

  • Sur le serveur IIS, s'assurer que le composant ASP.net est installé.
  • Dézipper le contenu de MercatorPenguinServer.zip dans un répertoire local du serveur (par exemple C:\inetpub\wwwroot_penguin). Ce répertoire ne doit pas être celui de Mercator.

Installation sur base du framework .net Core

  • Sur le serveur IIS, s'assurer que le composant ASP.net est installé.
  • Installer le ASP.NET Core Runtime et le .NET Desktop Runtime téléchargeables à partir de cette page (choisir dans les deux cas Windows X64)
  • Dézipper le contenu de MercatorPenguinServerCore.zip dans un répertoire local du serveur (par exemple C:\inetpub\wwwroot_penguincore). Ce répertoire ne doit pas être celui de Mercator.

Il est nécessaire de disposer sur ce serveur d'une installation de Mercator à jour et fonctionnelle.

Dans la console d'IIS, il faut créer un nouveau site web.

Pour le chemin d'accès, il faut indiquer le répertoire utilisé ci-dessus. 

Il est aussi nécessaire de compléter un nom d'hôte correctement enregistré dans votre DNS : par exemple penguin.domain.com

Ce nouveau site ne requiert aucun paramétrage particulier en matière de sécurité par exemple, si ce n'est qu'il faut donner des droits en écriture sur le sous-répertoire LogFiles. C'est en effet dans ce répertoire que MercatorPenguinServer va écrire les fichiers de log permettant d'enregistrer son activité. Ce même paramétrage est nécessaire sur le sous-répertoire Bin afin de permettre la mise à jour automatique de MercatorTunnel.dll.

Installation sur base du framework .net classique

  • L'application pool associé doit avoir la propriété .NET CLR version à v4.0.030319.

Installation sur base du framework .net Core

  • L'application pool associé doit avoir la propriété .NET CLR version à No Managed Code.
  • Le serveur MercatorPenguinServerCore.exe communique avec une instance propre à chaque dossier Mercator (PenguinServerMercatorInstance.exe) sur un port TCP choisi par le serveur au départ de la valeur mentionnée dans appsettings.json sous le paramètre BaseTcpPort. La valeur par défaut est 15000. Cela signifie que les ports TCP 15000 et supérieurs doivent être accessibles au sein du serveur. (Il n'est cependant pas du tout nécessaire ni même recommandé d'ouvrir ces ports sur le réseau.) Si nécessaire, la valeur de BaseTcpPort peut être adaptée.

Pour des raisons de sécurité, MercatorPenguin ne peut accéder à MercatorPenguinServer qu'en HTTPS. Il est donc obligatoire d'installer un certificat SSL. Le port 443 (https) devra aussi être ouvert et dirigé vers ce serveur. Ce certificat SSL peut être obtenu gratuitement via LetsEncrypt ou fourni par l'Active Directory de votre réseau local.

MercatorPenguinServer peut être utilisé pour offrir un accès simultané à différents Mercator. Pour cela, MercatorPenguinServer doit disposer d'un ou plusieurs fichiers de configuration, placé dans le sous-répertoire App_Data, dont le nom est composé comme suit :

  • le nom du fichier doit être le nom de la configuration qui sera renseignée dans les paramètres de connexion de MercatorPenguin
  • son extension est toujours .ini

Le fichier doit avoir un contenu dont la structure est identique au fichier fourni par défaut : config.ini

Il doit être complété comme suit :

  • MainDir : répertoire contenant le Mercator auquel il faut se connecter. Attention : ce répertoire doit être un répertoire local. En effet, un service Windows ne peut voir les répertoires distants.
  • Dossier : identifiant du dossier si ce Mercator contient une gestion multi-dossiers. Si tel n'est pas le cas, ce paramètre doit être laissé à blanc.
  • SecretPhrase : phrase secrète qui sera utilisée pour le cryptage et le hashage des communications entre MercatorPenguin et le serveur. Cette phrase doit être indiquée dans les paramètres de connexion de MercatorPenguin. Nous recommandons d'utiliser une phrase suffisamment forte et d'éviter celles comme "1234", "Secret", ...
  • MaxRows : un utilisateur sur mobile ne peut pas recevoir un catalogue de 30.000 articles. Il ne pourra les parcourir et il est probable que son portable ne pourra contenir toute cette information en mémoire. Les jeux de données renvoyés à l'utilisateur doivent donc être limités en terme de nombre d'enregistrements. Ce nombre maximal d'enregistrements est renseigné ici. Valeur recommandée = 50
  • AdDomain et AdGroup : nous recommandons avec insistance l'utilisation de l'authentification sur la base d'Active Directory. Si tel est bien le cas, il faut spécifier ici, respectivement le domaine (mydomain.local) et le groupe auquel doit appartenir l'utilisateur pour avoir accès à ce Mercator et/ou à ce web service. Si ces options sont à blanc, alors les utilisateurs seront authentifiés sur base du login et du mot de passe encodés dans Mercator. Cette dernière option est déconseillée.

 

Le fichier web.config ou appsettings.json présent dans le répertoire root contient les paramètres suivants :

  • DaysLogs : nombre de jours pendant lesquels il faut maintenir les fichiers de log. Lors du démarrage du web service, les fichiers log plus anciens sont automatiquement supprimés. Si on souhaite désactiver cette suppression automatique, il faut indiquer la valeur zéro. Valeur par défaut = 30 jours.
  • IpBlockerNbr : nombre de logins infructueux maximal, au delà duquel l'adresse IP de l'utilisateur est black-listée pendant le délai indiqué ci-dessous. Valeur par défaut = 10.
  • IpBlockerMin : nombre de minutes pendant lesquelles sera bloquée une adresse IP pour laquelle le nombre de logins infructueux a dépassé le paramètre précédent. Valeur par défaut = 15 minutes.
  • JpegCompression : paramètre de compression pour les images rendues par ShowImage.ashx. Valeur par défaut = 50.

Pourquoi l'infrastructure proposée par MercatorPenguinServer est-elle fiable en matière de sécurité ?

  • Les échanges sont pris en charge par le protocole HTTPS. Cela assure un cryptage des communications et rend impossible l'interception de données "en clair".
  • Chaque requête n'est acceptée par MercatorPenguinServer que si des headers http bien spécifiques sont présents.
  • Ces headers consistent notamment en un échange d'une clé de hashage et d'un jeton à usage unique qui attestent que l'expéditeur du message est bien MercatorPenguin.
  • Le jeton fait partie de ce scénario de calcul du hashage, ainsi qu'une phrase secrète, propre à chaque configuration et inconnue du code de MercatorPenguin ainsi que de MercatorPenguinServer.
  • MercatorPenguinServer dispose d'un système permettant de bloquer temporairement des adresses IP envoyant plusieurs requêtes avec des clés/jetons incorrects ou tentant de valider des crédentiales incorrectes.
  • Les requêtes SQL à exécuter ne sont jamais envoyées du mobile vers MercatorPenguinServer. Ce dernier utilise toujours les versions originales qu'il trouve dans Mercator. De plus, toutes les requêtes SQL utilisent exclusivement des paramètres SQL. Ces deux points rendent strictement impossible toute injection SQL.

 


Uniquement pour le framework .net 4.8

Si l'erreur HttpStatusCode=NotFound est rencontrée dans l'application mobile (et seulement dans ce cas), il faut ajouter ces lignes dans le fichier web.config juste avant </system.webServer>

<handlers>
<add name="ApiURIs-ISAPI-Integrated-4.0"
      path="/api/*"
      verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS"
      type="System.Web.Handlers.TransferRequestHandler"
      preCondition="integratedMode,runtimeVersionv4.0" />
</handlers>

 


Si l'erreur HttpStatusCode=Forbidden est rencontrée dans l'application mobile (avec "Security headers error 3" dans le fichier log), il faut vérifier la phrase secrète.
En effet, celle-ci est case sensitive.


Versions

  • 12/12/2017 : v 1.0.1 : amélioration multi-threading au niveau de l'écriture des logs
  • 29/05/2018 : v 2.0.0 : compatible avec MercatorPenguin 2.0
  • 28/06/2018 : v 2.1.0 : compatible avec MercatorPenguin 2.1
  • 18/09/2018 : v 2.2.0 : compatible avec MercatorPenguin 2.2
  • 03/10/2018 : v 2.2.1 : compatible avec MercatorPenguin 2.2.1
  • 13/10/2018 : v 2.2.1.1 : bug fixing calcul ItemsSource des EditPickers
  • 20/10/2018 : v 2.2.1.2 : bug fixing création fiche signalétique si pas de valeur par défaut + compatibilité compilation via Roslyn des rapports
  • 23/10/2018 : v 2.2.1.3 : prise en compte de l’événement PenguinServerBeforeValidateData de la classe MercatorUi.Sig.Sig  Mise à jour de tous les Mercators nécessaire !
  • 22/11/2018 : v 2.2.1.4 : prise en compte de l’événement PenguinServerBeforeValidateData du BillingEngine et de l'ActionEngine  Mise à jour de tous les Mercators nécessaire !
  • 22/11/2018 : v 2.2.1.5 : initialisation différée d'instance de MercatorUi.Main en cas d'erreur au démarrage, soit via la page de maintenance, soit à la prochaine sollicitation de cette instance + dans la page de maintenance, prise en compte des modifications apportées dans les fichiers ini.
  • 07/12/2018 : v 2.2.2 : compatible avec MercatorPenguin 2.2.2
  • 09/12/2018 : v 2.2.2.1 : mise à jour automatique des assemblies et des fichiers SQL à distribuer avant démarrage de l'instance
  • 11/12/2018 : v 2.2.2.2 : correction erreur SQL lors de la sauvegarde de signalétique, relative à @current_modiftag
  • 31/01/2019 : v 2.3.0 : compatible avec MercatorPenguin 2.3 (SumUp)
  • 19/02/2019 : v 2.4.0 : compatible avec MercatorPenguin 2.4 (signatures)
  • 16/03/2019 : v 2.4.0.1 : ReqSql dans SearchPickers
  • 02/05/2019 : v 2.5.0 : RunDocumReport : tenir compte de l'utilisateur 
  • 09/05/2019 : v 2.5.1 : compatible avec MercatorPenguin 2.5 (virtual scan)
  • 11/05/2019 : v 2.5.2 : corr. bug sous iOS "Default constructor not found for type System.Array"
  • 25/10/2019 : v 2.6.0 : compatible avec MercatorPenguin 2.6.0  Mise à jour de tous les Mercators nécessaire !
  • 04/11/2019 : v 2.6.1 : envoi de notifications : exclure les utilisateurs non repris dans penguin_players
  • 10/01/2020 : v 2.6.2 : fixer le paramètre MaxRows par requête SQL
  • 11/01/2020 : v 2.7.0 : compatibilité avec MercatorPenguin 2.7
  • 22/06/2020 : v 2.8.0.10 : compatibilité avec MercatorPenguin 2.8  Mise à jour de tous les Mercators nécessaire !
  • 28/06/2020 : v 2.8.0.11 : bug fixing billing licensing
  • 01/07/2020 : v 2.8.0.12 : bug fixing Maintenance.aspx
  • 09/07/2020 : v 2.8.0.13 : bug fixing billing si options LOT ou MPLACE absentes
  • 19/08/2020 : v 2.8.0.14 : bug fixing Maintenance.aspx (disabling device)
  • 21/09/2020 : v 2.9.0 : compatibilité avec MercatorPenguin 2.9  Mise à jour de tous les Mercators nécessaire !
  • 07/10/2020 : v 2.9.1 : recherche article : optimisation via options N_BARCODE et RECH_S_ID
  • 25/11/2020 : v 2.9.3 : compatibilité avec MercatorPenguin 2.9.3  Mise à jour de tous les Mercators nécessaire !
  • 09/12/2020 : v 2.9.4 : compatibilité avec MercatorPenguin 2.9.4
  • 13/01/2021 : v 2.9.5.0 : compatibilité avec MercatorPenguin 2.9.5  Mise à jour de tous les Mercators nécessaire ! 
  • 18/01/2021 : v 2.9.5.1 : correction bug inventaires & transferts de dépôts
  • 19/03/2021 : v 2.9.5.2 : compatibilité avec MercatorPenguin 2.9.6
  • 07/04/2021 : v 2.9.7.0 : compatibilité avec MercatorPenguin 2.9.7
  • 07/06/2021 : v 2.9.7.1 : correction comptabilisation des devices (ne plus tenir compte de l'utilisateur)
  • 09/09/2021 : v 2.9.8.0 : compatibilité avec MercatorPenguin 2.9.8  Mise à jour de tous les Mercators nécessaire !
  • 26/10/2021 : v 2.9.9.0 : compatibilité avec Mercator 10.10
  • 22/11/2021 : v 2.9.10.0 : compatibilité avec MercatorPenguin 2.9.9  Mise à jour de tous les Mercators nécessaire !
  • 07/12/2021 : v 2.9.11.0 : compatibilité avec MercatorPenguin 2.9.11  Mise à jour de tous les Mercators nécessaire !
  • 02/02/2022 : v 2.10.0.0 : compatibilité avec MercatorPenguin 2.10.0  Mise à jour de tous les Mercators nécessaire !
  • 21/03/2022 : v 2.10.0.1 : toujours exécuter InitReporting lors de l'initialisation d'instance
  • 06/04/2022 : v 2.10.0.2 : prise en compte de l'event BillingEngine.PenguinServerHandlingReqSql2  Mise à jour de tous les Mercators nécessaire !
  • 17/05/2022 : v 2.10.0.3 : corr. disponible article à emplacement, si hors emplacement
  • 21/06/2022 : v 2.10.6 : compatibilité avec MercatorPenguin 2.10.6  Mise à jour de tous les Mercators nécessaire !
  • 29/06/2022 : v 2.10.7 : corr. compatiblité lots et inventaires
  • 22/07/2022 : v 2.10.9 : compatibilité avec MercatorPenguin 2.10.9 + certificats SQL SSL  Mise à jour de tous les Mercators nécessaire !
  • 18/10/2022 : v 2.10.13 : compatibilité avec MercatorPenguin 2.10.13
  • 01/12/2022 : v 2.10.15 : corr. upload de fichiers SQL depuis les actions
  • 04/12/2022 : v 2.10.16 : compatibilité avec MercatorPenguin 2.10.16 : warning dans TargetSig
  • 13/12/2022 : v 2.10.17 : IXmlDocumentUpdaterWithContextInfo peut aussi agir sur XamlListViewCell des documents en modification
  • 17/12/2022 : v 2.10.18 : remplir C_IDCOMPTA et F_IDCOMPTA des nouveaux clients/fournisseurs
  • 20/12/2022 : v 2.10.19 : corr. possible erreur "Value cannot be null" dans RunSql
  • 01/05/2023 : v 2.10.20 : compatibilité avec Mercator 11.0
  • 15/05/2023 : v 2.10.21 : remplacement de System.Windows.Forms.DataVisualization.Charting (voir cette page)
  • 21/07/2023 : v 2.10.22 : compatibilité avec MercatorPenguin 2.10.22 : picking avancé
  • 12/09/2023 : v 2.10.23 : générer les duplicatas PDF
  • 20/09/2023 : v 2.10.24 : compatibilité avec MercatorPenguin 2.10.24 : EditActionRights  Mise à jour de tous les Mercators nécessaire !
  • 19/10/2023 : v 2.10.25 : compatibilité avec MercatorPenguin 2.10.25 : Ne pas réappliquer client/fournisseur s'il ne change pas dans les documents
  • 15/11/2023 : v 2.10.25.1 : Correction exception sur context.Exception.TargetSite
  • 05/12/2023 : v 2.10.26 : compatibilité avec MercatorPenguin 2.10.26 : EditEntry hiérarchisé personnalisé + Picking : Commentaire sur les lignes pickées + Tenir compte de BLOCK_SOMMEIL et BLOCK_NONDISPO  Mise à jour de tous les Mercators nécessaire !

Voir aussi : Procédure pour la mise à jour de MercatorPenguinServer

Mettre en place un certificat LetsEncrypt

1) Installer le web service comme indiqué dans cette page. Assurez-vous que l'url http://penguin.domain.com/testprocess.ashx renvoie bien "OK". Si c'est le cas, votre web service est démarré et fonctionnel. Si ce n'est pas le cas, corrigez la configuration avant de passer à l'étape suivante. Ne rien paramétrer manuellement en ce qui concerne la liaison à HTTPS.

2) Le port 80 (http) doit être ouvert et dirigé vers ce serveur.

3) Télécharger le client letsencrypt-win-simple depuis https://www.win-acme.com/

4) Exécuter letsencrypt.exe. Si c'est la première fois, accepter la licence et saisir une adresse email susceptible de recevoir des éventuels avertissements quant à l'expiration du certificat.

5) Dans l'invite, saisir le n° du site correspondant à penguin.domain.com.

6) S'il s'agit du premier certificat demandé, confirmer la création d'une tâche dans le "planificateur de tâches" de Windows, qui assurera le renouvellement automatique du certificat tous les 60 jours. Il faut s'assurer de bien spécifier les crédentiales d'un compte administrateur pour l'exécution de cette tâche.

7) Tester l'url https://penguin.domain.com/testprocess.ashx 

Let's Encrypt

Mettre en place un certificat fourni par l'Active Directory local

Il est possible d'utiliser un certificat SSL produit par l'Active Directory du réseau local. Cela induit deux limites qu'il faut bien comprendre :

  • si le nom commun du certificat correspond à un nom local (par ex. myserver.mydomain.local), il sera nécessaire de mettre en place un VPN afin qu'un mobile utilisé en dehors du réseau local puisse atteindre le serveur 
  • le certificat SSL ne sera pas approuvé par défaut. Il est nécessaire de déployer le certificat CA (certificate authority) du contrôleur de domaine. Notez que ce point peut être vu comme une sécurité supplémentaire, puisque seuls les appareils ayant reçu ce certificat CA auront accès à ce MercatorPenguinServer.

 

Si le certificat SSL existe déjà et contient un nom commun qui convient (typiquement myserver.mydomain.local)

Il n'est pas nécessaire de faire une demande de certificat supplémentaire. Ce certificat est directement visible dans les liaisons (bindings) de IIS. Il peut être directement utilisé. Le point suivant peut donc être ignoré.

S'il faut demander un certificat

  • Sur le serveur hébergeant IIS, exécuter mmc et ajouter le composant enfichable "Certificats" en choisissant "Ordinateur"
  • Développer le nœud "Personnel / Certificat" et via clic-droit : "Toutes les tâches / Opérations avancées / Créer une demande personnalisée"
  • Cliquer "Suivant" jusqu'à l'étape qui permet de choisir le modèle de certificat : sélectionner "Server Web"
  • A l'étape suivante, cliquer sur "Détails" et ensuite "Propriétés"
  • Dans le cadre du haut : ajouter sous "nom commun" le nom qui sera utilisé comme host
  • Dans le cadre du bas : ajouter ce même host en tant que "DNS"
  • Dans le second onglet, indiquer un nom convivial (libre) qui permettra de reconnaître le certificat
  • Terminer en produisant un fichier de certifcate request
  • Sur le serveur contrôleur de domaine, exécuter certreq et importer le certifcate request. Cela produira le certificat demandé.
  • Enfin, retourner dans les certificats du serveur IIS et importer dans le nœud "Hébergement web / certificats" ce nouveau certificat.
  • Ce certificat est à présent disponible dans les liaisons (bindings) de IIS.

 

Dans les deux cas, il faut déployer le certificat CA du contrôleur de domaine

  • Exécuter mmc et ajouter le composant enfichable "Certificats" en choisissant "Ordinateur"
  • Étendre le nœud "Autorités de certifications..."
  • Localiser le certificat correspondant à votre serveur contrôleur de domaine local
  • Via clic-droit / toutes les tâches, l'exporter. Attention : en aucun cas, il ne faut exporter la clé privée. (Par défaut, cette clé n'est pas exportable)
  • Le fichier produit devra être déployé dans tous les appareils mobiles. Il est, par exemple, possible de l'envoyer par mail. (Ce certificat ne contient aucune donnée confidentielle et ne peut être utilisé pour signer d'autres certificats, puisque la clé privée associée n'a pas été exportée).
  • Il faut cliquer sur le certificat présent dans le mail et accepter l'installation.
    • Sous Android, il faut encoder le code de l'appareil ainsi qu'un nom de certificat (libre).
    • Attention : sous iOS, il faut ensuite approuver ce certificat via Réglages > Général > Informations > Réglages des certificats. Sous « Activer la confiance totale pour les certificats racine », activer l’option associée au certificat.