SASKIA.H2R (NetFramework)

Voraussetzungen#

Ausführliche Informationen zu Systemvoraussetzungen finden sie hier.

Installation IIS Webserver#

Klicken sie in der Systemsteuerung auf Windows-Features aktivieren oder deaktivieren.

Wählen sie im Anschluss im erscheinenden Dialog Assistent zum Hinzufügen von Rollen und Features die "Rollenbasierte oder featurebasierte Installation als Installationstyp aus und Klicken sie auf Weiter.

Aktivieren sie im Dialogschritt Serverrollen die folgenden Webserver (IIS) - Rollen:

Im Dialogschritt Features aktivieren sie bitte die folgenden Optionen:

Schließen sie den Dialog durch Betätigen von Installieren ab.

Im Windows Server Manager ist anschließend der Eintrag IIS verfügbar.

Nach der Installation der notwendigen Features können sie den IIS Manager per Rechtsklick auf dem entsprechend aufgelisteten Webserver aufrufen.

Damit ist die Installation von IIS für den Betrieb von H2R abgeschlossen

Installation Powershell Remoting Dienst#

Zur Durchführung des OnlineUpdates wir der Dienst Windows-Remoteverwaltung (WS-Verwaltung) benötigt.

Sie können diesen Dienst über folgenden Befehl in der Powershell direkt installieren.

Enable-PSRemoting

Weiterführende Informationen erhalten sie hier.

Installation H2R Anwendung#

Öffnen sie den IIS Manager und erstellen sie einen neuen Anwendungspool H2R mit den folgenden Einstellungen

Name: H2R
.Net CLR-Version: verfügbare .Net CLR-Version auswählen
verwalteter Pipelinemodus: Integriert
Anwendungspool sofort starten: Aktiviert

Setzen sie anschließend in den erweiterten Einstellungen des Anwendungspools H2R den Eintrag Benutzerprofil laden auf True. Der korrekte Eintrag ist essenziell für die Realisierung des PDF Druckes mit Hilfe des IIS Servers.

Die H2R Anwendung muss nun als Website angelegt und dem Anwendungspool H2R zugeordnet werden. Klicken sie dafür mit der rechten Maustaste auf den Punkt Sites und wählen sie anschließend Website hinzufügen

Folgende Angaben sind zu hinterlegen:

Sitename: H2R
Physischer Pfad: D:\H2R (Bei Bedarf anpassen)
Bindung Typ: HTTP
Bindung Port: 80

Kopieren sie nun den Inhalt des durch das Saskia OnlineUpdates bereitgestellten Ordners H2R in den Ordner der zuvor erstellten Website.

In unserem Beispiel sollte der Ordner D:\H2R wie folgt aussehen:

Hinweis

Die Datei wisej-server.lic wird beim ersten Start der Anwendung erstellt und prüft den hinterlegten Wisej.LicenseKey in der Web.config auf Gültigkeit. Für diese Anfrage muss der IIS Prozess per Webrequest mit der Adresse http://license.wisej.com/ kommunizieren können. Notwendige Proxyeinstellung für diese Verbindung können sie in der Web.config unter system.net.DefaultProxy hinterlegen.

Für den erstellten Ordner müssen je nach Sicherheitsrichtline volle Lese- und Schreibrechte für den Anwender IIS_IUSRS eingerichtet werden.

Im Anschluss sollte die H2R-Anwendung im Browser über die Serveradresse aufrufbar sein:

Datei- und Ordnerstruktur#

Im folgenden Abschnitt werden die Datei- und Ordnerstruktur von H2R auf dem Webserver erläutert.

Ordner/Datei	Beschreibung
bin	Der bin-Ordner enthält den ausführbaren Programmcode von H2R sowie Übersetzungen/Lokalisierungen
Default.html	enthält den Einstiegspunkt der Anwendung, wird beim Aufruf der URL geladen
Defaullt.json	enthält Grundeinstellungen der H2R Webanwendung, z.B. Sessiontimeout oder verwendetes Theme
Web.config	enthält IIS Konfigurationsangaben für die H2R Anwendung
central.config	enthält die zentrale Konfiguration der mit H2R verbundenen Dienste (WCF)
sql.config	enthält die für H2R zur Verfügung stehenden Datenbankverbindungsinformationen

Konfigurationsdateien#

Im folgenden Abschnitt werden die verschiedenen H2R-Konfigurationsdateien aufgelistet und beschrieben.

Web.configDefault.jsonsql.config

Mit Hilfe der Web.config Datei können IIS Anwendungen konfiguriert werden. Eine ausführliche Beschreibung der möglichen Einstellungen entnehmen sie bitte der offiziellen Windows Dokumentation.

<?xml version="1.0"?>
<configuration>
    <appSettings>
        <add key="Wisej.LicenseKey" value="ba2afe0be26448cb248b884ddf204fe3" />
        <add key="Wisej.DefaultTheme" value="saskia" />
        <add key="dbname" value="myDatabaseName" />
        <add key="configFile" value="central.config" />
        <add key="replication" value="false" />
    </appSettings>
    <system.net>
        <defaultProxy>
                <proxy autoDetect="false" bypassonlocal="true" proxyaddress="http://proxy.example.de:80" />
        </defaultProxy>
    </system.net>
    <system.web>
        <globalization requestEncoding="utf-8" responseEncoding="utf-8" />
        <httpRuntime targetFramework="4.8" maxRequestLength="1048576" />
        <httpModules>
            <add name="Wisej" type="Wisej.Core.HttpModule, Wisej.Framework" />
        </httpModules>
    </system.web>
    <system.webServer>
        <validation validateIntegratedModeConfiguration="false" />
        <handlers>
            <add name="wisej" verb="*" path="*.wx" type="Wisej.Core.HttpHandler, Wisej.Framework" />
        </handlers>
        <security>
            <requestFiltering>
            <requestLimits maxAllowedContentLength="1073741824" />
            </requestFiltering>
        </security>
        <defaultDocument enabled="true">
        <files>
            <add value="Default.html" />
        </files>
        </defaultDocument>
    </system.webServer>
</configuration>

Konfigurationskey	Beschreibung
appSettings.Wisej.LicenseKey	enthält die Lizenz zum Starten der Anwendung auf einem Webserver. Die Lizenz wird von Saskia bereitgestellt
appSettings.Wisej.DefaultTheme	enthält den Namen des Standardthemes
appSettings.dbname	Beim Starten von H2R muss sich das System direkt mit einer vorhandenen Datenbank verbinden. Hier geben sie den Namen dieser Datenbank an
appSettings.configFile	Angabe des Dateipfades zur central.config
appSettings.replication	Parameter muss aus Kompatibilitätsgründen immer auf false gesetzt werden
system.net.defaultProxy	Angabe des Proxies zur Lizenzabfrage Wisej, wenn Server hinter einem Proxy betrieben wird

In dieser Anwendungskonfigurationsdatei kann das Verhalten der Webanwendung H2R beeinflusst werden. Eine ausführliche Beschreibung der Einstellungen finden sie hier

//
// Application Configuration:
//
// All settings are optional.
//
// startup:                    Full name of the startup method. i.e. "MyApp.Program.Main, MyApp".
// mainWindow:                 Full name of a view (Page or Form) created automatically at startup. i.e. "MyApp.MainView, MyApp".
// theme:                      Name of the theme, without the extension, to load at startup.
// url:                        Destination URL. If null, the request must match a web page.
// allowedRoutes:              Allows the application to handle different Url routes, separated by a semicolon. i.e. "api;admin;query/users".
// culture:                    The default culture of the application. Default: "auto" (detects the culture from the browser.)
// rightToLeft:                Enables or disables Right to Left mode: true, false or auto. Default: "auto".
// sessionTimeout:             Timeout of the session in seconds. Default: 120. Minimum: 60. Disable: 0.
// responseTimeout:            Timeout of the Wisej requests in seconds. Default: 300. Minimum: 300.
//                             Increase this value if you expect your application to process long running requests.
// pollingInterval:            Interval for the automatic polling of the server in milliseconds. Default: 0 (disabled). Minimum: 1000.
//                             This option is ignored for WebSocket connections.
// autoReload:                 When true, the application is automatically reloaded when the session expires or Application.Exit() is called. Default: false.
// secure:                     Forces the client to use SSL. Default: false.
// showLoader:                 Loads the wisej ajax loader. Default: true.
// loaderTimeout:              Timeout before the appearance of the Ajax loader in milliseconds. Default: 5000. Minimum: 1000. Disable: 0.
// browserCheck:               Custom expression to validate the browser, i.e. "navigator.platform == 'Win32'".
// enablePWA:                  Enables PWA mode in browsers that support it. Default: false.
// offlineUrl:                 URL to navigate to when the client loses connectivity with the application. Default: "".
// notSupportedUrl:            URL of the not-supported page. Wisej will redirect here when the browser is not supported. Default: 'resource.wx/Wisej.Framework/NotSupported.html'
// notAvailableUrl:            URL of the not-available page. Wisej will redirect here when the server cannot accept any more sessions. Default: 'resource.wx/Wisej.Framework/NotAvailable.html'
// debug:                      Enables logging on the client browser console. Default: false.
// enableWebSocket:            Enables the user of WebSocket if available. Default: true.
// enableWebSocketCompression: Enables compression of incoming WebSocket data. Default: true.
// maxSessions:                Maximum number of active sessions (users) before redirecting to notAvailableUrl. Default: -1 (unlimited).
// maxModalStack:              Maximum number of nested modal dialogs. Default: 10.
// dropDuplicateClicks:        Drops all "execute" (clicks) events while there is a pending request. Touch and mouse clicks are still queued and will be executed. Default: false.
// disableClientObjectModel:   Disables the creation of the JavaScript object model on the client.
// validateClient              Verifies the client fingerprint when retrieving a session. Default: true.
// impersonate:                Set impersonate:true to impersonate the user on the server. Default: false.
// threadPool:                 Configures the thread pool without having to modify the machin.config file.
//                             All values are optional. i.e. {minWorkerThreads:100}. Default: null.
// options:                    Map of platform options. i.e. {"automation.mode": true, "mobile.mode": true, ...}.
// settings:                   Map of custom application settings. i.e. {jquery: "http://cdn...", rootPath: "c:\\users\\...", ...}.
//                             Custom settings are available using Application.Configuration.Settings.
{
    "url": "Default.html",
    "theme": "saskia",
    "options": { "mobile.mode": true },
    "startup": "SIS.H2r.Program.Main, SIS.H2r",
    "showLoader": false,
    "autoReload": true,
    "sessionTimeout":  600,
}

Warnung

Im aktuellen Entwicklungsstand kann die H2R-Anwendung nur mit SQL Server Datenbanken verbunden werden. Die Oracle-Anbindung wird bis zur Veröffentlichung von H2R implementiert.

Für den Connection String sind alle gültigen SQL Server- Varianten möglich. Details entnehmen sie bitte der offiziellen Microsoft-Dokumentation oder der Knowledge Database unter https://www.connectionstrings.com/sql-server/

<databases>
    <database name="MyDatabase>
        <provider name="Sql" namespace="System.Data.SqlClient" assembly="" brand="31" />
        <autocommit value="false" />
        <named_parameters value="true" prefix="@" />
        <multiple_connections value="false" />
        <null_empty_strings value="true" />
        <connection_string value="Data Source=my.domain.de;Initial Catalog=MyDatabase;MultipleActiveResultSets=True;pooling=false;" />
        <mars_supported value="true" />
        <custom_properties>
            <add name="dbu" value="SgRP9RTtNZpQvnKEH13kLiz0jmB7yX7XnrMEF7qz3p8=" />
        </custom_properties>
    </database>
</databases>

HTTPS Kommunikation aktivieren#

Um für die H2R-Anwendung eine verschlüselte Kommunikation zwischen Webbrowser und IIS Server zu erreichen, gehen sie bitte wie folgt vor:

Markieren sie im IIS-Manager ihre Website/Applikation und öffnen sie per Rechtsklick den Kontextmenüeintrag Bindungen bearbeiten

Es werden nun die vorhandenen Bindungen angezeigt. Über die Schaltfläche Hinzufügen können neue Bindungen hinzugefügt werden.

Folgende Angaben sind zu hinterlegen:

Bindung Typ: HTTPS
Bindung Port: 443
SSL-Zertifikat: verfügbares CA-Zertifikat oder Domainenzertifikat wählen

Domainenzertifikat erstellen#

In diesem Abschnitt beschreiben wir die Aktivierung von HTTPS für die H2R Anwendung über ein Domainenzertifikat.

Hinweis

Die Erstellung und Einrichtung CA-signierter Zertifikate ist nicht Bestandteil dieser Dokumentation.

Der H2R Server ist im Regelfall nur im internen Netz erreichbar. Kann daher kein CA-signiertes Zertifikat erstellt werden, empfehlen wir die Verwendung eines sogenannten Domänenzertifikats. Vorteilhaft sind dabei die Kostenerstarnis bei der Ausstellung von Zertifikaten und die einfache Bereitstellung.

Um ein Domainenzertifikat zu erstellen gehen sie bitte wie folgt vor:

Öffnen sie im IIS Manager den Dialog Serverzertifikate

Klicken Sie anschließend im Fenster Aktionen auf Domänenzertifikat erstellen.

Im Dialog tragen sie nun die Zertifikatsinformationen für ihren spezifischen Standort ein. Im Feld Gemeinsamer Name müssen Sie den vollständig qualifizierten Domänennamen des H2R Servers eingeben, beispielsweise `server.meine-domain.de.

Nach Eingabe der Daten geben sie im Folgedialog bitte ihre Online-Zertifizierungsstelle an.

Schließen sie die Domainzertifikatserstellung durch Betätigen der Schaltfläche Fertig stellen ab.

Strict Transport Security (HSTS)-Unterstützung aktivieren#

Hinweis

IIS unterstützt mehrere Möglichkeiten, um eine sichere Übertragung mittels HTTPS zu erzwingen. Eine komplette Beschreibung finden sie hier.

IIS 10.0 bietet ab Version 1709 Native HSTS-Unterstützung. Aktivieren sie diese Einstellung im ISS Manager, in dem sie ihre Website auswählen und im Aktionsmenu HSTS auswählen:

Folgende Angaben sind zu hinterlegen:

Aktivieren: Ja
Max Age: 31536000
IncludeSubSomains: Ja (wenn Anwendung nicht über Subdomain auf dem Server genutzt wird)
HTTP an HTTPS umleiten

Der Webserver liefert dann die korrekten Antwort-Header zurück, die sie über die Browser Console einsehen können. Damit ist HSTS korrekt für ihre H2R-Anwendung eingerichtet.

Subdomain-Handling

Prüfen sie ihre individuellen URL-Rewrite Regeln im Zusammenspiel mit HSTS, um ein korrektes Redirect-Verhalten zu erreichen. Die Einstellungsmöglichkeiten sind hier detailliert dokumentiert.

Wndows Authentifizierung (SSO Single Sign On) aktivieren#

Klicken sie in der Systemsteuerung auf Windows-Features aktivieren oder deaktivieren.

Wählen sie im Anschluss im erscheinenden Dialog Assistent zum Hinzufügen von Rollen und Features die "Rollenbasierte oder featurebasierte Installation als Installationstyp aus und Klicken sie auf Weiter.

Aktivieren sie im Dialogschritt Serverrollen die Webserver (IIS) - Rolle Windows-Authentifizierung.

Hinweis

Starten sie anschließend den IIS Dienst in der Dienstverwaltung neu

Im IIS Manager steht nun unter dem Punkt Authentifizierung die Option Windows-Authentifizierung zur Verfügung, welche sie aktivieren.

Deaktivieren sie zusätzlich die anonyme Authentifizierung, wenn H2R nur für Domain-Anwender erreichbar sein soll.

Als letzten Schritt ergänzen sie folgenden Eintrag in der Web.config ihrer H2R-Installation

    <configuration>
        <system.web>
            <authentication mode="Windows" />
        </system.web>
    </configuration>

Installation von Schriftarten#

Die verfügbaren Mrt-Reports werden auf dem Server im Kontext des konfigurierten ApplicationPool-Anwenders erzeugt. Daher müssen alle benötigten Schriften für diesen Anwender verfügbar gemacht werden. Wir empfehlen die Installation der Schriftart für alle Windows-Anwender. Kopieren sie dafür die Schriftart-Datei auf den Server und wählen nach vorherigem Rechtsklick im Kontextmenü die Option Für alle Benutzer installieren.

Nach der Installation muss der Server zwingend neugestartet werden, damit die neue Schriftart verfügbar wird.

wichtiger Hinweis

Es muss ein Standarddrucker in dem Nutzerprofil des verwendeten App-Pool-Nutzers hinterlegt werden. Beachten sie dabei ihre Domainen-konfiguration und Gruppenrichtlinien!!!!